node-geolite2-redist

MaxMind's GeoLite2 free databases as an npm library. As this is a redistribution, you don't need a MaxMind license key. However, some additional legal restrictions apply, make sure to read this README and the Legal Warning carefully before deciding to use this.

You will need a database reader capable of reading .mmdb files, like node-maxmind, if you wish to use the data.

This package is compatible with the 3 GeoLite2 databases, namely:

GeoLite2-ASN
GeoLite2-Country
GeoLite2-City

For more info check out the MaxMind website.

Due to license requirements, this package automatically updates the databases in the background when it detects that a new version is available. This should be transparent for most usecases, if you're experiencing any problem with it, please file an issue.

See Legal Warning section for more info on licensing and limitations.

Usage

Installing

npm install geolite2-redist

Using the geoip data

Example geoip lookup in a Node environment, using the GeoLite2-City database with node-maxmind as a db reader:

Javascript

const maxmind = require('maxmind');

// This module is distributed as en ESM module (import...from... syntax), but you can
// use an import() promise to make it work without switching to ESM!
import('geolite2-redist').then((geolite2) => {
 return geolite2.open(
  'GeoLite2-City',                 // database name
  (dbPath) => maxmind.open(dbPath) // function that builds a useful db reader
  )
}).then((reader) => {
  const lookup = reader.get('185.194.81.29')

  console.log(lookup.country.iso_code) // FR 🥖🇫🇷

  // Calling close() here shuts everything down nicely and clears up Node's event loop.
  reader.close()
})

Typescript

import geolite2, { GeoIpDbName } from 'geolite2-redist';
import maxmind, { CountryResponse } from 'maxmind';

(async () => {
  const reader = await geolite2.open(
    GeoIpDbName.Country, // Use the enum instead of a string!
    (path) => maxmind.open<CountryResponse>(path)
  )

  const lookup = reader.get('185.194.81.29')

  console.log(lookup.country.iso_code) // FR 🥖🇫🇷

  reader.close()
})();

Preloading databases

You can add this to your package.json to preload the databases after running npm install, instead of downloading them the first time open is called:

{
  "scripts": {
    "preload": "node -e \"import('geolite2-redist').then(geolite => geolite.downloadDbs())\""
  }
}

API

You can find a more detailed documentation on the Typedoc-generated website.

Legal Warning

Privacy regulations (CCPA in California, GDPR in Europe) that implement the right-to-forget have affected MaxMind's EULA & licenses. In a nutshell, you should always make sure your GeoIP databases are up to date, which this library conveniently does for you ;)

That said, please carefully read the LICENSE and EULA files. The databases are provided under certain restrictions and obligations, most notably:

You cannot prevent the library from updating the databases.
You cannot use the GeoLite2 data:
- for FCRA purposes in the USA,
- to identify specific households or individuals, worldwide.

If you plan on using node-geolite2 behind a firewall, you need to whitelist the GitHub IP range so that the package can reach the databases mirror.

Compatibility

We follow the OpenJS Foundation's deprecation schedule and support all maintained Node versions.

Alternatives

If you do have a MaxMind license key (which you can get by signing up here), you might prefer using node-geolite2, which this repository is originally a fork of.

License

The databases themselves are provided by MaxMind under CC BY-SA 4.0

For the library, see LICENSE.

This software package includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

GitSquared/node-geolite2-redist