geoip2-lite

GeoIP2-lite
==========

A native NodeJS API for the GeoIP2-Lite data from MaxMind originally written for geoip-lite by Philip Tellis and
modified for GeoIP2-Lite by Chandra Gupta .

This product includes GeoIP2 Lite data created by MaxMind, available from http://maxmind.com/

   

Introduction
------------

MaxMind provides a set of data files for IP to Geo mapping along with opensource libraries to parse and lookup these data files.
One would typically write a wrapper around their C API to get access to this data in other languages (like JavaScript).

GeoIP2-lite instead attempts to be a fully native JavaScript library. A converter script converts the CSV files from MaxMind into
an internal binary format (note that this is different from the binary data format provided by MaxMind). The geoip2 module uses this
binary file to lookup IP addresses and return the country, region and city that it maps to.

Both IPv4 and IPv6 addresses are supported, however since the GeoLite IPv6 database does not currently contain any city or region
information, city, region and postal code lookups are only supported for IPv4.

Philosophy
----------

Philip Tellis was aiming for a fast JavaScript native implementation for geomapping of IPs. His prime motivator was the fact that it was really hard to get libgeoip built for Mac OSX without using the library from MacPorts.

After Philip Tellis abandoned the project, I picked up to update and upgrade the Library.

Why geoip2-lite
--------------

geoip2-lite is a fully JavaScript implementation of the MaxMind GeoIP2 API. It is not as fully featured as bindings that use libgeoip.
By reducing scope, this package is about 40% faster at doing lookups. On average, an IP to Location lookup should take 20 microseconds on
a Macbook Pro. IPv4 addresses take about 6 microseconds, while IPv6 addresses take about 30 microseconds.

Synopsis
--------

``javascript
var geoip2 = require('geoip2-lite');

var ip = "207.97.227.239";
var geo = geoip2.lookup(ip);

console.log(geo);
{ range: [ 3479298048, 3479300095 ],
country: 'US',
region: 'TX',
eu: '0',
timezone: 'America/Chicago',
city: 'San Antonio',
ll: [ 29.4969, -98.4032 ],
metro: 641,
area: 1000 }

`

Installation
------------


$3

$ npm install geoip2-lite

$3

Run cd node_modules/geoip2-lite && npm run-script updatedb license_key=YOUR_LICENSE_KEY to update the data files. (Replace YOUR_LICENSE_KEY with your license key obtained from maxmind.com)

You can create maxmind account here

NOTE that this requires a lot of RAM. It is known to fail on on a Digital Ocean or AWS micro instance.
There are no plans to change this. geoip2-lite stores all data in RAM in order to be fast.

API
---

geoip2-lite is completely synchronous. There are no callbacks involved. All blocking file IO is done at startup time, so all runtime
calls are executed in-memory and are fast. Startup may take up to 200ms while it reads into memory and indexes data files.

$3

If you have an IP address in dotted quad notation, IPv6 colon notation, or a 32 bit unsigned integer (treated
as an IPv4 address), pass it to the lookup method. Note that you should remove any [ and ] around an
IPv6 address before passing it to this method.

`javascript
var geo = geoip.lookup(ip);
`

If the IP address was found, the lookup method returns an object with the following structure:

`javascript
{
range: [ , ],
country: 'XX', // 2 letter ISO-3166-1 country code
region: 'RR', // Up to 3 alphanumeric variable length characters as ISO 3166-2 code
// For US states this is the 2 letter state
// For the United Kingdom this could be ENG as a country like “England
// FIPS 10-4 subcountry code
eu: '0', // 1 if the country is a member state of the European Union, 0 otherwise.
timezone: 'Country/Zone', // Timezone from IANA Time Zone Database
city: "City Name", // This is the full city name
ll: [, ], // The latitude and longitude of the city
metro: , // Metro code
area: // The approximate accuracy radius (km), around the latitude and longitude
}
`

The actual values for the range array depend on whether the IP is IPv4 or IPv6 and should be
considered internal to geoip2-lite. To get a human readable format, pass them to geoip.pretty()

If the IP address was not found, the lookup returns null

$3

If you have a 32 bit unsigned integer, or a number returned as part of the range array from the lookup method,
the pretty method can be used to turn it into a human readable string.

`javascript
console.log("The IP is %s", geoip.pretty(ip));
`

This method returns a string if the input was in a format that geoip2-lite can recognise, else it returns the
input itself.

Built-in Updater
----------------

This package contains an update script that can pull the files from MaxMind and handle the conversion from CSV.
A npm script alias has been setup to make this process easy. Please keep in mind this requires internet and MaxMind
rate limits that amount of downloads on their servers.

You will need, at minimum, a free license key obtained from maxmind.com to run the update script.

Package stores checksums of MaxMind data and by default only downloads them if checksums have changed.

$3

`shell
#update data if new data is available
npm run-script updatedb license_key=YOUR_LICENSE_KEY

#update data to a different location
npm run-script updatedb geodatadir=/path/to/target/directory license_key=YOUR_LICENSE_KEY

#force udpate data even if checkums have not changed
npm run-script updatedb-force license_key=YOUR_LICENSE_KEY
`

You can also run it by doing:

`bash
node ./node_modules/geoip2-lite/scripts/updatedb.js license_key=YOUR_LICENSE_KEY
`

$3

If you have a server running geoip2-lite, and you want to reload its geo data, after you finished update, without a restart.

#### Programmatically ####

You can do it programmatically, calling after scheduled data updates

`javascript
//Synchronously
geoip.reloadDataSync();

//Asynchronously
geoip.reloadData(function(){
console.log("Done");
});
`

#### Automatic Start and stop watching for data updates ####

You can enable the data watcher to automatically refresh in-memory geo data when a file changes in the data directory.

`javascript
geoip.startWatchingDataUpdate();
`

This tool can be used with npm run-script node-modules/geoip2-lite/updatedb to periodically update geo data on a running server.

Caveats
-------

This package includes the GeoLite database from MaxMind. This database is not the most accurate database available,
however it is the best available for free. You can use the commercial GeoIP database from MaxMind with better
accuracy by buying a license from MaxMind, and then using the conversion utility to convert it to a format that
geoip2-lite understands. You will need to use the .csv files from MaxMind for conversion.

Also note that on occassion, the library may take up to 5 seconds to load into memory. This is largely dependent on
how busy your disk is at that time. It can take as little as 200ms on a lightly loaded disk. This is a one time
cost though, and you make it up at run time with very fast lookups.

$3

Quick test on memory consumption shows that library uses around 100Mb per process

`javascript
var geoip = require('geoip2-lite');
console.log(process.memoryUsage());
/**
* Outputs:
* {
* rss: 126365696,
* heapTotal: 10305536,
* heapUsed: 5168944,
* external: 104347120
* }
**/
`

References
----------
- Documentation from MaxMind
- ISO 3166 (1 & 2) codes
- FIPS region codes

Copyright
---------

geoip2-lite` is Copyright 2022 Chandra Gupta and the latest version of the code is
available at https://github.com/geoip2/geoip2-lite

License
-------

There are two licenses for the code and data. See the LICENSE file for details.