{"id":13629,"library":"node-ipinfo","title":"IPinfo Node.js Client Library","description":"The official Node.js client library for the IPinfo.io IP data API. This library allows developers to retrieve comprehensive details for IP addresses, including geolocation (city, region, country, postal code, lat/long), ASN details, company data, and carrier information. The current stable version is 4.4.0. Releases are typically driven by API changes or significant internal improvements, as seen with the v4.0.0 update. Key differentiators include direct integration with the IPinfo.io platform, support for both Core and Lite APIs, and comprehensive data fields beyond basic geolocation. It works with ES5, ES6+, and TypeScript environments, and requires an API token for usage.","status":"active","version":"4.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/ipinfo/node","tags":["javascript","IPinfo","typescript"],"install":[{"cmd":"npm install node-ipinfo","lang":"bash","label":"npm"},{"cmd":"yarn add node-ipinfo","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-ipinfo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency for API communication, replaced Node.js's native http(s) module in v4.0.0.","package":"node-fetch","optional":false}],"imports":[{"note":"Use named import for `IPinfoWrapper` in ESM. CommonJS users should use `require` syntax.","wrong":"const { IPinfoWrapper } = require('node-ipinfo');","symbol":"IPinfoWrapper","correct":"import { IPinfoWrapper } from 'node-ipinfo';"},{"note":"For the Lite API client, `IPinfoLiteWrapper` is also a named export. Ensure consistent import style.","wrong":"const IPinfoLiteWrapper = require('node-ipinfo').IPinfoLiteWrapper;","symbol":"IPinfoLiteWrapper","correct":"import { IPinfoLiteWrapper } from 'node-ipinfo';"},{"note":"TypeScript users can import specific types like `IPinfo` for detailed API response structures.","symbol":"Types","correct":"import type { IPinfo } from 'node-ipinfo';"}],"quickstart":{"code":"import { IPinfoWrapper } from 'node-ipinfo';\n\nasync function getIpInfo() {\n  const token = process.env.IPINFO_TOKEN ?? ''; // Set your IPINFO_TOKEN environment variable\n  if (!token) {\n    console.error('IPINFO_TOKEN environment variable is not set.');\n    process.exit(1);\n  }\n\n  const ipinfoWrapper = new IPinfoWrapper(token);\n  const ipAddress = '8.8.8.8'; // Or process.argv[2] for CLI\n\n  try {\n    const ipinfo = await ipinfoWrapper.lookupIp(ipAddress);\n    console.log(`IP: ${ipinfo.ip}`);\n    console.log(`City: ${ipinfo.city}`);\n    console.log(`Country: ${ipinfo.country}`);\n    console.log(`Org: ${ipinfo.org}`);\n    console.log(`Location: ${ipinfo.loc}`);\n  } catch (error) {\n    console.error(`Failed to lookup IP ${ipAddress}:`, error);\n  }\n}\n\ngetIpInfo();","lang":"typescript","description":"This quickstart initializes the IPinfo client with an API token from an environment variable and performs a lookup for a specific IP address, printing key details."},"warnings":[{"fix":"Review any custom network configurations or dependencies that might conflict with `node-fetch`. Ensure your Node.js environment is compatible with `node-fetch` (Node.js >=14 required).","message":"Version 4.0.0 changed internal API communication from Node.js native http(s) to `node-fetch`. This may impact consumers relying on internal network behavior or require polyfills in certain environments.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your project's Node.js runtime is version 14 or higher. Update `engines.node` in your `package.json` if necessary and upgrade your Node.js installation.","message":"The minimum Node.js engine version was increased to 14 due to the `node-fetch` dependency update in v4.0.0.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Sign up for a free IPinfo account at `https://ipinfo.io/signup` and obtain your API token. Pass this token during `IPinfoWrapper` initialization.","message":"An API token is required for all lookups. Using the library without a valid token will result in API errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the IPinfo documentation for the Lite API vs. Core API data fields. If specific data is missing, you might need to switch to the `IPinfoWrapper` or check your API plan.","message":"The Lite API (`IPinfoLiteWrapper`) provides a slightly different set of returned details compared to the Core API (`IPinfoWrapper`). Ensure you are using the correct client for the data fields you expect.","severity":"gotcha","affected_versions":">=4.2.0"}],"env_vars":null,"search_vec":"'4.4.0':47 'address':26 'allow':18 'api':15,53,80,99 'asn':35 'basic':86 'beyond':85 'carrier':40 'chang':54 'citi':29 'client':3,8 'code':33 'compani':37 'comprehens':22,82 'core':77 'countri':31 'current':43 'data':14,38,83 'detail':23,36 'develop':19 'differenti':66 'direct':68 'driven':51 'environ':95 'es5':91 'es6':92 'field':84 'geoloc':28,87 'improv':58 'includ':27,67 'inform':41 'integr':69 'intern':57 'ip':13,25 'ipinfo':1,104 'ipinfo.io':12,72 'javascript':103 'key':65 'lat/long':34 'librari':4,9,17 'lite':79 'node.js':2,7 'offici':6 'platform':73 'postal':32 'region':30 'releas':48 'requir':97 'retriev':21 'seen':60 'signific':56 'stabl':44 'support':74 'token':100 'typescript':94,105 'typic':50 'updat':64 'usag':102 'v4.0.0':63 'version':45 'work':89","created_at":"2026-04-20T01:55:29.692416+00:00","updated_at":"2026-04-20T01:55:29.692416+00:00","problems":[{"fix":"Verify your API token. Ensure it is correctly set as a string when initializing `IPinfoWrapper` or `IPinfoLiteWrapper`.","cause":"Invalid or missing API token provided to the IPinfoWrapper constructor.","error":"Error: Request failed with status code 401"},{"fix":"For ESM, use `import { IPinfoWrapper } from 'node-ipinfo';`. For CommonJS, use `const { IPinfoWrapper } = require('node-ipinfo');`.","cause":"Incorrect import statement, often mixing CommonJS `require` with ES Modules `import` or vice-versa, or attempting to use a default import for a named export.","error":"TypeError: IPinfoWrapper is not a constructor"},{"fix":"Switch to ES Module import syntax: `import { IPinfoWrapper } from 'node-ipinfo';`.","cause":"Attempting to use `require` in an ES Module (`.mjs` file or `type: \"module\"` in `package.json`).","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://ipinfo.io","github":"https://github.com/ipinfo/node","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-ipinfo","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}