locator#

Look up IP locations and networks with MaxMind GeoLite2 City and ASN databases.

Requirements#

A MaxMind account ID and license key, network access to MaxMind, and tar for extracting database downloads.

Install#

npm i @nodedk/locator

Usage#

var createLocator = require('@nodedk/locator')

async function main() {
  var locator = createLocator({
    datadir: 'data',
    account_id: process.env.MAXMIND_ACCOUNT_ID,
    license_key: process.env.MAXMIND_LICENSE_KEY
  })

  var result = await locator.sync()
  console.log(result.updated)
  console.log(locator.find('8.8.8.8'))
}

main().catch(console.error)

API#

createLocator(options = {})#

Returns { sync, find } synchronously.

• account_id, license_key: required by sync().
• datadir: database directory, default data, resolved from the working directory.

locator.sync()#

Checks both editions, downloads missing or changed databases, validates them, and loads readers. Resolves to { updated }, where updated is an array containing any changed edition names: GeoLite2-City and GeoLite2-ASN.

An unchanged sync returns { updated: [] }. Call explicitly when updates are needed; the library does not start a timer. Request, extraction, and validation failures reject.

locator.find(ip)#

Takes an IPv4 or IPv6 string. Returns a location object synchronously, or null when neither database contains the address. Throws if called before a successful sync() or if the reader rejects the IP.

The result contains:

• country_code, country: country code and English name.
• region_code, region: first subdivision code and English name.
• city, postal_code.
• latitude, longitude, accuracy_radius_km.
• timezone.
• asn, organization: autonomous system number and organization.

Unavailable fields are null. The input IP is not repeated in the result.

Testing options#

createLocator also accepts these replacements:

• fetcher(url, options): Fetch-compatible function for HEAD and download requests.
• extractor(archive, directory): extracts an archive; may return a promise.
• validate(file, edition): validates each staged database; may return a promise. edition contains name, file, and reader method.
• cityReader, asnReader: objects implementing city(ip) and asn(ip), used instead of opening local readers after sync.

Created by Vidar Eldøy