Autocomplete & widget

Suggest complete addresses while the user types. Server-side through POST /v1/autocomplete, or in the browser with the embeddable widget and a publishable token.

Server-side: POST /v1/autocomplete

Authenticates with your secret API key, like validation. Send the partial query; get up to limit suggestions back, deduplicated across providers.

curl -s https://geoverdict.com/v1/autocomplete \
  -H "Authorization: Bearer $GEOVERDICT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Prinsengracht 26", "country": "NL", "limit": 5}'

Response:

{
  "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
}

Browser: the autocomplete widget

For checkout and signup forms, use the hosted widget instead of proxying autocomplete through your backend. It is dependency-free, accessible (combobox pattern, keyboard navigation, live region), and authenticates with an origin-restricted publishable token, so no secret ever reaches the browser.

Create a token in the console under your project's Autocomplete widget panel, then:

<label for="address-search">Find your address</label>
<input id="address-search" type="text">
<script src="https://geoverdict.com/widget/v1/geoverdict-autocomplete.js"
  data-input="#address-search"
  data-token="gv_pk_live_REPLACE_WITH_PUBLISHABLE_TOKEN"
  data-country="NL" defer></script>

The script auto-loads its stylesheet, infers the endpoint, and mounts itself. Selected addresses are emitted as a geoverdict:select event and can be mapped straight into your form fields. The full option list (field mapping, theming variables, events, programmatic API, manual-entry fallback) lives in the widget README.

The widget endpoint contract

The widget calls POST /v1/widget/autocomplete. You only need this contract when building your own client instead of using the hosted script:

• Auth: Authorization: Bearer gv_pk_live_… plus a request Origin that exactly matches an HTTPS origin on the token's allowlist. Secret keys and console sessions are rejected.
• Body: identical to /v1/autocomplete (query, country, language, limit, sessionToken, source).
• Response: browser-safe suggestions with an opaque id (prefix gv_s_) instead of provider-native identifiers, plus label, provider, and the structured address:

{
  "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": "client-generated-session-id",
  "cached": false
}

• Rate limits: 120 requests per minute per token and per origin, on top of the account credit gate. Exceeding either returns 429.
• Errors: 403 for a missing or disallowed origin, 401 for a bad token, 429 for rate limits or exhausted credits. See Errors.
• Billing: same as server autocomplete, against the account that owns the token's project.

Suggested flow: autocomplete, then validate

Autocomplete improves input speed; it does not certify deliverability. For addresses that matter (shipping, billing, KYC), validate the selected address server-side with /v1/validate before you commit it. Autocomplete and validation use separate cache entries, so budget for the validation call.