GeoIP API

The GeoIP API returns country and network information for an IP address, plus country metadata and available threat flags. Use these signals for regional personalization and investigation. Results depend on the installed IP dataset; coordinates, flags, and complete country metadata are not guaranteed.

Intelligence Resolution (Geo-Location)

Retrieve the full intelligence profile for a specific IPv4 address. This includes Autonomous System (AS) data, high-level geolocation, and localized jurisdictional metadata.

GET

/2026-02-01/geoip/ip.json

Required permissiongeoip:read

Path, query, and header parameters

ipstring· queryRequired

The targeted IPv4 address for resolution (e.g., 8.8.8.8).

Responses

IP intelligence profile successfully resolved.

{
  "requested_ip": "8.8.8.8",
  "geolocation": {
    "as_domain": "google.com",
    "as_name": "Google LLC",
    "asn": "AS15169",
    "continent": "NA",
    "country": "US",
    "country_name": "United States"
  },
  "country_metadata": {
    "name": "United States",
    "phone": [
      1
    ],
    "capital": "Washington D.C.",
    "currency": [
      "USD",
      "USN",
      "USS"
    ],
    "languages": [
      "en"
    ]
  },
  "threats": [
    "proxy",
    "vpn"
  ],
  "_credits": "IP address data powered by https://ipinfo.io"
}

The provided IP address is malformed or resolution failed.

{
  "error": "Unable to get info for this IP Address"
}

Request examples

curl --request GET 'https://api.hub.donutwork.com/2026-02-01/geoip/ip.json?ip=8.8.8.8' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch('https://api.hub.donutwork.com/2026-02-01/geoip/ip.json?ip=8.8.8.8', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + process.env.DONUTWORK_API_KEY,
  },
});
const requestId = response.headers.get('x-request-id');
if (!response.ok) {
  const error = await response.text();
  throw new Error(`${response.status} ${error} [${requestId}]`);
}
const contentType = response.headers.get('content-type') ?? '';
const data = response.status === 204 ? null
  : contentType.includes('application/json') ? await response.json()
  : await response.text();

$request = curl_init('https://api.hub.donutwork.com/2026-02-01/geoip/ip.json?ip=8.8.8.8');
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('DONUTWORK_API_KEY'),
    ],
]);
$response = curl_exec($request);
if ($response === false) {
    $error = curl_error($request);
    curl_close($request);
    throw new RuntimeException($error);
}
$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$contentType = (string) curl_getinfo($request, CURLINFO_CONTENT_TYPE);
curl_close($request);
if ($status >= 400) { throw new RuntimeException($response); }
$data = $status === 204 ? null
    : (str_contains($contentType, 'application/json')
        ? json_decode($response, true, flags: JSON_THROW_ON_ERROR) : $response);

Replace uppercase placeholders and sample values with your own data and company resource IDs. Keep the API key on a trusted server. Reuse an idempotency key only for the same logical request and payload.

Technical Implementation

IP-derived location is an approximate signal. Combine it with verified customer information and the requirements of your use case when selecting billing or regional policies.

GeoIP (Location Services)