Location by IP

This module returns the location of a given IP address (v4 or v6).

Data comes from Spott, which is a geographical API.

Usage

1. Install:

npm install --save location-by-ip

1. Get a Spott API Key here.

2. Use it in your project:

const GetLocation = require('location-by-ip');
const SPOTT_API_KEY = 'PUT_YOUR_API_KEY_HERE';
 
const getLocation = new GetLocation(SPOTT_API_KEY);
 
// Start using the client. For Example:
// const location = await getLocation.byMyIp();

Data

This module will try to return the most precise location available, which is a CITY. If there's no enough information it will return a COUNTRY.

The properties returned for both responses are:

Property	Type	Description
id	String	Unique identifier given by Spott.
geonameId	Integer	Unique identifier given by GeoNames.
type	String	The classification of the place. Possible values are: CITY and COUNTRY
name	String	Default name of the place (usually in English). This property always has a value.
localizedName	String	Localized name of the place in the requested language. This property is only present when option language is specified. It's null when the translation is not available.
population	Integer	The approximate population living in the place.
elevation	Float	The approximate elevation from sea level. Value is expressed in meters.
coordinates	Object	The geographic coordinates where the place is located.
coordinates.latitude	Float	Latitude component from the geographic coordinates of the place.
coordinates.longitude	Float	Longitude component from the geographic coordinates of the place.
timezoneId	String	Time zone associated to the place. This property is null for countries since they may have multiple.
adminDivision2	Object	A minimal version of the Administrative Division level 2 where the place is located. This property is only present for places of type: CITY. The object contain the properties: id, geonameId, name and localizedName.
adminDivision1	Object	A minimal version of the Administrative Division level 1 where the place is located. This property is only present for places of type: CITY. The object contain the properties: id, geonameId, name and localizedName.
country	Object	A minimal version of the Country where the place is located. This property is only present for places of type: CITY. The object contain the properties: id, geonameId, name and localizedName.

API

.byIp(ip, options)

Returns the location of a given IP Address, or null when the location is not available.

Parameters

Paramter	Type	Description
ip	String	IP Address (v4 and v6 are supported).
options	Object	Optional object with modifiers for the call.
options.language	String	Specifies a language ISO 639-1 to get the localized name of the place. If the translation is not available, "localizedName" property will be null.

Example

const options = {
  language: 'ru' // Russian
};
 
const location = await getLocation.byIp('200.194.51.97', options);
 
/*
console.log(location);
Prints:
 
{
  "id": "4005539",
  "geonameId": 4005539,
  "type": "CITY",
  "name": "Guadalajara",
  "localizedName": "Гвадалахара",
  "population": 1495182,
  "elevation": 1598,
  "timezoneId": "America/Mexico_City",
  "country": {
    "id": "MX",
    "geonameId": 3996063,
    "name": "Mexico",
    "localizedName": "Мексика"
  },
  "adminDivision1": {
    "id": "MX.14",
    "geonameId": 4004156,
    "name": "Jalisco",
    "localizedName": null
  },
  "adminDivision2": {
    "id": "MX.14.039",
    "geonameId": 8582140,
    "name": "Guadalajara",
    "localizedName": null
  },
  "coordinates": {
    "latitude": 20.6668,
    "longitude": -103.392
  }
}
 
*/

.byMyIp(options)

Returns the location related to the IP where the request comes from, or null when the location is not available.

Parameters

Paramter	Type	Description
options	Object	Optional object with modifiers for the call.
options.language	String	Specifies a language ISO 639-1 to get the localized name of the place. If the translation is not available, "localizedName" property will be null.

Example

const options = {
  language: 'fr' // French
};
 
const location = await getLocation.byMyIp(options);
 
/*
console.log(location);
Prints:
 
{
  "id": "5391959",
  "geonameId": 5391959,
  "type": "CITY",
  "name": "San Francisco",
  "localizedName": "San Francisco",
  "population": 864816,
  "elevation": 16,
  "timezoneId": "America/Los_Angeles",
  "coordinates": {
    "latitude": 37.7749,
    "longitude": -122.419
  },
  "country": {
    "id": "US",
    "geonameId": 6252001,
    "name": "United States of America",
    "localizedName": "États-Unis"
  },
  "adminDivision1": {
    "id": "US.CA",
    "geonameId": 5332921,
    "name": "California",
    "localizedName": "Californie"
  },
  "adminDivision2": {
    "id": "US.CA.075",
    "geonameId": 5391997,
    "name": "San Francisco County",
    "localizedName": "Comté de San Francisco"
  }
}
 
*/

Related projects

• countries-and-timezones
• countries-db

License

MIT