Confidence scores
Understand match evidence and choose an acceptance policy.
Confidence helps your application decide how to handle a candidate. It is not a calibrated probability or an accuracy guarantee, and scores from different providers are not directly comparable.
Scores by provider
| Result | Confidence |
|---|---|
Primary geocode (/v1/geocode) | Address-evidence match score in [0, 0.99], rounded to three decimals |
| Primary search and autocomplete | Ranking score in [0, 1], based on how well the text matched |
| Primary reverse geocoding | Distance-based score in [0, 1] |
| Primary place lookup / resolution | 1 |
| HERE through an SDK | queryScore, or 0 if absent/null |
| Google through an SDK | 0, because the provider supplies no numeric confidence score |
SDKs normalize missing/null confidence to 0, and return numeric scores in [0, 1]. Here 0 can mean the score is unavailable. Google results with score 0 are not measured zero-confidence matches.
The SDK threshold defaults to 0.8 and controls whether to try backups. Many correct matches are capped at exactly 0.80 because one component is missing or disagrees (a misspelled or wrong city, or only a state), so 0.8 accepts them; set 0.85 or higher to require every supplied component to agree, at the cost of more backup calls. If any primary candidate reaches the threshold, the SDK keeps the primary result set. For geocode with backups configured (and both no_results and low_confidence enabled), the SDK sends the threshold as min_confidence, so the API returns only results that reach it and a request with none is metered as no_match; if every backup then fails, the response is empty rather than the low-confidence results. Setting it to 0 keeps any nonempty primary response, including results with unavailable scores. The first nonempty backup wins regardless of its score.
This threshold applies to geocode, search, and reverse geocode. Autocomplete suggestions have no confidence score and do not use low_confidence fallback. Resolution returns the selected address without threshold-based selection or provider fallback.
Geocode match components
For /v1/geocode, the primary API compares the request with each candidate using these weights:
| Component | Weight |
|---|---|
| House number | 35% |
| Street | 35% |
| City | 10% |
| State | 10% |
| ZIP | 10% |
Omitted city/state/ZIP inputs are excluded from the denominator. Missing returned values earn no credit. Source names have no arbitrary trust weights.
House numbers must match exactly, including suffixes, hyphens, and fractions. Street comparison normalizes case, punctuation, common suffixes, compass directions, and Unicode accents. An exact normalized street earns full credit. A single name edit earns 90% street credit when the shorter name has at least eight Unicode characters excluding suffixes/directions; a shorter name earns 60% and has an overall ceiling of 0.80. Multiple edits, different suffixes, conflicting directions, and different numeric street tokens earn no street credit.
City comparison considers locality, localadmin, and borough. County earns half credit only when all three are absent, with a 0.80 ceiling, and cannot override conflicting city fields. US state names/codes and ZIP/ZIP+4 forms are normalized; returned full region names also match.
Conservative ceilings
| Evidence | Maximum before ambiguity adjustment |
|---|---|
| Contradictory house number | 0.35 |
| Unmatched street | 0.55 |
| Short street name with one edit | 0.80 |
| Contradictory state / ZIP / city | 0.45 / 0.65 / 0.80 |
| Missing requested component or unparsed house number | 0.80 |
| Only state / city / ZIP supplied for location | 0.80 / 0.88 / 0.94 |
| Two location fields supplied | 0.96 |
interpolated / fallback match type | 0.85 / 0.50 |
| Missing or unknown match type | 0.95 |
| Explicitly non-address layer without house number | 0.50 |
The lowest ceiling applies; the component score may be lower. Each result's match_type is returned so you can see why a ceiling applied.
Ambiguity and duplicates
Distinct eligible candidates within 0.15 of a candidate's pre-ambiguity score reduce that candidate's score by up to 20%. An equally strong or stronger competing candidate applies the full penalty.
Records count as source duplicates when they have equal nonempty normalized house number/street plus either equal nonempty ZIP codes or coordinates within 30 meters. Known contradictory country or state values prevent deduplication. Duplicates do not compete for ambiguity scoring, but all eligible records remain in the response with their own source names.
Source filtering runs before scoring, so excluding a competitor can change the remaining candidates' scores. Primary geocode results are then sorted by confidence, highest first.
Choose an acceptance policy
Treat the threshold as a provider-selection setting. Inspect the candidate list, required address fields, and provider when deciding whether to accept a match. Evaluate thresholds against labeled addresses representative of your application. Parsing assumes a leading house number, and abbreviation normalization is primarily US-oriented; other address formats and locality aliases may score lower.