geoip-lookup

Exposes 2 simple APIs, .lookup and .match. Both are asynchronous, but .match will "block" the callback until it retrieves the information.

.lookup will return an undefined result if the data is not cached in a LevelUp local database that is updated once the data is retrieved.

Usage:

var geoip = require('geoip-lookup');

// This will attempt to check the local database. if not found, it will return an empty result (non-blocking), but will cache the data later
// when the lookup is complete. Useful when e.g. part of an express middleware which you don't want to block rendering the page when your
// next() call is in the callback.
geoip.lookup('10.10.1.1', function(err, result) {
    if (err) {
        console.error(err.stack);
    } else if (result) {
        console.log(result);
    } else {
        console.log('result not found in local database');
    }
    next();
});

// This will get the information from MaxMind and only invoke the callback when it is retrieved.
// it will effectively "block" via the callback, and probably not suitable if continuous execution depends on callbacks
geoip.check('10.10.1.1', function(err, result) {
    if (err) {
        console.error(err.stack);
    } else {
        console.log(result);
    }
}

How it works

Essentially hits

freegeoip.net/json/<ip address>

Please go to https://freegeoip.net/ for more information.

returns JSON in the format

{
    city: "Willemstad"
    country_code: "CW"
    country_name: "Curaçao"
    ip: "190.88.211.185"
    latitude: 12.1
    longitude: -68.917
    metro_code: 0
    region_code: ""
    region_name: ""
    time_zone: "America/Curacao"
    zip_code: ""
}

Legacy (no longer applies)

Tries to cache IP addresses / location lookup via LevelDB, and otherwise pulls the data via a "demo" RESTful API provided by MaxMind.

It's not very clear if this is "legal" as you should probably get a proper license to do this if you're doing it on a large scale.

Essentially hits

https://www.maxmind.com/geoip/v2.1/city/<ip address>?demo=1

which returns JSON in the following format

{
   "country":{
      "iso_code":"US",
      "names":{
         "pt-BR":"Estados Unidos",
         "es":"Estados Unidos",
         "ru":"Сша",
         "en":"United States",
         "zh-CN":"美国",
         "fr":"États-Unis",
         "de":"USA",
         "ja":"アメリカ合衆国"
      },
      "geoname_id":6252001
   },
   "location":{
      "longitude":-121.895,
      "latitude":37.3394,
      "time_zone":"America/Los_Angeles",
      "metro_code":807
   },
   "subdivisions":[
      {
         "iso_code":"CA",
         "names":{
            "pt-BR":"Califórnia",
            "es":"California",
            "ru":"Калифорния",
            "en":"California",
            "zh-CN":"加利福尼亚州",
            "fr":"Californie",
            "de":"Kalifornien",
            "ja":"カリフォルニア州"
         },
         "geoname_id":5332921
      }
   ],
   "city":{
      "names":{
         "en":"San Jose",
         "fr":"San José",
         "pt-BR":"San José",
         "de":"San José",
         "ja":"サンノゼ",
         "es":"San José",
         "ru":"Сан-Хосе"
      },
      "geoname_id":5392171
   },
   "continent":{
      "names":{
         "pt-BR":"América do Norte",
         "es":"Norteamérica",
         "ru":"Северная Америка",
         "en":"North America",
         "zh-CN":"北美洲",
         "fr":"Amérique du Nord",
         "de":"Nordamerika",
         "ja":"北アメリカ"
      },
      "geoname_id":6255149,
      "code":"NA"
   },
   "maxmind":{
      "queries_remaining":24
   },
   "registered_country":{
      "iso_code":"US",
      "names":{
         "pt-BR":"Estados Unidos",
         "es":"Estados Unidos",
         "ru":"Сша",
         "en":"United States",
         "zh-CN":"美国",
         "fr":"États-Unis",
         "de":"USA",
         "ja":"アメリカ合衆国"
      },
      "geoname_id":6252001
   },
   "traits":{
      "autonomous_system_number":<some integer>,
      "ip_address":"<ip address>",
      "organization":"<some organization>",
      "isp":"<some ISP>",
      "autonomous_system_organization":"<some system organization>"
   }
}