A Node.js library for the ipdata API. Look up IP addresses for geolocation, threat intelligence, company data, and more.

Requires Node.js 18 or later. Uses the native fetch API with zero HTTP dependencies.

Table of Contents

• Install
• Use
  • Import Library
  • Create an Instance
  • EU Endpoint
  • Lookup
  • Bulk Lookup
• Response Fields
• TypeScript

npm install ipdata

import IPData from 'ipdata';

A named export is also available:

import { IPData } from 'ipdata';

CommonJS:

const { IPData } = require('ipdata');

Create an instance of the IPData class with your API key.

const ipdata = new IPData('<apiKey>');

The library caches up to 4096 responses for 24 hours using an LRU cache by default. You can configure the cache by passing an options object as the second parameter.

const ipdata = new IPData('<apiKey>', {
  max: 1000, // max number of entries
  ttl: 10 * 60 * 1000, // 10 minutes
});

To disable caching, set ttl to 1:

const ipdata = new IPData('<apiKey>', { ttl: 1 });

By default requests are routed to the global endpoint (https://api.ipdata.co). To ensure end-user data stays in the EU, pass the EU endpoint as the third parameter.

import IPData, { EU_BASE_URL } from 'ipdata';

const ipdata = new IPData('<apiKey>', undefined, EU_BASE_URL);

You can also pass any custom base URL:

const ipdata = new IPData('<apiKey>', undefined, 'https://eu-api.ipdata.co/');

Look up the current machine's IP when called with no arguments:

const info = await ipdata.lookup();
// info.ip === '<your ip>'

Pass an IP address to look it up:

const info = await ipdata.lookup('1.1.1.1');
// info.ip === '1.1.1.1'

Return a single field:

const info = await ipdata.lookup('1.1.1.1', 'city');

Return multiple fields:

const info = await ipdata.lookup('1.1.1.1', undefined, ['ip', 'city']);

You can also pass a single object, which is convenient when you only need fields or selectField without specifying an IP.

// Look up your own IP with specific fields
const info = await ipdata.lookup({ fields: ['ip', 'city'] });

// Look up a specific IP with a single field
const info = await ipdata.lookup({ ip: '1.1.1.1', selectField: 'city' });

Look up multiple IP addresses in a single API call:

const info = await ipdata.bulkLookup(['1.1.1.1', '1.0.0.1']);
// info[0].ip === '1.1.1.1'

With field filtering:

const info = await ipdata.bulkLookup(['1.1.1.1', '1.0.0.1'], ['ip', 'city']);

The following fields are available for use with selectField and fields:

ip, is_eu, city, region, region_code, country_name, country_code, continent_name, continent_code, latitude, longitude, asn, company, organisation, postal, calling_code, flag, emoji_flag, emoji_unicode, carrier, languages, currency, time_zone, threat, count

asn — { asn, name, domain, route, type }

company — { name, domain, network, type }

carrier — { name, mcc, mnc }

threat — { is_tor, is_icloud_relay, is_proxy, is_datacenter, is_anonymous, is_known_attacker, is_known_abuser, is_threat, is_bogon, blocklists }

The library is written in TypeScript and exports the following types:

import IPData, { EU_BASE_URL, CacheConfig, LookupParams, LookupResponse } from 'ipdata';