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, additional restrictions apply, and while they should be transparent to most users, you should read this README and the LICENSE file 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 contains 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.
See Warning section for more info.
Usage
Using the geoip data
Example geoip lookup, using the GeoLite2-City
database with node-maxmind
as a db reader:
Async
const geolite2 = require('geolite2-redist');
const maxmind = require('maxmind');
(async () => {
let lookup = await geolite2.open('GeoLite2-City', path => {
return maxmind.open(path);
});
let city = lookup.get('66.6.44.4');
// Call this when done to empty node's event loop
lookup.close();
})();
Sync
const geolite2 = require('geolite2-redist');
const maxmind = require('maxmind');
const fs = require('fs');
let lookup = geolite2.open('GeoLite2-City', path => {
let buf = fs.readFileSync(path);
return new maxmind.Reader(buf);
});
let city = lookup.get('66.6.44.4');
lookup.close();
Advanced usage
If you do not consume the databases directly, or need more flexible methods, the internal geolite2.UpdateSubscriber
class is exposed so you can directly listen to database update events.
Example usage:
const geolite2 = require('geolite2-redist');
function useGeolite() {
// You can retrieve the path to `.mmdb` files
let cityPath = geolite2.paths['GeoLite2-City'];
}
const dbWatcher = new geolite2.UpdateSubscriber();
dbWatcher.on('update', () => {
useGeolite();
});
// Empty event loop when shutting down
dbWatcher.close();
Usage with TypeScript
This package includes its own types and you can pass the response type in open
:
import geolite2 from 'geolite2-redist';
import maxmind, { CityResponse } from 'maxmind';
(async () => {
let lookup = await geolite2.open<CityResponse>('GeoLite2-City', path => {
return maxmind.open(path);
});
let city = lookup.get('66.6.44.4');
// Call this when done to empty node's event loop
lookup.close();
})();
API
Methods
geolite2.open(database, databaseReader)
database
:<string>
One ofGeoLite2-ASN
,GeoLite2-Country
,GeoLite2-City
.databaseReader
:<function>
a function that will build a database reader object (lookup
). Must return aPromise
or an<object>
. Called with two arguments:path
:<string>
The filesystem path to the database.mmdb
file.update
:<boolean>
Will be set totrue
if this is a rebuild following a database update.false
on first run.
Properties
geolite2.paths <object>
Full fs paths for each database. Warning: you need to let the library update the databases automatically, see Usage section.
GeoLite2-ASN
:<string>
GeoLite2-Country
:<string>
GeoLite2-City
:<string>
Classes
geolite2.UpdateSubscriber
Internal class used to automatically update databases, exposed to allow advanced usage without the geolite2.open()
method - see Usage.
- Constructor
- new UpdateSubscriber() Returns
EventEmitter
instance
- new UpdateSubscriber() Returns
- Events
checking
Emitted when automatically checking for database updates.downloading
Emitted when an update has been found and the new databases are being downloaded in the background.update
Emitted when new databases have been written to the filesystem.
- Methods
- checkUpdates() Checks for new database updates and downloads them.
- triggerUpdate() Replaces the current databases with fresh copies from the mirror.
- close() Shuts down the updater.
- Props
downloading
:<boolean>
Whether databases are being downloaded in the background right now - seedownloading
event.
Warning
Please carefully read the LICENSE and EULA files. This package comes with certain restrictions and obligations, most notably:
- You cannot prevent the library from updating the databases.
- You cannot use the GeoLite2 data:
- for FCRA purposes,
- to identify specific households or individuals.
This library's licensing is not suitable for commercial projects distribution.
If you plan on using node-geolite2
behind a firewall, you need to whitelist the raw.githubusercontent.com
IP range for the database updates.
License
See LICENSE.
This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.