Quickstart

Validate your first address in under five minutes. GeoVerdict is one HTTP API in front of multiple geocoding providers, returning a single normalized verdict and confidence score.

1. Get a free API key

Sign up at geoverdict.com with your email address. The sign-up flow creates your account and your first API key, shown exactly once. The free plan includes 500 credits per month, no card required.

You can create more keys any time in the console: open a project, then Keys → Create key. Keys look like this:

ak_live_nZ3f…   # secret server-side key, shown once at creation

2. Make your first call

Send the key as a bearer token. Validate a free-form address:

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

Or with structured components when your form already has separate fields:

curl -s https://geoverdict.com/v1/validate \
  -H "Authorization: Bearer $GEOVERDICT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "components": {
      "street": "Prinsengracht",
      "houseNumber": "263",
      "postcode": "1016 GV",
      "city": "Amsterdam",
      "country": "NL"
    }
  }'

3. Read the response

{
  "verdict": "valid",
  "confidence": 100,
  "address": {
    "street": "Prinsengracht",
    "houseNumber": "263",
    "postcode": "1016 GV",
    "city": "Amsterdam",
    "country": "NL",
    "lat": 52.3752,
    "lng": 4.8836
  },
  "components": {
    "street": "match",
    "houseNumber": "match",
    "city": "match",
    "country": "match"
  },
  "provider": "bag",
  "reasons": [],
  "cached": false
}

Three fields do most of the work:

• valid — the best provider result matched the checked input components at or above your configured confidence threshold.
• correctable — found, but something was fixed. address carries the standardized version; offer it to the user or apply it.
• invalid — could not be verified to the configured threshold. reasons says why.

A valid verdict verifies the address against the available provider data; it is not a guarantee that a carrier can deliver to it. Apply your own business rules where deliverability or identity assurance matters.

confidence is a unified 0–100 score, comparable across providers, and components shows exactly how each part of the input compared. See Verdicts & confidence for the full model.

Next steps