IP geolocation database geoip
The IP geolocation database in use (provider > built-in), node rollout progress and address lookup.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/geoipGet IP geolocation database status
Authentication: Admin only
/api/v2/geoip/lookupLook up an IP's geolocation
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
ipRequired | string | IPv4 or IPv6 address. |
IP geolocation database object
| Field | Type | Description |
|---|---|---|
active | GeoipActive | The database currently delivered to nodes and the state of each source; empty sha256 means not resolved yet (nodes use the built-in database from their package). |
country | string | Country/region code (ISO 3166-1 alpha-2), empty if unknown. |
coverage | GeoipCoverage | Coverage comparison of the free and commercial tiers, carried by the license; a side without statistics is omitted (the page shows a dash), whether or not the commercial tier is enabled. |
found | boolean | The address is in the database (at least one field has a value). |
ip | string | The queried address. |
isp | string | ISP code, empty if unknown. |
nodes | GeoipNodes | Node rollout progress (by the database each node reports in its heartbeat). |
prov | string | Province code (mainland China only), empty if unknown. |
region_enabled | boolean | Always true. Province/carrier is open to the free edition too; the field is kept for older frontends. |
source | string | Source of the database in use: provider (from the provider), builtin (built-in). |
tier | string | Tier currently delivered to nodes: biz (provider-delivered commercial database) or free (built-in). |
version | string | Version of the database in use. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}