Repository files navigation

Javascript module for Geo IP lookup using Maxmind binary databases (aka mmdb or geoip2).Fastest Maxmind lookup library available - up to17,000% faster than other libraries. Module has 100% test coverage with comprehensive test suite. It natively works with binary Maxmind database format and doesn't require any "CSV - {specific lib format}" conversions as some other modules do. Maxmind binary databases are highly optimized for size and performance so there's no point using other formats.

You might want to usegeolite2 module with free geo databases. Alternatively, free databases available fordownload here. If you need better accuracy you should consider buyingcommercial subscription.

npm i maxmind

importmaxmind,{CityResponse}from'maxmind';constlookup=awaitmaxmind.open<CityResponse>('/path/to/GeoLite2-City.mmdb');console.log(lookup.get('66.6.44.4'));// inferred type maxmind.CityResponseconsole.log(lookup.getWithPrefixLength('66.6.44.4'));// tuple with inferred type [maxmind.CityResponse|null, number]

You can useReader class directly in case if you would want to instantiate it in non-async fashion. Use cases would include receiving a buffer database over network, or just reading it synchronously from disk.

import{Reader}from'maxmind';constbuffer=fs.readFileSync('./db.mmdb');constlookup=newReader<CityResponse>(buffer);constcity=lookup.get('8.8.8.8');const[city2,prefixLength]=lookup.getWithPrefixLength('66.6.44.4');

Supported response types:

- CountryResponse- CityResponse- AnonymousIPResponse- AsnResponse- ConnectionTypeResponse- DomainResponse- IspResponse

Module is fully compatible with IPv6. There are no differences in API between IPv4 and IPv6.

constlookup=awaitmaxmind.open('/path/to/GeoLite2.mmdb');constlocation=lookup.get('2001:4860:0:1001::3004:ef68');

maxmind.open(filepath, [options])

• filepath:<string> Path to the binary mmdb database file.
• options:<Object>
  • cache:<Object> Cache options. Under the bonnet module usestiny-lru cache.
    • max:<number> Max cache items to keep in memory.Default:10_000.
  • watchForUpdates:<boolean> Supports reloading the reader when changes occur to the database that is loaded.Default:false.
  • watchForUpdatesNonPersistent:<boolean> Controls whether the watcher should be persistent or not. If it is persistent, a node process will be blocked in watching state if the watcher is the only thing still running in the program.Default:false.
  • watchForUpdatesHook:<Function> Hook function that is fired on database update.Default:null.

Current module is designed to work in node.js environment. Check outmmdb-lib that's used under the bonnet - it's environment agnostic and does work in browser.

Module supports validation for both IPv4 and IPv6:

maxmind.validate('66.6.44.4');// returns truemaxmind.validate('66.6.44.boom!');// returns falsemaxmind.validate('2001:4860:0:1001::3004:ef68');// returns truemaxmind.validate('2001:4860:0:1001::3004:boom!');// returns false

In case you want to use legacy GeoIP binary databases you should usemaxmind@0.6.

• MMDB library
• MaxMind DB file format specificationhttp://maxmind.github.io/MaxMind-DB/
• MaxMind test/sample DB fileshttps://github.com/maxmind/MaxMind-DB
• GeoLite2 Free Downloadable Databaseshttp://dev.maxmind.com/geoip/geoip2/geolite2/
• Great talk about V8 performancehttps://www.youtube.com/watch?v=UJPdhx5zTaw
• V8 Optimization killershttps://github.com/petkaantonov/bluebird/wiki/Optimization-killers
• More V8 performance tipshttp://www.html5rocks.com/en/tutorials/speed/v8/

MIT