API

IP location

Bound where an IPv4 or IPv6 address physically sits using speed-of-light RTT constraints, and verify or refute region claims.

On this page

Locate an IP & verify claims
Cost & zero-credit silent-target guarantee
Read an answer again

Locate an IP & verify claims

POST/v1/geolocate

Answers 200 with the speed-of-light location bound, target network classification, per-VP exclusion proof, and optional claim verdict.

Field	Required	What it is
`target`	Yes	Public IPv4 or IPv6 literal.
`mode`	No	`cached` (default) returns a 7-day cached bound when available and no `claim` is attached. `fresh` dispatches live probes.
`max_credits`	No	Maximum credits this query may spend (`1..60`, default `60`).
`claim`	No	Optional `{ country?, lat?, lon?, radius_km? }` assertion to test against physical `2/3 c` fiber propagation bounds.

Request body with country claim check

{
  "target": "140.82.112.4",
  "mode": "fresh",
  "max_credits": 30,
  "claim": { "country": "US", "lat": 39.83, "lon": -98.58, "radius_km": 2300 }
}

Response

{
  "id": "geo_9f4a21c8e1104b20",
  "ip": "140.82.112.4",
  "confidence": "high",
  "radius_km": 118,
  "point": null,
  "country": "US",
  "city": "Ashburn",
  "target_class": "datacenter",
  "class_source": "asn_heuristic",
  "asn": 36459,
  "as_name": "GitHub, Inc.",
  "anycast": false,
  "gateway": false,
  "method": "cbg_icmp",
  "vps_used": 4,
  "probes": [
    {
      "country": "US",
      "asn": 7922,
      "network_class": "residential",
      "probe_kind": "icmp",
      "rtt_ms": 6.84,
      "exclusion_radius_km": 809.0
    },
    {
      "country": "DE",
      "asn": 24940,
      "network_class": "datacenter",
      "probe_kind": "icmp",
      "rtt_ms": 79.12,
      "exclusion_radius_km": 8037.0
    }
  ],
  "prior": {
    "country": "US",
    "city": "Ashburn",
    "asn": 36459,
    "as_name": "GitHub, Inc.",
    "attribution": "IP Geolocation by DB-IP (https://db-ip.com)"
  },
  "measured_at": "2026-11-13T10:28:12Z",
  "credits_charged": 6
}

In the answer	What it is
`id`	Query identifier for reading the result again via `GET /v1/geolocate/{id}`.
`confidence`	`high`, `medium`, `low`, or `none` (when the target drops all probes).
`radius_km`	Speed-of-light uncertainty radius in kilometres (`0` when `confidence` is `none`).
`target_class`, `asn`, `as_name`	Network classification (`datacenter`, `residential`, `mobile`, `satellite`, `anycast`) and autonomous system metadata.
`probes`	Privacy-safe vantage proof rows (`country`, `asn`, `network_class`, `probe_kind`, `rtt_ms`, `exclusion_radius_km`). Never contains node IDs or node IPs.
`claim` / `claim_check`	Verdict comparing RTT exclusion disks against your submitted `claim` (`consistent` / `plausible`, `refuted` / `implausible`, `undetermined` / `inconclusive`, or `delay_inflated`).
`prior`	Database prior (`country`, `city` when non-residential, and required DB-IP CC BY 4.0 `attribution`: `"IP Geolocation by DB-IP (https://db-ip.com)"`).
`credits_charged`	Actual credits settled (`0` when the target is completely silent).

Cost & zero-credit silent-target guarantee

A cached lookup costs 5 credits. A fresh triangulation reserves up to max_credits (default 60) and settles 1 credit per usable vantage observation. If a target is completely silent (vps_used == 0, no ICMP or TCP 443/80 reply), Hopbits returns confidence: "none", radius_km: 0, charges `0` credits, and skips the 7-day cache so you never pay for an unresponsive host.

Read an answer again

GET/v1/geolocate/{id}

Returns a previously stored geolocation result isolated to the requesting account.