@proofcodec/geoip

GeoIP lookup in 265 KB — drop-in replacement for geoip-lite.

Uses proof-carrying compression to shrink DB-IP Lite from 68 MB to a single npm package. Zero dependencies, works in Node.js, browsers, and edge runtimes.

Install

npm install @proofcodec/geoip

Usage

import geoip from '@proofcodec/geoip';

const geo = geoip.lookup('8.8.8.8');
// {
//   range: [134744064, 134744319],
//   country: 'US',
//   region: '',
//   eu: '0',
//   timezone: '',
//   city: '',
//   ll: [0, 0],
//   metro: 0,
//   area: 0
// }

Returns null if the IP is not found or invalid.

API

geoip.lookup(ip)

Look up geolocation for an IPv4 address. Returns an object matching the geoip-lite shape, or null.

geoip.pretty(num)

Convert a numeric IP to dotted-quad string.

Why this exists

| | geoip-lite | @proofcodec/geoip | |---|---|---| | Install size | 110 MB | 265 KB | | License key required | Yes (MaxMind) | No | | Edge runtime support | No | Yes | | Startup time | 200ms+ | <1ms | | Data source | MaxMind GeoLite2 | DB-IP Lite |

Edge runtimes

Works on Cloudflare Workers, Vercel Edge, Deno Deploy, and any runtime that supports ESM — no fs dependency, no native modules, no postinstall scripts.

Data source

IP geolocation data by DB-IP, licensed under CC-BY-4.0.

When displaying geolocation results to users, please include attribution:

<a href="https://db-ip.com">IP Geolocation by DB-IP</a>

How it works

A decision tree classifies each /24 IP block by country based on prefix features. A sparse correction table fixes the few blocks where the tree prediction is wrong. Together, tree + corrections achieve 100% accuracy with ~300x compression vs Huffman-optimal encoding.

The compressed format is verified by proofcodec-verify.

License

MIT. See LICENSE for details.

IP data: CC-BY-4.0 (DB-IP Lite). See NOTICE for attribution requirements.