Version 2.4.8 · latest

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.

Operations and systemAuthentication: Admin only2 endpoints

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.

GET/api/v2/geoip/lookupLook up an IP's geolocation

Authentication: Admin only

Query parameters

FieldTypeDescription
ipRequiredstring IPv4 or IPv6 address.

IP geolocation database object

FieldTypeDescription
activeGeoipActive 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).
countrystring Country/region code (ISO 3166-1 alpha-2), empty if unknown.
coverageGeoipCoverage 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.
foundboolean The address is in the database (at least one field has a value).
ipstring The queried address.
ispstring ISP code, empty if unknown.
nodesGeoipNodes Node rollout progress (by the database each node reports in its heartbeat).
provstring Province code (mainland China only), empty if unknown.
region_enabledboolean Always true. Province/carrier is open to the free edition too; the field is kept for older frontends.
sourcestring Source of the database in use: provider (from the provider), builtin (built-in).
Values ["provider","builtin"]
tierstring Tier currently delivered to nodes: biz (provider-delivered commercial database) or free (built-in).
Values ["free","biz"]
versionstring 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command