IPinfo Node.js Client Library

The library uses an LRU cache by default (5000 items, 1 day TTL). You can provide your own caching implementation by implementing the IPCache interface and passing it to the constructor.

const { IPinfoWrapper, LruCache } = require("node-ipinfo");

const cacheOptions = {
    max: 5000,
    ttl: 24 * 1000 * 60 * 60
};

const cache = new LruCache(cacheOptions);
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", cache);

Install the official IPinfo NodeJS client library using your preferred package manager.

npm install node-ipinfo
# or
yarn add node-ipinfo

You can customize how country names, flags, currencies, and continents are returned by passing an internationalization object to the constructor. This object can include countries, countriesFlags, countriesCurrencies, continents, and euCountries.

const internationalization = {
    countries: { US: "United States" },
    countriesFlags: { US: { emoji: "🇺🇸", unicode: "U+1F1FA U+1F1F8" } },
    countriesCurrencies: { US: { code: "USD", symbol: "$" } },
    continents: { US: { code: "NA", name: "North America" } },
    euCountries: ["FR", "ES", "BE"]
};

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", undefined, undefined, internationalization);

To perform standard IP lookups, initialize an instance of IPinfoWrapper with your IPinfo API access token. This wrapper is suitable for general use cases including Residential Proxy lookups.

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

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");

// Perform a lookup
const ipinfo = await ipinfoWrapper.lookupIp("1.1.1.1");

Use the lookupResproxy method to check if an IP address is a residential proxy.

import { IPinfoWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
const resproxy = await ipinfoWrapper.lookupResproxy("175.107.211.204");
console.log(resproxy.service); // e.g., 'Bright Data'

If you want to use the Lite API, use the IPinfoLiteWrapper. The returned details are slightly different (flatter) than the Core API. Authentication with your token is still required.

import { IPinfoLiteWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoLiteWrapper("MY_TOKEN");
const ipinfo = await ipinfoWrapper.lookupIp("8.8.8.8");
console.log(ipinfo.countryCode);
// US

The IPinfoPlusWrapper provides access to the Plus API, which includes enhanced data such as mobile carrier information and privacy detection (proxy, VPN, Tor).

import { IPinfoPlusWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoPlusWrapper("MY_TOKEN");
const ipinfo = await ipinfoWrapper.lookupIp("8.8.8.8");
console.log(ipinfo.mobile);    // { carrier: ..., mcc: ..., mnc: ... }
console.log(ipinfo.anonymous); // { isProxy: false, isRelay: false, isTor: false, ... }

Use getMap with an array of IP addresses to receive a URL for a generated world map showing those locations.

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

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
const ips = ["1.1.1.1", "8.8.8.8", "1.2.3.4"];

ipinfoWrapper.getMap(ips).then(response => {
    console.log(response); // Returns the map URL
});

The client constructor accepts a timeout parameter in milliseconds. It defaults to 5000 (5 seconds). Setting it to 0 disables the timeout.

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

const timeout = 10 * 1000; // 10 seconds
const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN", undefined, timeout);

To improve performance when looking up multiple IPs, use getBatch. The library automatically chunks operations behind the scenes to handle large inputs.

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

const ipinfoWrapper = new IPinfoWrapper("MY_TOKEN");
const ips = ["1.1.1.1", "8.8.8.8", "1.2.3.4/country"];

ipinfoWrapper.getBatch(ips).then(batch => console.log(batch));

The IPinfoCoreWrapper provides access to the Core API, which includes city-level geolocation with nested geo and as objects.

import { IPinfoCoreWrapper } from "node-ipinfo";

const ipinfoWrapper = new IPinfoCoreWrapper("MY_TOKEN");
const ipinfo = await ipinfoWrapper.lookupIp("8.8.8.8");
console.log(ipinfo.geo); // { city: '...', region: '...', ... }
console.log(ipinfo.as); // { asn: '...', name: '...', ... }

Depending on your subscription tier, you can use specific wrappers to interact with different API endpoints:

• IPinfoLiteWrapper: For Lite API access.
• IPinfoCoreWrapper: For Core API access.
• IPinfoPlusWrapper: For Plus API access.

import { IPinfoLiteWrapper, IPinfoCoreWrapper, IPinfoPlusWrapper } from 'ipinfo';

const lite = new IPinfoLiteWrapper({ token: 'YOUR_TOKEN' });
const core = new IPinfoCoreWrapper({ token: 'YOUR_TOKEN' });
const plus = new IPinfoPlusWrapper({ token: 'YOUR_TOKEN' });