# Confidence and warnings (/concepts/confidence-and-warnings)

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 [#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_confidence` warning.
- 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 `0` and an `empty_input` warning.

## Warnings [#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.

```json
{
  "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](/api-reference/parse#warnings).

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 [#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_parcel` answer always scores low.
- When there's no single parcel (`ambiguous`, `not_found`), the top-level `matchConfidence` is `0`. 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 [#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`:

```json
{
  "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 [#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](/api-reference/lookup#statuses).
- `unit_required`: the building has unit parcels and the input didn't name one that exists. See [Condos and units](/concepts/condos-and-units).