ip-asn-map

NPM | Git | Reference

Maps IP addresses to country and AS info with low memory footprint.

• Uses the data graciously provided by IPtoASN (not included, fetch yourself as necessary).
• Native JS, no dependencies. The update/build code needs Node.js, but the actual IpMap class only uses ArrayBuffer and DataView and can work anywhere.
• Memory usage: a single blob of about 10 MiB optimized for binary search.
• Lookup speed: about 250k lookups/sec or 4 microseconds per lookup on my Ryzen 5600G.
• Zero emojis (although I am holding back), bad grammar, and code with badly named variables and no comments. As if an actual human wasted half a weekend to write and document this by hand. Weirdo.

Warning: the lookup function uses a very naive parser that expects the addresses in the most basic form, 1.2.3.4 or a:b::c:d. If you're dealing with untrusted input, you should probably pass it through a proper parser first.

Command line

Install:

npm install ip-asn-map

Fetch and process the latest dataset, and save it in the package directory:

npx ip-asn-map update
# or
npx ip-asn-map update cache/custom.bin # custom destination

Generate the blob using previously fetched TSV (any of)

npx ip-asn-map parse ip2asn-combined.tsv.gz # save to default location
npx ip-asn-map parse ip2asn-combined.tsv.gz cache/custom.bin
npx ip-asn-map parse ip2asn-combined.tsv cache/custom.bin # can be unpacked
zcat ip2asn-combined.tsv.gz | npx ip-asn-map parse - - > custom.bin # stdio

Lookup an address:

npx ip-asn-map lookup 51.210.240.134
npx ip-asn-map lookup 2001:abad:1dea:: praise.odin

Example output:

{
  family: 4,
  ip: '51.210.240.134',
  int: 869462150,
  as: { number: 16276, country: 'FR', description: 'OVH' },
  range: {
    family: 4,
    first: '51.210.0.0',
    last: '51.210.255.255',
    firstInt: 869400576,
    lastInt: 869466111,
    size: 65536,
    index: 73285
  }
}

Usage

In Node:

import { loadIpMap } from 'ip-asn-map';

const map = await loadIpMap(); // or loadIpMap('custom.bin');
const result = map.lookup('51.210.240.134');
const cc = result.as.country; // 'FR', may be null if the range is not assigned
Copy

In the browser: load the binary to ArrayBuffer and pass it to new IpMap(buffer) – see demo / code

• Full reference
  • IpMap class
    • lookup by string
    • findV4 by integer
    • findV6 by BigInt
  • loadIpMap
  • updateIpMap
  • Helpers:
    • getDefaultIpMapPath
    • encodeIp2AsnStream
    • parseIp2AsnGzip
    • parseIp2AsnStream
• Buffer format

License

Public Domain / CC0