Lookup

Locates one IPv4 or IPv6 address: its network, continent, country, region, city and coordinates.

API key
1 unit per request

GET/v1/lookup/{ip}

GET/v1/lookup/me

Request

Parameter	In	Description
`ip`	path	An IPv4 or IPv6 address, at most 45 characters. IPv4-mapped IPv6 (`::ffff:1.2.3.4`) is treated as IPv4, and percent-encoded colons are accepted. Zone IDs and leading zeros are rejected.
`lang`	query	Language of place names: `en` (default), `de`, `es`, `fr`, `ja`, `pt-BR`, `ru` or `zh-CN`, case-insensitive. A name without a translation falls back to English.
`X-API-Key`	header	Your key, or `Authorization: Bearer <key>`. See Authentication.

curl -H "X-API-Key: $LOCATE_ME_KEY" \
  "http://localhost:8080/v1/lookup/8.8.8.8?lang=de"

const url = "http://localhost:8080/v1/lookup/8.8.8.8?lang=de";
const res = await fetch(url, {
  headers: { "X-API-Key": process.env.LOCATE_ME_KEY },
});
if (!res.ok) throw new Error((await res.json()).error);
const place = await res.json();
console.log(place.city, place.country?.name);

import os
import requests

res = requests.get(
    "http://localhost:8080/v1/lookup/8.8.8.8",
    params={"lang": "de"},
    headers={"X-API-Key": os.environ["LOCATE_ME_KEY"]},
    timeout=5,
)
res.raise_for_status()
place = res.json()
print(place.get("city"), place["country"]["name"])

// reqwest = { version = "0.12", features = ["json"] }
let place: serde_json::Value = reqwest::Client::new()
    .get("http://localhost:8080/v1/lookup/8.8.8.8?lang=de")
    .header("X-API-Key", std::env::var("LOCATE_ME_KEY")?)
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;
println!("{} {}", place["city"], place["country"]["name"]);

Response

200 OK // ?lang=de

{
  "ip": "8.8.8.8",
  "network": "8.8.8.0/24",
  "continent": { "code": "NA", "name": "Nordamerika" },
  "country": {
    "code": "US",
    "name": "Vereinigte Staaten von Amerika",
    "in_eu": false
  },
  "region": { "name": "California" },
  "city": "Mountain View",
  "location": { "latitude": 37.422, "longitude": -122.085 }
}

The region has no German name in the database, so it falls back to English. Fields without data are left out rather than sent as null. DB-IP City Lite, the default database, fills continent, country, region.name, city and location; other databases may add the fields marked optional.

Field	Type	Description
`ip`	string	The address looked up, in canonical form (`::ffff:8.8.8.8` becomes `8.8.8.8`).
`network`	string	The most specific network in the database that contains the address, as CIDR.
`continent.code`	string	Two-letter continent code: `AF`, `AN`, `AS`, `EU`, `NA`, `OC` or `SA`.
`continent.name`	string	Continent name in the requested language.
`country.code`	string	ISO 3166-1 alpha-2 country code.
`country.name`	string	Country name in the requested language.
`country.in_eu`	boolean	Whether the country is a member state of the European Union.
`region.code`	string	Optional. ISO 3166-2 subdivision code.
`region.name`	string	First-level subdivision: state, province or region.
`city`	string	City name in the requested language.
`postal_code`	string	Optional. Postal code.
`location.latitude`	number	Degrees north, WGS 84.
`location.longitude`	number	Degrees east, WGS 84.
`location.accuracy_radius_km`	number	Optional. Radius around the coordinates that likely contains the address.
`location.time_zone`	string	Optional. IANA time zone, such as `Europe/Vienna`.

Headers

Header	Description
`RateLimit-Limit`	Burst capacity of your key. See Rate Limits.
`RateLimit-Remaining`	Units you can spend right now.
`RateLimit-Reset`	Seconds until your key's bucket is full again.
`X-Data-Attribution`	The credit the database license requires, on successful lookups.

The Caller's Address

GET /v1/lookup/me locates the address the request comes from. It takes the same lang parameter, costs the same unit and returns the same response.

curl -H "X-API-Key: $LOCATE_ME_KEY" \
  http://localhost:8080/v1/lookup/me

The address is the TCP peer. When the peer is listed in server.trusted_proxies, it is the right-most X-Forwarded-For hop that is not itself a trusted proxy.

Requests from loopback or a private network get 404 reserved_address: those addresses never have a location. Call it from your users' side of the network, or pass their address to /v1/lookup/{ip}.

Errors

Status	Code	When
400	`invalid_ip`	The path is not a valid address.
400	`invalid_lang`	`lang` is not one of the eight languages.
401	`unauthorized`	Missing, unknown or disabled key.
404	`not_found`	The database has no location for the address.
404	`reserved_address`	A private, loopback, documentation or other reserved range.
429	`rate_limited`	The key's quota is spent; wait `Retry-After` seconds.
503	`database_unavailable`	No database is loaded yet.