Caution

This repository would not maintaine any more. We recommend to use new library ip-location-api which has faster and customizable system, we created from scratch.

geoip-country

A native nodejs API to get country information from ip address.

This library is fork of the geoip-lite which provides a very fast ip to geolocation API by loading the ip to geolocation database into memory. However, because the database contains city and coordinate information, etc., its size exceeds 120 MB, which means that it uses a lot of memory and takes a long time before the first execution.

geoip-country reduces memory usage and faster startup and faster lookup by restricting database to country from geolocation. Futhermore, we add the other information capital, continent_name, languages, etc., from v5. You can check the test/benchmark.js after updating geoip-lite database. The following tests were performed on Node.js v20 on a PC using SSD.

benchmark	database size	startup time	lookup time
geoip-country	7 MB	17 ms	0.95 μs/ip
geoip-lite	124MB	52 ms	2.37 μs/ip

This product includes GeoLite2 ipv4 and ipv6 country data created by MaxMind. The database of this product updates twice a weekly.

You should read this README and the LICENSE and EULA files carefully before deciding to use this product.
After v4, LICENSE for the GeoLite2 database was changed. If you need to use this product with previous LICENSE, please use v3.

Synopsis

var geoip = require('geoip-country');

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

console.log(geo);
{
  country: 'US', // "2 letter" country code defined at ISO-3166-1 alpha-2
  name: 'United States',
  native: 'United States',
  continent: 'NA',
  continent_name: 'North America',
  phone: [ 1 ],
  capital: 'Washington D.C.',
  currency: [ 'USD', 'USN', 'USS' ],
  languages: [ 'en' ],
}

Installation

$ npm i geoip-country

API

geoip-country 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 20ms 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.

var geo = geoip.lookup(ip);

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

{
  country: 'CN', // "2 letter" country code defined at ISO-3166-1 alpha-2
  name: 'China',
  native: '中国',
  continent: 'AS',
  continent_name: 'Asia',
  phone: [ 86 ],
  capital: 'Beijing',
  currency: [ 'CNY' ],
  languages: [ 'zh' ],
}

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

We use two databases for getting ip address to geo data. First is GeoLite2 country database for linking ip address to country which is "2 letter" country code which is defined at ISO-3166-1 alpha-2 wiki. Second database is Countries database which is published under MIT License for linking country to languages, capital, continent, etc.

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.

npm run updatedb --license_key=YOUR_GEOLITE2_LICENSE_KEY
	or
GEOLITE2_LICENSE_KEY=YOUR_GEOLITE2_LICENSE_KEY node scripts/updatedb.js

YOUR_GEOLITE2_LICENSE_KEY should be replaced by a valid GeoLite2 license key. Please follow instructions provided by MaxMind to obtain a license key.

Update database API [Added at v4.1.0]

You can update country database with updateDatabase method.

  geoip.updateDatabase(license_key, callback);

license_key is a license key which provided by MaxMind. You can get GeoLite2 license key as instructions.

By setting the environmental variable GEOLITE2_LICENSE_KEY, you can update with

  geoip.updateDatabase(callback);

Fast lookup setting

By setting CLI parameter --geoip_fast_lookup=XX or envirnment GEOIP_FAST_LOOKUP=XX, you can make faster lookup time, in exchange for slower startup time and increase memory usage. Default of geoip_fast_lookup is 12, 4 is minimum and 18 is maximum.

geoip_fast_lookup	increased memory usage	startup time	lookup time
4 [min]	192 B	13 ms	1.15 μs/ip
6	768 B	13 ms	1.11 μs/ip
8	3 KB	13 ms	1.07 μs/ip
10	12 KB	15 ms	1.00 μs/ip
12 [default]	48 KB	17 ms	0.95 μs/ip
14	192 KB	19 ms	0.91 μs/ip
16	768 KB	22 ms	0.87 μs/ip
18 [max]	3 MB	31 ms	0.84 μs/ip
20 [cannot use]	12 MB	59 ms	0.87 μs/ip

Use ip-location-db database

You can use ip-location-db database with the environment variable IP_LOCATION_DB or CLI parameter --ip_location_db=XXXXX. For example, if you want to use geolite2-geo-whois-asn-country which supports wider ip than geolite2-country, you can update the database by executing npm run updatedb --ip_location_db=geolite2-geo-whois-asn.

If you cannot use GeoLite2 licence for your use-case, the licence issue can be circumvented by replacing the database in ip-location-db, as there are also some Public licenced (CC0 PDDL) databases in ip-location-db.

Custom Directory for database files

You can store the database files in custom directory with the environment variable GEOIP_DATADIR or CLI parameter --geoip_datadir=XXXXX. For creating or updating the database files in custom directory, you need to run built-in updater as documented above with setting the environment variable GEOIP_DATADIR or CLI parameter --geoip_datadir=XXXXX. If you have no write-access to the geoip-country directory, it would be better to set the environment GEOIP_TMPDATADIR or CLI parameter --geoip_tmpdatadir=YYYYY for temporary directory when updating the database files.

License and EULA

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.

You can read the latest version of GeoLite2 EULA. GeoLite2 database is provided under CC BY-SA 4.0 by MaxMind, so, you must create attribusion to MaxMind for using GeoLite2 database.

The license for the software itself is an Apache License 2.0 by geoip-country. This software is created from the repository geoip-lite/node-geoip. The software license of geoip-lite/node-geoip is Apache License 2.0.

References

• GeoLite2 EULA
• Documentation from MaxMind
• ISO 3166 (1 & 2) codes
• FIPS region codes
• annexare/Countries