ipdb

IP lookup using IPIP.net database (Node.js & Browser)

Free databases available for download here. If you need better accuracy you should consider buying commercial subscription.

Install

Node.js

$ npm install ipdb

Browser

Via CDN

<script src="https://unpkg.com/ipdb/dist/ipdb.umd.min.js"></script>

Via npm + bundler (Webpack, Vite, etc.)

$ npm install ipdb

Usage

Node.js

Using file path (recommended)

const IPDB = require('ipdb');
const ipdb = new IPDB('./data/ipipfree.ipdb');

const result = ipdb.find('183.62.57.1');
console.log(result);
/*
{
  code: 0,
  data: {
    country_name: '中国',
    region_name: '广东',
    city_name: '广州',
    bitmask: 18,
    ip: '183.62.57.1'
  }
}
*/

Using Buffer

const fs = require('fs');
const IPDB = require('ipdb');

const buffer = fs.readFileSync('./data/ipipfree.ipdb');
const ipdb = new IPDB(buffer);

const result = ipdb.find('183.62.57.1');
console.log(result.data);

Browser

Using Fetch API

// Load database file from server
const response = await fetch('/data/ipipfree.ipdb');
const arrayBuffer = await response.arrayBuffer();

const ipdb = new IPDB(arrayBuffer);
const result = ipdb.find('183.62.57.1');
console.log(result.data);

Using File API (user upload)

<input type="file" id="dbfile" accept=".ipdb">
<script>
document.getElementById('dbfile').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const arrayBuffer = await file.arrayBuffer();

  const ipdb = new IPDB(arrayBuffer);
  const result = ipdb.find('183.62.57.1');
  console.log(result.data);
});
</script>

CDN Usage

<script src="https://unpkg.com/ipdb"></script>
<script>
  fetch('/data/ipipfree.ipdb')
    .then(response => response.arrayBuffer())
    .then(buffer => {
      const ipdb = new IPDB(buffer);
      const result = ipdb.find('183.62.57.1');
      console.log(result);
    });
</script>

ES Module (modern browsers)

<script type="module">
import IPDB from 'https://unpkg.com/ipdb/dist/ipdb.esm.js';

const response = await fetch('/data/ipipfree.ipdb');
const arrayBuffer = await response.arrayBuffer();
const ipdb = new IPDB(arrayBuffer);

const result = ipdb.find('183.62.57.1');
console.log(result);
</script>

API

ipdb = new IPDB(data, [options])

Creates an IPDB instance.

data

Type: string | Buffer | ArrayBuffer | Uint8Array

• Node.js: File path (string) or Buffer
• Browser: ArrayBuffer or Uint8Array (loaded via Fetch/File API)
• Note: File path string is only supported in Node.js environment

options

Type: object

patches

Type: array Default: []

See Patches

ipdb.find(ip, [options])

Lookup IP address geolocation information.

ip

Type: string

IPv4 or IPv6 address

options

Type: object

language

Type: string Default: CN

Language code (e.g., 'CN', 'EN')

patches

Type: array Default: []

Query-specific patch functions. See Patches

Returns

Type: object

• code: number - Status code (0 = success, -1 = error)
• data: object - Geolocation data (only when code is 0)
  • Fields depend on the database (e.g., country_name, city_name, region_name)
• message: string - Error message (only when code is -1)

Patches

• @ipdb/iso3166 - IPIP.net database patches (ISO-3166)
• @ipdb/cac - IPIP.net database patches (中国行政区划代码)
• @ipdb/range - IPIP.net database patches (range of cidr)

Browser Compatibility

This library supports modern browsers with the following features:

• ES6+ (or use a transpiler)
• Typed Arrays (Uint8Array, ArrayBuffer)
• Fetch API or File API (for loading database files)

Tested Browsers

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Bundle Size

• UMD (minified + gzipped): ~2KB
• ESM (minified + gzipped): ~2KB

Note for Older Browsers

For IE11 and other older browsers, please use appropriate polyfills:

• Typed Array polyfill
• Fetch API polyfill
• Promise polyfill

Related

• @ipdb/database - IPIP.net free database
• qqwry.ipdb - 纯真数据库 IPIP.net 格式版

License

MIT © metowolf