Documentation

Getting started

From an empty account to a resolved IP address in four steps.

The shape of the API

Every endpoint is versioned under /v1 and answers JSON. Authentication is a bearer token, and both quota and rate limit state travel back as response headers so you never have to poll a separate usage endpoint.

Four steps

Create an account. The free plan activates immediately, with no payment method.
Subscribe to the geolocation product from the billing page.
Create an API key. The full secret is displayed once, so store it right away.
Send the key as a bearer token on any /v1 request.

Your first request

cURL

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

Base URL

The public base URL is owned by the platform. The upstream geolocation service is an internal data source and is never addressed directly by your integration.

In your language

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" },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error.message);
}

const location = await response.json();
console.log(location.country.code, location.city);

import { request } from "node:https";

const options = {
  hostname: "api.geolocate-api.dev",
  path: "/v1/ip/8.8.8.8",
  headers: { Authorization: "Bearer geo_live_xxxxxxxxxxxxxxxxx" },
};

request(options, (response) => {
  let body = "";
  response.on("data", (chunk) => (body += chunk));
  response.on("end", () => console.log(JSON.parse(body)));
}).end();

import requests

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

location = response.json()
print(location["country"]["code"], location["city"])

<?php

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

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

echo $location["country"]["code"] . " " . $location["city"];