ipdb/readme.md

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

# ipdb [![Build Status](https://travis-ci.com/metowolf/ipdb.svg?branch=master)](https://travis-ci.com/metowolf/ipdb)

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

Free databases available for [download here](https://www.ipip.net/free_download/). If you need better accuracy you should consider buying [commercial subscription](https://www.ipip.net/product/ip.html#ipv4city).


## Install

### Node.js

```bash
$ npm install ipdb
```

### Browser

#### Via CDN

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

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

```bash
$ npm install ipdb
```

## Usage

### Node.js

#### Using file path (recommended)

```js
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

```js
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

```js
// 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)

```html
<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

```html
<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)

```html
<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](#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](#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](https://github.com/metowolf/ipdb-iso3166) - IPIP.net database patches (ISO-3166)
 - [@ipdb/cac](https://github.com/metowolf/ipdb-cac) - IPIP.net database patches (中国行政区划代码)
 - [@ipdb/range](https://github.com/metowolf/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](https://www.npmjs.com/package/@ipdb/database) - IPIP.net free database
 - [qqwry.ipdb](https://www.npmjs.com/package/qqwry.ipdb) - 纯真数据库 IPIP.net 格式版


## License

MIT © [metowolf](https://i-meto.com/)