geoip-native-lite

Super-fast IP to country lookups with minimal RAM usage.

Goals

• Fast IP address to country lookup:
  • 1,000,000+ ops/second for IPv4 addresses
  • 500,000+ ops/second for IPv6 addresses
• Minimal RAM usage
• Native JavaScript implementation for ease-of-use and portability

Installation

Add to your application via npm:

npm install geoip-native-lite --save

This will install geoip-native-lite and add it to your application's package.json file.

Update Data Files

This module ships with pre-built data files. If you'd like to update the data files for yourself, run the update script like this:

npm run updatedata

How to Use

• lookup
• loadData
• loadDataSync

lookup

lookup(ip)

Lookup the country in which the IP address is located. Supports both ipv4 and ipv6.

Usage:

1var GeoIpNativeLite = require('geoip-native-lite');
2
3// Must load data before lookups can be performed.
4GeoIpNativeLite.loadDataSync();
5
6// Data loaded successfully.
7// Ready for lookups.
8var ip = '128.21.16.34';
9var country = GeoIpNativeLite.lookup(ip);
10
11if (country) {
12	console.log(ip, 'is geo-located in', country.toUpperCase());
13} else {
14	console.log('Failed to geo-locate the IP address:', ip);
15}

loadData

loadData([options, ]cb)

Asynchronously loads geoip data.

Usage:

1var GeoIpNativeLite = require('geoip-native-lite');
2
3GeoIpNativeLite.loadData(options, function(error, data) {
4
5	if (error) {
6		// Something went wrong.
7	} else {
8		// Data loaded successfully.
9		// Ready for lookups.
10	}
11});

Options:

1var options = {
2
3	/*
4		Set to TRUE to load ipv4 geoip data.
5
6		Default value is TRUE.
7	*/
8	ipv4: true,
9
10	/*
11		Set to TRUE to load ipv6 geoip data.
12
13		Default value is FALSE.
14	*/
15	ipv6: false,
16
17	/*
18		Set to TRUE to cache data in memory.
19
20		Default value is TRUE.
21	*/
22	cache: true
23};

loadDataSync

loadDataSync([options])

Synchronously loads geoip data.

Usage:

1var GeoIpNativeLite = require('geoip-native-lite');
2
3GeoIpNativeLite.loadDataSync(options);
4
5var country = GeoIpNativeLite.lookup('198.169.246.30');

Options:

1var options = {
2
3	/*
4		Set to TRUE to load ipv4 geoip data.
5
6		Default value is TRUE.
7	*/
8	ipv4: true,
9
10	/*
11		Set to TRUE to load ipv6 geoip data.
12
13		Default value is FALSE.
14	*/
15	ipv6: false,
16
17	/*
18		Set to TRUE to cache data in memory.
19
20		Default value is TRUE.
21	*/
22	cache: true
23};

Contributing

There are a number of ways you can contribute:

• Improve or correct the documentation - All the documentation is in this readme.md file. If you see a mistake, or think something should be clarified or expanded upon, please submit a pull request
• Report a bug - Please review existing issues before submitting a new one; to avoid duplicates. If you can't find an issue that relates to the bug you've found, please create a new one.
• Request a feature - Again, please review the existing issues before posting a feature request. If you can't find an existing one that covers your feature idea, please create a new one.
• Fix a bug - Have a look at the existing issues for the project. If there's a bug in there that you'd like to tackle, please feel free to do so. I would ask that when fixing a bug, that you first create a failing test that proves the bug. Then to fix the bug, make the test pass. This should hopefully ensure that the bug never creeps into the project again. After you've done all that, you can submit a pull request with your changes.

Tests

To run all tests (except benchmarks):

npm test

To run benchmarks:

npm run test:benchmarks

To run only unit tests:

npm run test:unit

To run only code-style checks:

npm run lint

Licensing

All the code in this project is MIT licensed.

The geoip data used in this project is licensed separately.