2.3.2 • Published 21 hours ago

ip-location-api v2.3.2

Weekly downloads
-
License
Multiple licenses
Repository
github
Last release
21 hours ago

ip-location-api npm version

Fast and customizable nodejs api to get geolocation information from ip address. ip-location-api make a fast lookup by using in-memory database.

This api is created for server-side javascript like Node.js. If you need client-side javascript which works in BROWSER, please try to use @iplookup/country or @iplookup/geocode.

Synopsis

import { lookup } from 'ip-location-api'
// or CJS format
// const { lookup } = require('ip-location-api')

var ip = "207.97.227.239"
var location = lookup(ip)
// If you use Asynchronouns version which is configured with smallMemory=true,
// var location = await lookup(ip)

console.log(location)
{
  country: 'FR',
  region1: 'NOR',
  region1_name: 'Normandy',
  region2: '27', 
  region2_name: 'Eure',
  city: 'Heudicourt',
  // metro: Defined only in US (Aug.2024)
  timezone: 'Europe/Paris',
  eu: 1,
  latitude: 49.3335,
  longitude: 1.6566,
  area: 5,
  postcode: 27860,
  country_name: 'France',
  country_native: 'France',
  phone: [ 33 ],
  continent: 'EU',
  capital: 'Paris',
  currency: [ 'EUR' ],
  languages: [ 'fr' ],
  continent_name: 'Europe'
}

Benchmark

I make a benchmark for making comparison with intel 12700 (2.1GHz), SSD, nodejs v20. You can change the memory usage or lookup time, by customizing location information.

benchmarktypein-memory dbstartuplookup ipv4lookup ipv6
ip-location-api(default)country6.9 MB3 ms0.362 μs/ip0.708 μs/ip
ip-location-api(async)country2.9 MB2 ms243 μs/ip255 μs/ip
ip-location-apicity62.9 MB14 ms0.751 μs/ip1.064 μs/ip
ip-location-api(async)city15.6 MB5 ms267 μs/ip271 μs/ip
geoip-litecity136 MB54 ms1.616 μs/ip3.890 μs/ip
fast-geoip(async)city0MB4 ms1714 μs/ipcannot lookup

Installation

$ npm i ip-location-api

API

ip-location-api has two modes which are synchronous and asynchronous. Synchronouns one load all data in-memory at startup time, thus it makes fast lookup. Asynchronouns one load smaller data in-memory at startup time, and the other data is loaded from the hard drive for each lookup.

typememory usagestartuplookup
SynchronounsLargeSlowFast
AsynchronounsSmallFastSlow

If you have a enough memory, I recommend to use synchronouns one because lookup is over 300 times faster than asynchronouns one.

Field description

Note that as far as possible, the same field names as in geoip-lite are used, but some different field names are used.

ip-location-apigeoip-litedatabasedescription
countrycountryMaxMind"2 letter" country code defined at ISO-3166-1 alpha-2
region1regionMaxMindregion code which is short code for region1_name ISO 3166-2
region1_name❌️MaxMindfirst sub division name (multi language)
region2❌️MaxMindregion code which is short code for region2_name ISO 3166-2
region2_name❌️MaxMindsecond sub division name (multi language)
citycityMaxMindcity name (multi language)
metrometroMaxMindGeolocation target code from Google
eueuMaxMindtrue: the member state of the European Union, undefined: for the other countries. This needs "country" field.
timezonetimezoneMaxMindtime zone associated with location
latitudell0MaxMindapproximate WGS84 latitude
longitudell1MaxMindapproximate WGS84 longitude
areaareaMaxMindThe radius in kilometers around the specified location where the IP address is likely to be. maxmind blog
postcode❌️MaxMindregion-specific postal code near the IP address
❌️rangeMaxMindWe removes range information for optimization
country_name❌️Countriescountry name
country_native❌️Countriescountry name in native language
continent❌️Countriescontinent short code
continent_name❌️Countriescontinent name
capital❌️Countriescapital name
phone❌️Countriesinternational country calling codes
currency❌️Countrieslist of commonly used currencies
languages❌️Countrieslist of commonly used languages

Setup the configuration

You can configure the api by 3 way.

  • CLI parameters: ILA_FIELDS=latitude,longitude
  • Environment variables: ILA_FIELDS=latitude,longitude
  • Javascript: await reload({fields: 'latitude,longitude'}) .

The name of CLI prameter and environment variables are same.

Conf key in reload(conf) is named with "LOWER CAMEL", CLI or ENV parameter is named with "SNAKE" with adding "ILA_" (come from Ip-Location-Api).

reload(conf)CLI or ENVdefaultdescription
fieldsILA_FIELDScountryYou can change the fields to be retrived from MaxMind. When you set "all", all fields are displayed.
addCountryInfoILA_ADD_COUNTRY_INFOfalse"true" make to add the country information from Countries. This needs "country" field.
dataDirILA_DATA_DIR../dataDirectory for database file
tmpDataDirILA_TMP_DATA_DIR../tmpDirectory for temporary file
apiDirILA_API_DIR..Directory for ip-location-api
smallMemoryILA_SMALL_MEMORYfalsefalse: synchronouns, ture: asynchronouns
smallMemoryFileSizeILA_SMALL_MEMORY_FILE_SIZE4096Max file size for asynchronouns data (no change is recommended)
licenseKeyILA_LICENSE_KEYredistBy setting MaxMind License key, you can download latest version of database from MaxMind server. By setting to "redist", you can download the database from node-geolite2-redist repository which re-distribute the GeoLite2 database.
ipLocationDbILA_IP_LOCATION_DBWhen you need only "country" field, you can use ip-location-db data
downloadTypeILA_DOWNLOAD_TYPEreuseBy setting to "false", "tmpDataDir" directory is deleted every update. "reuse" dose not delete "tmpDataDir" and re-use "tmpDataDir"'s database if the database file dose not update.
autoUpdateILA_AUTO_UPDATEdefaultBy setting to "false", it dose not update automatically. "default" updates twice weekly. You can set CRON PATTERN FORMAT which is provided by cron with UTC timezone (For example, ILA_AUTO_UPDATE="0 1 * * *" for daily update).
multiDbDirILA_MULTI_DB_DIRfalseIf you use multiple "dataDir", please make this value to "true"
seriesILA_SERIESGeoLite2By setting to "GeoIP2", you can use premium database "GeoIP2"
languageILA_LANGUAGEenYou can choose "de", "en", "es", "fr", "ja", "pt-BR", "ru", "zh-CN". By changing, the language of "region1_name", "region2_name", "city" fields are changed
silentILA_SILENTfalsetrue: deactivate unnecessary console.log

Update database

npm run updatedb

or

import { updateDb } from 'ip-location-api'
await updateDb(setting)

There are three database update way.

  • ILA_LICENSE_KEY=redist
  • ILA_LICENSE_KEY=YOUR_GEOLITE2_LICENSE_KEY
  • ILA_IP_LOCATION_DB=YOUR_CHOOSEN_DATABSE

When you set "ILA_LICENSE_KEY=redist" which is the dafault setting, it downloads GeoLite2 database from the redistribution repository node-geolite2-redist.

When you set "ILA_LICENSE_KEY=YOUR_GEOLITE2_LICENSE_KEY", it downloads GeoLite2 dastabase from the MaxMind provided server. YOUR_GEOLITE2_LICENSE_KEY should be replaced by a valid GeoLite2 license key. Please follow instructions provided by MaxMind to obtain a license key.

When you set "ILA_IP_LOCATION_DB=YOUR_CHOOSEN_DATABSE", it downloads from the ip-location-db (country type only). You can "YOUR_CHOOSEN_DATABSE" from ip-location-db with country type. For example, "geolite2-geo-whois-asn" is wider IP range country database which is equivalent to GeoLite2 database result for GeoLite2 country covered IP range and geo-whois-asn-country for the other IP range. The other example, "geo-whois-asn" is CC0 licensed database, if you are unable to apply the GeoLite2 License.

After v2.0, the database is created automatically at initial startup, and updated automatically by setting ILA_AUTO_UPDATE which updates twice weekly with default setting.

How to use with an example

When you need only geographic coordinates, please set "ILA_FIELDS=latitude,longitude". You need to create a database for each configuration. After v2.0.0, the database is created at initial running (which takes some seconds), and auto update with ILA_AUTO_UPDATE which update twice weekly with default setting.

The database is created by following CLI

$ npm run updatedb ILA_FIELDS=latitude,longitude

or

$ ILA_FIELDS=latitude,longitude # set environment variable
$ npm run updatedb

or you can create database with 'create.js' which includes the following.

await updateDb({fields:['latitude', 'longitude']})

The CLI command for using app.js which uses ip-location-api is necessary to start with following CLI parameter

$ node app.js ILA_FIELDS=latitude,longitude

or environment variable

$ ILA_FIELDS=latitude,longitude # set environment variable
$ node app.js

or you can write down configuration in reload function of app.js as

await reload({fields:['latitude', 'longitude']})
// or await reload({fields:'latitude,longitude'})

If you need all the data in above field table, setting "ILA_FIELDS=all" and "ILA_ADD_COUNTRY_INFO=true" is the one.

benchmarkin-memory dbstartuplookup ipv4lookup ipv6
longitude,latitude46.5 MB10 ms0.428 μs/ip0.776 μs/ip
all76.4 MB18 ms1.054 μs/ip1.348 μs/ip

For module bundler (webpack, vite, next.js, etc)

Some module bundlers cannot work with original database system. If module bundlers could not work with ip-location-api, please try to import module as following. It works almost same as original module.

import { lookup } from 'ip-location-api/pack'

It would be better to set directories for database files which have write permission. Without write permission directories, you cannot use this module.

ILA_DATA_DIR=/your_database_directory
ILA_TMP_DATA_DIR=/your_tmporary_directory_for_database

Node.js version

This library supports Node.js >= 14 for ESM and CJS.

License and EULA

There are multiple licenses in this library, one for the software library, and the others for the datadata. Please read the LICENSE and EULA files for details.

The license for the software itself is published under MIT License by sapics.

The GeoLite2 database 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 need to create attribusion to MaxMind for using GeoLite2 database.

The database of Countries is published under MIT license by Annexare Studio.

2.3.2

21 hours ago

2.3.0

7 days ago

2.3.1

3 days ago

2.2.1

8 days ago

2.2.0

9 days ago

2.1.5

19 days ago

2.1.4

20 days ago

2.1.3

28 days ago

2.1.2

28 days ago

2.1.1

1 month ago

2.1.0

1 month ago

2.0.1

1 month ago

2.0.0

1 month ago

1.0.0

2 months ago

0.2.4

2 months ago

0.2.3

2 months ago

0.2.2

2 months ago

0.2.1

2 months ago

0.2.0

2 months ago

0.1.20240907

2 months ago

0.1.20240904

2 months ago

0.1.1

2 months ago

0.1.0

2 months ago