geoip-ultralight
v0.1.5
Published
Super lightweight GeoIP implementation with country data
Downloads
6,742
Maintainers
Readme
geoip-ultralight
An even lighter alternative to geoip-lite and libGeoIP wrappers. It provides country data for IP addresses based on the GeoLite data from MaxMind. It does not provide city, state or region data. Forked from geoip-lite.
Why
Unlike other geoip libraries for node, geoip-lite and geoip-ultralight don't
require compiling libGeoIP
; they're JavaScript implementations. While neither
offer the full functionality of geoip
, they're significantly faster.
geoip-lite
is fairly light already, boasting 6 microsecond lookups for IPv4
addresses, and 30 microsecond lookups for IPv6 on a Macbook Pro. However, it
ships over 60MB of data for handling city/region names, and thus introduces
significant memory overhead. If all you want is country data, and not
city/regions, then that's a lot of RAM for unused functionality.
Instead, geoip-ultralight
includes under 2MB of data, and has negligible
memory consumption. If all you need is to identify countries, this will work
perfectly with your Digital Ocean or AWS micro instances.
Installation
It can be installed via npm
using:
npm install --save geoip-ultralight
Usage
var geoip = require('geoip-ultralight');
// Unlike geoip-lite's lookup() call, geoip-ultralight exposes
// a lookupCountry() function to avoid confusion
var ip = "207.97.227.239";
geoip.lookupCountry(ip); // => "US"
API
geoip-ultralight is completely synchronous. There are no callbacks involved. All blocking file IO is done at startup time, so runtime calls are executed quickly in memory. Startup may take up to 200ms while reading and indexing files into memory.
lookupCountry
The function accepts IP addresses in dotted quad notation, IPv6 colon notation, as well as 32bit unsigned integers (treated as IPv4). Note that any square brackets should be removed from IPv6 addresses beforehand.
var country = geoip.lookupCountry(ip);
If the IP address was found, lookupCountry
returns a
2 letter ISO-3166-1
country code. Otherwise it returns null.
pretty
Given a 32bit unsigned integer, pretty
will return a human readable string
equivalent.
geoip.pretty(ip);
The function returns a string if the format was recognized, otherwise it returns the original input.
startWatchingDataUpdate
When invoked, the server will watch the data directory for changes and reload the in-memory geo data as necessary.
geoip.startWatchingDataUpdate();
This can be used along with npm run-script updatedb
to periodically update
geo data on a running server.
stopWatchingDataUpdate
Stops the server from watching the data dir for updates.
geoip.stopWatchingDataUpdate();
Built-in Updater
The package contains an update script that can pull geo data from MaxMind and handle the necessary conversions into a compatible format.
npm run-script updatedb