Confidence and warnings
How sure an answer is, and how the API tells you what it couldn't settle.
Verify reports uncertainty instead of hiding it. A parse carries a confidence and warnings; a lookup carries a matchConfidence, a status and flags such as unit_required and fuzzy. Read them together: a high score doesn't make a warning go away.
Parse confidence
confidence is a number from 0 to 1: the model's average certainty about the label it gave each word (house number, street name, city, and so on).
- It measures how sure the model is of how it split the line, not whether the address exists. A clean parse of an address that doesn't exist can score close to 1.
- Below 0.6, the answer adds a
low_confidencewarning. - When the parse is structurally wrong or out of scope (a suffix with no street name, an intersection, a non-US address), confidence is capped at 0.5.
- An empty line has confidence
0and anempty_inputwarning.
Warnings
Each warning has a code, a message, and for problems in one part of the input, start and end offsets into input, so you can highlight the text in a UI.
{
"code": "ambiguous_city_street",
"message": "street name \"via christna\" runs into the city with no suffix and no separator; the boundary is a guess",
"start": 5,
"end": 23
}Warnings fall into a few groups:
| Group | Codes | Usually means |
|---|---|---|
| Missing parts | missing_address_number, missing_street_name, missing_city, missing_state, missing_zip, unit_without_id, unit_id_without_type | The input is incomplete. A lookup may still work: it needs a street and a ZIP or city. |
| Invalid values | invalid_zip, invalid_state, unknown_suffix, unknown_unit_designator | A value isn't in USPS Publication 28's tables. It's kept as typed. |
| Guesses | ambiguous_type, ambiguous_city_street, discontiguous_component, unknown_tokens, low_confidence | The split is uncertain. Show it to a person, or ask for a cleaner input. |
| Out of scope | unsupported_intersection, possibly_foreign, dual_address, empty_input | The line isn't a single US delivery address. |
| Formatting | leading_zero_removed, line_overflow | Informational. |
| Fallback | model_unavailable, model_output_invalid | The rule-based fallback answered instead of the model. |
The full list with meanings is in Parse an address.
The parser doesn't fix spelling. 1509 via christna vista ca keeps VIA CHRISTNA; the lookup's near-miss matching is what connects it to the right street.
Match confidence
matchConfidence (on a lookup and on each candidate) is a number from 0 to 1 for how closely the input matched the parcel's address. It isn't a probability.
- 1 means the house number, street name, and any suffix, directions and unit you sent all matched exactly.
- It's lower when the match needed slack: the input left out a suffix or direction the parcel has, a suffix or direction differed, the unit matched only in part, or the street name was a near miss (
fuzzy: true). - A building matched without the unit you named, or a condo building with no unit given, scores below a full match.
- A
no_situs_parcelanswer always scores low. - When there's no single parcel (
ambiguous,not_found), the top-levelmatchConfidenceis0. Look at each candidate's score instead.
Use status to decide what happened, and matchConfidence to rank or to flag answers for review.
Fuzzy matches
When no street matches exactly, the lookup tries near-miss street names (typos and spelling variants). A hit sets fuzzy: true on the answer (and on matching candidates) and lowers matchConfidence:
{
"status": "matched",
"fieldgeist_id": "adr_01JA2Z3Y4X5W6V7T8S9R0QPSP1",
"matchConfidence": 0.72,
"fuzzy": true,
"...": "..."
}Near-miss matching only applies to real near misses. A street that isn't close to any known street returns not_found.
Explicit uncertainty
Some answers are uncertain by design. They're answers, not errors, and they're billed:
ambiguous: more than one parcel fits. See Look up a parcel.unit_required: the building has unit parcels and the input didn't name one that exists. See Condos and units.