Sign in
geo

Get the freshness of the geolocation database

Changed on
get/geo/status

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/geo/status
  • Auth: HTTP bearer

Response

Geolocation database status retrieved

age_daysinteger nullable

Age in days of the loaded data, from build_time when known and from last_refreshed_at otherwise

build_epochinteger nullable

MaxMind build_epoch of the loaded database (Unix seconds)

build_timestring nullable

When MaxMind built the loaded data (ISO 8601, UTC)

is_staleboolean required

Whether age_days has passed stale_after_days, or the last check failed

last_check_atstring nullable

When a refresh was last attempted, successful or not (ISO 8601, UTC)

last_check_statusstring nullable

ok or error for the most recent refresh attempt; null when none has run yet

last_errorstring nullable

Redacted reason the last refresh failed, so an operator can act on it without reading server logs

last_refreshed_atstring nullable

When new database bytes were last installed (ISO 8601, UTC)

license_key_configuredboolean required

Whether a MaxMind license key is configured. The key itself is never returned, logged, or persisted.

refresh_interval_hoursinteger required

How often the scheduled refresh job runs

sourcestring nullable

Where the loaded database was downloaded from: maxmind_official when a license key is configured, bundled_github otherwise. null when no refresh has run yet (the database was provisioned by the operator).

stale_after_daysinteger required

Age after which this instance treats the database, and cached IP lookups, as stale

Example response

{
  "age_days": 3,
  "build_epoch": 1767225600,
  "build_time": "2026-09-01T02:00:00Z",
  "last_check_at": "2026-09-17T03:14:00Z",
  "last_check_status": "ok",
  "last_error": "Geo database download from source 'maxmind_official' failed: HTTP 401",
  "last_refreshed_at": "2026-09-01T03:14:00Z",
  "license_key_configured": true,
  "refresh_interval_hours": 24,
  "source": "maxmind_official",
  "stale_after_days": 30
}

Changes

  • 4b228ebed583Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 1dc3e6788214Revision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status