ip2ldb-reader

A database reader for IP2Location paid, free, and sample databases. This is derivative work, based on github.com/ip2location-nodejs/IP2Location.

Requirements

• Minimum supported Node.js version: 20.19.0

Installation

npm install --save ip2ldb-reader

Usage

Both ES Module and CommonJS exports are available. Importing this module should work seamlessly in either system.

// Import as ES Module
import Ip2lReader from 'ip2ldb-reader';
// Or require as CommonJS
// const {Ip2lReader} = require('ip2ldb-reader');

// Define database reader options
const options = {...};

// Construct an instance of Ip2lReader
const ip2lReader = new Ip2lReader();

// Initialize reader with the IP2Location database
await ip2lReader.init('/path/to/database.bin', options);

// Get geolocation data for IP addresses
const ipv6data = ip2lReader.get('2001:4860:4860::8888');
const ipv4data = ip2lReader.get('8.8.8.8');

// Close the database and uninitialize the reader
ip2lReader.close();

Options

{
  // {boolean} Cache database in memory
  cacheDatabaseInMemory: false,

  // {boolean} Watch filesystem for database updates and reload if detected
  reloadOnDbUpdate: false,

  // {string} Path to subdivision CSV database
  subdivisionCsvPath: undefined,

  // {string} Path to GeoName ID CSV database
  geoNameIdCsvPath: undefined,

  // {string} Path to country info CSV database
  countryInfoCsvPath: undefined,

  // {string} Path to IATA/ICAO airport CSV database
  iataIcaoCsvPath: undefined,

  // {string} Path to continent multilingual CSV database
  continentCsvPath: undefined,

  // {string} Path to Olson time zone CSV database
  olsonTzCsvPath: undefined,
}

Additional information

• cacheDatabaseInMemory - Read entire database into memory on intialization.
• reloadOnDbUpdate - When enabled, the database file is monitored for changes with a 500ms debounce.
  • If cacheDatabaseInMemory is false (the default case), the database reader is put into the INITIALIZING state on the leading edge of the debounce. Attempts to read from the database short circuit and do not touch the filesystem. The updated database is reloaded on the trailing edge of the debounce. This means there is a minimum of 500ms where geolocation requests will receive {status: "INITIALIZING"} responses.
  • If cacheDatabaseInMemory is true, the reader will continue to return results from the cached database while the updated database loads. There is no interruption in service.
• subdivisionCsvPath - When a filesystem path to the IP2Location ISO 3166-2 Subdivision Code CSV database is provided, the country code and region will be used to identify the corresponding subdivision code.
  • Requires DB3 or higher database that includes both country and region.
• geoNameIdCsvPath - When a filesystem path to the IP2Location GeoName ID CSV database is provided, the country code, region, and city will be used to identify the corresponding GeoName ID.
  • Requires DB3 or higher database that includes all of country, region, and city.
• countryInfoCsvPath - When a filesystem path to the IP2Location Country Information CSV database is provided, the country code will be used to identify additional country information (capital, population, currency, language, etc.).
• iataIcaoCsvPath - When a filesystem path to the IP2Location IATA/ICAO airport CSV database is provided, the country code and region will be used to identify airports in the region.
  • Requires DB3 or higher database that includes both country and region.
• continentCsvPath - When a filesystem path to the IP2Location Continent Multilingual CSV database is provided, the country code will be used to identify the corresponding continent (English language only).
• olsonTzCsvPath - When a filesystem path to the IP2Location Olson Time Zone CSV database is provided, the country code, region, and city will be used to identify the corresponding time zone.
  • Requires DB3 or higher database that includes all of country, region, and city.
  • DB11 and higher databases include basic "shift from UTC" timezone information. This CSV database outputs more information, including the Olson time zone name and DST start/end dates.

Return

The object returned by .get(ip) has the following structure:

interface Ip2lData {
  ip: string | null;
  ip_no: string | null;
  status: string | null;

  addresstype?: string;
  airports?: IataIcaoData[];
  areacode?: string;
  as?: string;
  ascidr?: string;
  asdomain?: string;
  asn?: string;
  asusagetype?: string;
  category?: string;
  city?: string;
  continent?: ContinentData | null;
  country_info?: CountryInfoData | null;
  country_long?: string;
  country_short?: string;
  district?: string;
  domain?: string;
  elevation?: string;
  geoname_id?: number | null;
  iddcode?: string;
  isp?: string;
  latitude?: number | null;
  longitude?: number | null;
  mcc?: string;
  mnc?: string;
  mobilebrand?: string;
  netspeed?: string;
  olson_timezone?: OlsonTzData | null;
  region?: string;
  subdivision?: string | null;
  timezone?: string;
  usagetype?: string;
  weatherstationcode?: string;
  weatherstationname?: string;
  zipcode?: string;
}

where

interface CountryInfoData {
  capital: string;
  cctld?: string;
  country_alpha3_code?: string;
  country_code: string;
  country_demonym?: string;
  country_name?: string;
  country_numeric_code?: number | null;
  currency_code?: string;
  currency_name?: string;
  currency_symbol?: string;
  idd_code?: number | null;
  lang_code?: string;
  lang_name?: string;
  population?: number | null;
  total_area: number | null;
}

and

interface IataIcaoData {
  airport: string;
  iata: string;
  icao: string;
  latitude: number | null;
  longitude: number | null;
}

and

interface ContinentData {
  continent_code: string;
  continent: string;
}

and

interface OlsonTzData {
  abbreviation: string;
  dst_end: string | null;
  dst_start: string | null;
  olson_tz: string;
}

Properties suffixed by ? only exist if the database supports them. For example, when using a DB1 (country only) database, a sample return object looks like

{
  ip: "8.8.8.8",
  ip_no: "134744072",
  status: "OK",
  country_short: "US",
  country_long: "United States of America"
}

Possible values for status include:

• OK - Successful search for geolocation data
• INITIALIZING - Database reader is initializing and is not ready to receive requests
• NOT_INITIALIZED - Database reader failed to initialize
• IP_ADDRESS_NOT_FOUND - IP address has correct format, but database does not contain data for it
• INVALID_IP_ADDRESS - IP address does not have correct format
• IPV6_NOT_SUPPORTED - Unable to lookup IPv6 address because database does not support them
• DATABASE_NOT_FOUND - Database is missing from the filesystem

When no geolocation data is available for a supported property in the return object:

• String values are empty ("")
• Number values are null (null)

Upgrade notes

• See releases for information on feature updates, breaking changes, and bugfixes.

Development

See available build, lint, clean, etc. scripts with npm run.

Unit tests require the following database files to be made available in folder database within the project directory:

• IP2LOCATION-ISO3166-2.CSV - ISO 3166-2 Subdivision Code database in CSV format
• IP2LOCATION-GEONAMEID.CSV - GeoName ID database in CSV format
• IP2LOCATION-COUNTRY-INFORMATION.CSV - Country Info ("More Information" version) database in CSV format
• IP2LOCATION-IATA-ICAO.CSV - IATA/ICAO airport database in CSV format
• IP2LOCATION-OLSON-TIMEZONE.CSV - Olson Time Zone database in CSV format
• IP2LOCATION-CONTINENT-MULTILINGUAL.CSV - Continent Multilingual database in CSV format
• IP2LOCATION-LITE-DB1.BIN - LITE IP-COUNTRY DB1 IPv4 database in BIN format
• IP2LOCATION-SAMPLE-DB26.IPV6.BIN - Sample DB26 IPv6 database in BIN format

Note that the sample DB26 database is expected for unit tests, not the full, paid database.