A native NodeJS API for the GeoLite data from MaxMind.
This product includes GeoLite data created by MaxMind, available from http://maxmind.com/
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.
So why are we called geoip-lite?
binding around libgeoip from MaxMind. The
geoip package is fully featured and supports everything that the MaxMind APIs support,
however, it requires
libgeoip to be installed on your system.
geoip however, by reducing its
scope, it 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.
var geoip = ;var ip = "220.127.116.11";var geo = geoip;console;range: 3479298048 3479300095country: 'US'region: 'TX'eu: '0'timezone: 'America/Chicago'city: 'San Antonio'll: 294969 -984032metro: 641area: 1000
1. get the library
$ npm install geoip-lite
2. update the datafiles (optional)
npm run-script updatedb to update the data files.
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.
geoip-lite stores all data in RAM in order to be fast.
geoip-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.
Looking up an IP address
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
] around an
IPv6 address before passing it to this method.
var geo = geoip;
If the IP address was found, the
lookup method returns an object with the following structure:
range: <low bound of IP block> <high bound of IP block>country: 'XX' // 2 letter ISO-3166-1 country coderegion: '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 codeeu: '0' // 1 if the country is a member state of the European Union, 0 otherwise.timezone: 'Country/Zone' // Timezone from IANA Time Zone Databasecity: "City Name" // This is the full city namell: <latitude> <longitude> // The latitude and longitude of the citymetro: <metro code> // Metro codearea: <accuracy_radius> // 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
geoip-lite. To get a human readable format, pass them to
If the IP address was not found, the
Pretty printing an IP address
If you have a 32 bit unsigned integer, or a number returned as part of the
range array from the
pretty method can be used to turn it into a human readable string.
This method returns a string if the input was in a format that
geoip-lite can recognise, else it returns the
Start and stop watching for data updates
If you have a server running
geoip-lite, and you want to update its geo data without a restart, you can enable
the data watcher to automatically refresh in-memory geo data when a file changes in the data directory.
This tool can be used with
npm run-script updatedb to periodically update geo data on a running server.
Additionally, if you schedule upgrades, you can programmatically make geoip reload the data from new database
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.
npm run-script updatedb
You can also run it by doing:
Or, if you really want, run the update once by
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
geoip-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.
There are two licenses for the code and data. See the LICENSE file for details.