My Geocode

Guides

Read a confidence score correctly before you trust it

· 3 min read · My Geocode · #forward-geocoding#confidence#data-quality

A confidence value between 0.0 and 1.0 on a geocoding result looks like a simple pass or fail signal, but treating it that way misses what it is actually measuring.

What confidence measures

Confidence reflects how sure the match is, given the input text, that this particular result is the one the input was referring to. A high confidence score on an ambiguous or oddly formatted input still means the system is confident in its best guess, not that the input was definitely correct or that the location definitely exists as described.

GET /v1/forward?q=Main Street, Springfield&limit=1
{
  "status": "ok",
  "query": "Main Street, Springfield",
  "results": [
    {"formatted": "Main Street, Springfield, IL", "lat": 39.7817, "lon": -89.6501, "type": "address", "precision": "street", "confidence": 0.62, "place_id": "sp901", "components": {}}
  ]
}

A confidence of 0.62 here reflects the fact that many towns share the name Springfield, so even a correct match to one specific Springfield carries some inherent uncertainty about whether it is the Springfield the input meant.

Confidence versus precision

These are two different fields measuring two different things. Precision describes how specific the match is, house, street, or a coarser level. Confidence describes how sure the system is about the match it made. A "house" precision result can still carry a moderate confidence score if the input was ambiguous about which house on which street, and a "street" precision result can carry a high confidence score if the match, though coarse, was unambiguous.

Setting a threshold

Pick a confidence threshold based on what a wrong result would cost you. A threshold of 0.8 or higher makes sense for something automated and consequential, like auto-filling a shipping label with no human review. A lower threshold is reasonable for something with a human checking the result afterward, like a suggestion shown to a customer for confirmation.

Combining with the countries parameter

Ambiguous matches like the Springfield example above are often resolved by narrowing the search with the countries parameter when you already know which country the address should be in, which raises the odds of a high-confidence match on the first try rather than needing a second lookup.

Cost stays the same

Reading confidence correctly does not change what a lookup costs, still one request either way. What it changes is whether you act on the result with the right amount of trust.

Confidence is a specific, narrow signal, not a general correctness guarantee, and reading it that way avoids acting too quickly on a shaky match. Full field definitions are on the forward geocoding docs.

More in Guides