DOCSEARCHbyAlgolia
Submit Docs

MaxMind GeoIP2 Node.js API

repository·main·Indexed 42 days ago

https://github.com/maxmind/geoip2-node

A Node.js API for performing IP geolocation lookups using MaxMind's GeoIP and GeoLite databases locally via the Reader class or remotely through the WebServiceClient. Version 7.1.0 supports local .mmdb files and web service endpoints for country, city, and insights data.

Tokens
6.9K
Snippets
20
Records
32
Agent score
55%

What's inside GeoIP2 Node

  1. Understand data availability and unpopulated attributes

    main
    When using MaxMind web services or databases, the attributes populated in a record depend on the specific endpoint or database being used. MaxMind does not guarantee that every piece of data is available for every IP address. Consequently, any request may return a record where some or all attributes are unpopulated. The only attribute guaranteed to always be returned is ipAddress within the geoip2-node.TraitsRecord record.

  2. Understand GeoNames integration and geonameId

    main
    MaxMind integrates with GeoNames for geographical data such as place names and ISO codes. Many records returned by GeoIP services and databases include a geonameId field. This field is an integer representing the unique identifier for a geographical feature (such as a city, region, or country) in the GeoNames database.

  3. Supported development platforms

    main

    The following platforms are supported for development:

    • Linux (x64 and arm64)
    • Apple Silicon macOS (arm64)
    • Windows (x64)

    Note: Intel macOS and Windows ARM64 are not supported. Specifically, Intel macOS cannot be used because pnpm 11.0.5 and later do not ship a darwin-x64 binary, preventing mise from installing necessary tools.

  4. Recommended keys for data persistence

    main

    Do not use values from names properties as keys in your own databases or objects, as these names may change between releases. Instead, use these stable identifiers:

    • CityRecord: city.geonameId
    • ContinentRecord: continent.code or continent.geonameId
    • CountryRecord / RepresentedCountry: country.isoCode or country.geonameId
    • SubdivisionsRecord: subdivision.isoCode or subdivision.geonameId

  6. Install @maxmind/geoip2-node

    main

    Install the package using npm, yarn, or pnpm to access MaxMind GeoIP and GeoLite databases and web services in a server-side Node.js environment. Note that this package is not intended for client-side use.

    npm install @maxmind/geoip2-node

  7. Set up the development environment

    main

    This project uses pnpm for dependency management and mise for tool versioning. The repository is a pnpm workspace, so do not use npm or corepack, as they cannot resolve workspace:* dependencies used in the workspace members (e2e/js and e2e/ts).

    To set up the environment:

    1. Install dependencies via mise using mise install.
    2. Install project dependencies using pnpm install.
    mise install
pnpm install

  8. Set up Precious for linting and tidying

    main

    Precious is used to tidy and lint the codebase. You can set it up locally and configure a pre-commit hook to automate the process.

    1. Install Precious locally: mkdir -p local && ./bin/install-precious local
    2. Set up the pre-commit hook: ./git/setup.sh
    mkdir -p local && ./bin/install-precious local
./git/setup.sh

  9. Use the MaxMind Web Service API

    main

    To use the web service API, instantiate a WebServiceClient with your MaxMind accountID and licenseKey. You can then call specific endpoint methods (like country, city, or insights) passing an IP address. These methods return a Promise that resolves to a model containing multiple records.

    Configuration Options

    When instantiating WebServiceClient, you can pass an options object as the third argument:

    • timeout: Request timeout in milliseconds (defaults to 3000).
    • host: The API endpoint host.
      • geoip.maxmind.com (default for GeoIP)
      • geolite.info (for GeoLite web service)
      • sandbox.maxmind.com (for the Sandbox environment)
    • fetcher: A custom fetch implementation (defaults to the global fetch).
    import { WebServiceClient } from '@maxmind/geoip2-node';

// Example: Using the Country Service
const client = new WebServiceClient('1234', 'licenseKey');

client.country('142.1.1.1').then(response => {
  console.log(response.country.isoCode); // 'CA'
});

  10. Use MaxMind Databases locally

    main

    To use local .mmdb database files, use the Reader class. You can open a database file via a path or use a Buffer for synchronous operations or external data sources.

    Opening a Database File

    Reader.open(path, options) returns a Promise that resolves to a reader instance. The options object supports features from the node-maxmind library, such as cache or watchForUpdates.

    Using a Buffer

    Reader.openBuffer(buffer) allows you to use a pre-loaded Buffer. This is useful for synchronous workflows or when the database is fetched from an external source.

    import { Reader } from '@maxmind/geoip2-node';

// Using a file path
Reader.open('/usr/local/database.mmdb', { cache: true }).then(reader => {
  console.log(reader.country('1.1.1.1'));
});

// Using a Buffer
import { readFileSync } from 'node:fs';
const dbBuffer = readFileSync('/usr/local/city-database.mmdb');
const reader = Reader.openBuffer(dbBuffer);
console.log(reader.city('1.1.1.1'));

  11. Report data inaccuracies

    main

    If you encounter data issues, follow these steps based on the type of error:

    1. Incorrect IP mapping: Submit a correction directly to MaxMind via their data correction request form.
    2. Spelling or metadata errors: Check the GeoNames site first. If you find the error there, use the GeoNames correction tools (e.g., "move", "edit", "alternate names"). Once corrected in GeoNames, the data will be automatically incorporated into future MaxMind releases.
    3. Paying customers: If you are unsure where to submit a correction, contact MaxMind support.

  12. Understand the structure of Names and locale-based data

    main

    Many records in the MaxMind API (such as CityRecord, ContinentRecord, RegisteredCountryRecord, and SubdivisionsRecord) include a names object. This object provides the name of a place in various supported locales.

    Important: Do not use these localized names as keys for databases or dictionaries. Always use the provided geonameId or relevant ISO codes for programmatic lookups or storage.

    export interface Names {
  readonly de?: string;
  readonly en: string;
  readonly es?: string;
  readonly fr?: string;
  readonly ja?: string;
  readonly 'pt-BR'?: string;
  readonly ru?: string;
  readonly 'zh-CN'?: string;
}