Verdicts & confidence

Every validation returns exactly one verdict and one 0–100 confidence score. Both are computed by comparing the provider's answer against what you actually sent, never by trusting a provider's own confidence.

The three verdicts

How the verdict is decided

In order, for the best-scoring candidate:

1. No candidate at all: invalid, reason no_results.
2. You supplied a house number and the best result's house number is missing or mismatch: invalid, reason no_house_number_match. A confident street-level hit is deliberately not treated as a deliverable address.
3. Confidence at or above the valid threshold and nothing corrected, mismatched, or missing: valid, no reasons.
4. Confidence at or above the correctable threshold: correctable, with reason components_corrected when something was corrected.
5. Otherwise: invalid, reason low_confidence, plus components_incomplete when a component was mismatched or missing.

Reasons taxonomy

A closed set of five values. reasons is an array and is empty for a clean valid.

Component verdicts

The components object reports how each part of your input compared to the result. Only checked components appear.

The confidence score

Confidence is a unified 0–100 integer, comparable across providers. It is built from weighted component agreement:

Each component contributes points by its verdict: match scores 1, corrected 0.7, missing 0.2, mismatch 0, and not-checked is excluded from the weighting entirely. When a provider reports its own confidence, the adapter normalizes it to 0–1 and it blends in at weight 0.25. A per-provider, per-country calibration prior can scale the result (currently 1.0 for every provider, so it has no effect today).

Free-form query input is scored with presence-in-query checks; structured components input gets exact per-field comparison. Structured input therefore produces the more precise score when you have separate form fields.

Matching rules worth knowing

• House numbers carry real postal semantics: 2/B, 2-b, 2 B, and 2B are the same. A letter range 2A-2D contains 2B. A numeric range 2-8 respects street-side parity, so it contains 4 but not 3. The same number with a different suffix scores corrected.
• Postcodes compare digits and letters separately: a Dutch 1234 AB against 1234 AC is corrected, not a mismatch.
• Street and city use normalization (diacritics, casing), Levenshtein similarity, and token/abbreviation containment.

Thresholds

The valid threshold defaults to 85 and is configurable per account (console Settings) between 50 and 99, with optional per-project overrides. The correctable threshold is derived: 25 points below the valid threshold, never lower than 40. At the default that means valid ≥ 85 and correctable ≥ 60.

Raising the threshold makes valid stricter and pushes borderline results into correctable. Lowering it does the opposite. Changing the threshold also changes the cache key, so new settings take effect on the next lookup rather than being masked by cached responses.

Providers behind the verdict

Provider credentials belong to the platform, so you never bring your own keys. Which providers are active is a platform setting; GET /healthz reports the current list, and projects can restrict and reorder the ones they use. Providers that do not cover the requested country are skipped and traced as no-coverage.