Registry / http-networking / node-ipinfo

node-ipinfo

library4.4.0jsnpmunverified

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.

http-networking data

npm install node-ipinfo

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-IPINFO

node-ipinfo

http-networkingjavascriptv4.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IPinfoWrapper

✓ import { IPinfoWrapper } from 'node-ipinfo';

✗ const { IPinfoWrapper } = require('node-ipinfo');

Use named import for `IPinfoWrapper` in ESM. CommonJS users should use `require` syntax.

IPinfoLiteWrapper

✓ import { IPinfoLiteWrapper } from 'node-ipinfo';

✗ const IPinfoLiteWrapper = require('node-ipinfo').IPinfoLiteWrapper;

For the Lite API client, `IPinfoLiteWrapper` is also a named export. Ensure consistent import style.

Types

✓ import type { IPinfo } from 'node-ipinfo';

TypeScript users can import specific types like `IPinfo` for detailed API response structures.

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.

import { IPinfoWrapper } from 'node-ipinfo'; async function getIpInfo() { const token = process.env.IPINFO_TOKEN ?? ''; // Set your IPINFO_TOKEN environment variable if (!token) { console.error('IPINFO_TOKEN environment variable is not set.'); process.exit(1); } const ipinfoWrapper = new IPinfoWrapper(token); const ipAddress = '8.8.8.8'; // Or process.argv[2] for CLI try { const ipinfo = await ipinfoWrapper.lookupIp(ipAddress); console.log(`IP: ${ipinfo.ip}`); console.log(`City: ${ipinfo.city}`); console.log(`Country: ${ipinfo.country}`); console.log(`Org: ${ipinfo.org}`); console.log(`Location: ${ipinfo.loc}`); } catch (error) { console.error(`Failed to lookup IP ${ipAddress}:`, error); } } getIpInfo();

Debug

Known issues

breakingVersion 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.

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).

affects: >=4.0.0

breakingThe minimum Node.js engine version was increased to 14 due to the `node-fetch` dependency update in v4.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.

affects: >=4.0.0

gotchaAn API token is required for all lookups. Using the library without a valid token will result in API errors.

fix

Sign up for a free IPinfo account at `https://ipinfo.io/signup` and obtain your API token. Pass this token during `IPinfoWrapper` initialization.

affects: >=1.0.0

gotchaThe 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.

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.

affects: >=4.2.0

Errors

Common errors & fixes

Error: Request failed with status code 401

Invalid or missing API token provided to the IPinfoWrapper constructor.

fix

Verify your API token. Ensure it is correctly set as a string when initializing `IPinfoWrapper` or `IPinfoLiteWrapper`.

TypeError: IPinfoWrapper is not a constructor

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.

fix

For ESM, use `import { IPinfoWrapper } from 'node-ipinfo';`. For CommonJS, use `const { IPinfoWrapper } = require('node-ipinfo');`.

ReferenceError: require is not defined in ES module scope

Attempting to use `require` in an ES Module (`.mjs` file or `type: "module"` in `package.json`).

fix

Switch to ES Module import syntax: `import { IPinfoWrapper } from 'node-ipinfo';`.

Upgrade

Version history

4.4.0latest on npm

Audit

Dependencies

node-fetchrequiredInternal dependency for API communication, replaced Node.js's native http(s) module in v4.0.0.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ipinfo/node ↗

packagehttps://www.npmjs.com/package/node-ipinfo ↗

homepagehttps://ipinfo.io ↗