Documentation

Endpoint reference

Both geolocation endpoints, their parameters and responses.

GET/v1/ip

Detect the caller IP

Resolves the address the request originated from. Useful for server-side personalisation where you already proxy the visitor.

Parameter	In	Required	Description
locale	query	no	Language used for country and region names.

curl "https://api.geolocate-api.dev/v1/ip" \
  -H "Authorization: Bearer geo_live_xxxxxxxxxxxxxxxxx"

const response = await fetch("https://api.geolocate-api.dev/v1/ip", {
  headers: { Authorization: "Bearer geo_live_xxxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.geolocate-api.dev/v1/ip",
    headers={"Authorization": "Bearer geo_live_xxxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer geo_live_xxxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.geolocate-api.dev/v1/ip", false, $context), true);

200 OK

{
  "ip": "189.4.12.77",
  "country": { "code": "BR", "name": "Brazil" },
  "region": { "name": "São Paulo", "code": "BR-SP" },
  "city": "São Paulo",
  "postal_code": "01310",
  "coordinates": { "latitude": -23.5505, "longitude": -46.6333 },
  "timezone": { "id": "America/Sao_Paulo", "offset": "-03:00" }
}

GET/v1/ip/{ip}

Look up a specific IP

Resolves any IPv4 or IPv6 address. Returns 400 for a malformed address and 422 when the address cannot be resolved.

Parameter	In	Required	Description
ip	path	yes	The IPv4 or IPv6 address to resolve.
locale	query	no	Language used for country and region names.

curl "https://api.geolocate-api.dev/v1/ip/8.8.8.8" \
  -H "Authorization: Bearer geo_live_xxxxxxxxxxxxxxxxx"

const response = await fetch("https://api.geolocate-api.dev/v1/ip/8.8.8.8", {
  headers: { Authorization: "Bearer geo_live_xxxxxxxxxxxxxxxxx" },
});

const data = await response.json();

import requests

response = requests.get(
    "https://api.geolocate-api.dev/v1/ip/8.8.8.8",
    headers={"Authorization": "Bearer geo_live_xxxxxxxxxxxxxxxxx"},
    timeout=10,
)
data = response.json()

<?php

$context = stream_context_create([
    "http" => ["header" => "Authorization: Bearer geo_live_xxxxxxxxxxxxxxxxx"],
]);

$data = json_decode(file_get_contents("https://api.geolocate-api.dev/v1/ip/8.8.8.8", false, $context), true);

200 OK

{
  "ip": "8.8.8.8",
  "country": { "code": "US", "name": "United States" },
  "region": { "name": "California", "code": "US-CA" },
  "city": "Mountain View",
  "postal_code": "94043",
  "coordinates": { "latitude": 37.4056, "longitude": -122.0775 },
  "timezone": { "id": "America/Los_Angeles", "offset": "-07:00" }
}