API reference

GET/healthz

Auth: None (public endpoint)

Service health

Returns service status and the ids of the currently active geocoding providers. Free, unauthenticated.

Responses

{
  "status": "ok",
  "providers": [
    "bag"
  ]
}

POST/v1/validate

Auth: Secret API key

Validate an address

Validates a single address and returns a verdict, a 0-100 confidence score, the standardized address, per-component comparison results, and a provider-consensus report. Provide either a free-form query or structured components (at least one is required).

Costs 1 credit per provider that answered; a cache hit or a request where no provider answers costs 0.

Parameters

Request body

Provide query, components, or both. At least one is required.

{
  "query": "Prinsengracht 263, Amsterdam",
  "country": "NL"
}

{
  "components": {
    "street": "Prinsengracht",
    "houseNumber": "263",
    "postcode": "1016 GV",
    "city": "Amsterdam",
    "country": "NL"
  }
}

{
  "query": "Prinsengracht 263, Amsterdam",
  "country": "NL",
  "debug": true
}

Responses

{
  "verdict": "correctable",
  "confidence": 84,
  "address": {
    "street": "Prinsengracht",
    "houseNumber": "263",
    "postcode": "1016 GV",
    "city": "Amsterdam",
    "country": "NL",
    "lat": 52.3752,
    "lng": 4.8836
  },
  "components": {
    "street": "corrected",
    "houseNumber": "match",
    "city": "corrected",
    "country": "match"
  },
  "provider": "bag",
  "reasons": [
    "components_corrected"
  ],
  "consensus": {
    "status": "single-provider",
    "score": null,
    "baseConfidence": 84,
    "confidenceDelta": 0,
    "supportingProviders": [
      "bag"
    ],
    "conflictingProviders": [],
    "disagreements": []
  },
  "cached": false
}

{
  "message": "Validation failed",
  "issues": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": [
        "query"
      ],
      "message": "Too small, expected string to have >=1 characters"
    }
  ]
}

{
  "message": "Missing API key. Send it as: Authorization: Bearer ak_live_…"
}

{
  "message": "Malformed API key"
}

{
  "message": "Unknown or revoked API key"
}

{
  "message": "Monthly credits exhausted (500 plan credits on the free plan). Upgrade or buy credits at https://geoverdict.com/dashboard"
}

POST/v1/autocomplete

Auth: Secret API key

Autocomplete an address

Returns up to limit (default 5) address suggestions for a partial query. Suggestions are deduplicated across providers.

Each uncached call costs 1 credit per provider that answered. A cache hit or a request where no provider answers costs 0. sessionToken is echoed back for client-side correlation only; it does not deduplicate billing.

For browser-side autocomplete use the embeddable widget with a publishable token (/v1/widget/autocomplete) instead of exposing a secret key.

Parameters

Request body

{
  "query": "Prinsengracht 26",
  "country": "NL",
  "limit": 5
}

Responses

{
  "suggestions": [
    {
      "label": "Prinsengracht 263, 1016GV Amsterdam",
      "components": {
        "street": "Prinsengracht",
        "houseNumber": "263",
        "postcode": "1016 GV",
        "city": "Amsterdam",
        "country": "NL"
      },
      "location": {
        "lat": 52.3752,
        "lng": 4.8836
      },
      "provider": "bag"
    }
  ],
  "sessionToken": null,
  "cached": false
}

{
  "message": "Validation failed",
  "issues": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": [
        "query"
      ],
      "message": "Too small, expected string to have >=1 characters"
    }
  ]
}

{
  "message": "Missing API key. Send it as: Authorization: Bearer ak_live_…"
}

{
  "message": "Malformed API key"
}

{
  "message": "Unknown or revoked API key"
}

{
  "message": "Monthly credits exhausted (500 plan credits on the free plan). Upgrade or buy credits at https://geoverdict.com/dashboard"
}

POST/v1/widget/autocomplete

Auth: Publishable widget token

Browser widget autocomplete

Browser-safe autocomplete for the embeddable GeoVerdict widget. Authenticates with a project-scoped publishable token (gv_pk_live_... / gv_pk_test_...) and requires a request Origin on the token's exact HTTPS origin allowlist. Secret API keys (ak_...) and console sessions are rejected.

Suggestions are mapped to a browser-safe shape with opaque ids; provider-native identifiers and raw metadata are never returned. Per-token and per-origin rate limits of 120 requests/minute apply in addition to the account credit gate. Billing matches server autocomplete: 1 credit per answering provider per uncached call.

Most integrations should not call this endpoint directly; the hosted widget (https://geoverdict.com/widget/v1/geoverdict-autocomplete.js) implements the contract, keyboard navigation, and accessibility.

Parameters

Request body

{
  "query": "Prinsengracht 26",
  "country": "NL",
  "limit": 5,
  "sessionToken": "3f5a1c9e-session",
  "source": "widget"
}

Responses

{
  "suggestions": [
    {
      "id": "gv_s_1f7c0a92be34d56e78a90c12",
      "label": "Prinsengracht 263, 1016GV Amsterdam",
      "provider": "bag",
      "address": {
        "street": "Prinsengracht",
        "houseNumber": "263",
        "postcode": "1016 GV",
        "city": "Amsterdam",
        "country": "NL"
      }
    }
  ],
  "sessionToken": "3f5a1c9e-session",
  "cached": false
}

{
  "message": "Validation failed",
  "issues": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": [
        "query"
      ],
      "message": "Too small, expected string to have >=1 characters"
    }
  ]
}

{
  "message": "Unknown, revoked, or origin-restricted publishable token"
}

{
  "message": "A permitted HTTPS Origin is required"
}

{
  "message": "Widget autocomplete rate limit reached"
}

{
  "message": "Monthly project credits exhausted"
}

OPTIONS/v1/widget/autocomplete

Auth: None (public endpoint)

Widget CORS preflight

CORS preflight for the widget endpoint. Because browsers omit the Authorization value during preflight, the server reflects an origin only when an active publishable token currently allows it; the subsequent POST still binds the exact token and origin.

Parameters

Responses

GET/v1/usage

Auth: Secret API key

Usage and credit balance

Current-month credit consumption plus recent activity for the account that owns the API key. This call consumes no credits and never writes a usage event, but the shared API-key quota gate still returns 429 after the account exhausts its credits. Displays can lag the ledger by up to 60 seconds.

Parameters

Responses

{
  "plan": "free",
  "quota": 500,
  "extraCredits": 0,
  "creditsUsedThisMonth": 42,
  "environment": "test",
  "filteredBySource": null,
  "daily": [
    {
      "day": "2026-08-02",
      "n": 12,
      "credits": 10
    }
  ],
  "summary": [
    {
      "endpoint": "validate",
      "verdict": "valid",
      "n": 30,
      "credits": 28
    }
  ],
  "sources": [
    {
      "source": "checkout",
      "n": 25,
      "credits": 22
    },
    {
      "source": "",
      "n": 17,
      "credits": 20
    }
  ],
  "recent": [
    {
      "endpoint": "validate",
      "verdict": "valid",
      "provider": "bag",
      "latency_ms": 132,
      "cached": 0,
      "credits": 1,
      "query": "Prinsengracht 263, Amsterdam",
      "source": "checkout",
      "at": "2026-08-02 14:03:11"
    }
  ]
}

{
  "message": "Missing API key. Send it as: Authorization: Bearer ak_live_…"
}

{
  "message": "Malformed API key"
}

{
  "message": "Unknown or revoked API key"
}

{
  "message": "Monthly credits exhausted (500 plan credits on the free plan). Upgrade or buy credits at https://geoverdict.com/dashboard"
}

POST/demo/validate

Auth: None (public endpoint)

Homepage demo validation

Unauthenticated validation used by the geoverdict.com homepage demo. It defaults to the Netherlands (country: NL), but honors a trailing ISO alpha-2 country code in the query, and costs 0 credits. The three queries shown on the homepage use stable provider-free responses. Other queries check the engine cache first; cache hits do not consume demo allowance. Only cache misses are rate limited per visitor IP over rolling windows: 10 requests / 5 minutes, 20 / 24 hours, 50 / 7 days, and 200 / 30 days. Not intended for production integrations; use /v1/validate with an API key instead.

Request body

{
  "query": "prinsengrach 263, amsterdm"
}

Responses

{
  "message": "Type an address first"
}

{
  "message": "Demo request allowance reached.",
  "limits": [
    {
      "window": "five_minute",
      "max": 10,
      "periodSeconds": 300,
      "retryAfterSeconds": 233
    }
  ],
  "retryAfterSeconds": 233,
  "freeMonthlyCredits": 500
}