Validate an address (versioned alias)

ISO-3 country code, lowercase. Any country in the acceptance set (~223 live today — see Country codes in the API description) validates and returns the best tier its reference data supports; inspect accuracy_type. Highest-precision coverage includes usa, can, gbr (served from the PAF host — see Servers), deu, aut, che, fra, esp, bel, nld, dnk, fin, swe, nor, ita, jpn, sgp, among others. country_code and countryCode are accepted as aliases of this field.

API key in the body (legacy). Header auth is preferred.

Ignored. Same reference DB as geocode (ref_dbs.json).

verified = the street and house number matched exactly; postcode/locality repairs derived unambiguously from the matched premise may still appear in corrections (with postcode_corrected: true and confidence_level capped at medium) without demoting status. corrected = the street or city itself required a value-changing correction (fuzzy match above the 0.85 similarity threshold, or standardized fields). Omitted (with partial_match: true) when the address could not be verified. Standardization is never a correction: for a city-state (Singapore, Monaco) the city implied by the country — filled in when you omit it, or typed as an alias such as SG / Republic of Singapore — does not appear in corrections and does not make the status corrected; nor do Singapore street-type abbreviations (Jln = Jalan, Bt = Bukit, Ave, Cres, Cl, …). A genuinely different city or a misspelt street is still reported.

1.0 for a verified match; the similarity score (0.85–1.0) for a corrected match — but capped at match_score (0.2–0.6) whenever a street or house number you PROVIDED could not be confirmed against the matched record (e.g. the match fell back to a different street, or the house number is not on file). confidence_level is demoted to low in the same cases.

Plain confidence grade for bulk-CSV workflows. high = confirmed exact, medium = confirmed with safe corrections, low = partial/approximate (e.g. house number not found, or a locality/admin-area centroid only), none = no match.

What the returned coordinate represents. null on no_match.

This is an OPEN set. New tiers are added as reference data improves. Clients MUST pass unrecognized values through rather than throwing, and SHOULD branch on point_coordinate rather than on these literals.

A point coordinate identifies one address:

• rooftop — a point on the building itself.
• arrival_point — the address's entrance, gate or curb-side access point. A point for this address, typically a few metres from the roof — deliberately not claimed as the building footprint.

Everything else is derived rather than observed — a segment or an area, not an address:

• street_interpolated — HNO estimated along a street segment polyline (SEG cascade) from the position of neighbouring house numbers.
• street_centroid — street confirmed; exact HNO not located. Singapore: block numbers are not linear along a road and a letter-suffixed block (e.g. 700D) is a separate building with its own postcode, so Singapore never returns street_interpolated. An unconfirmed block (or a street with no block) answers street_centroid at the street's centre, and standardized.postcode is left empty unless you supplied a postcode that exists on that street — a postcode names one building, and another building's postcode is never shown as yours.
• landmark_proximity — India only. The address itself resolved no further than its postcode/locality, so the coordinate is that of a LANDMARK the caller named in the input ("opp. Swami Samarth Math"). It is a point on a neighbouring place, never the address, and it is only ever used when it out-ranks what would otherwise be returned. The landmark used is named back to you in landmark_used (name, matched_from, scope, source).
• postcode_centroid — only postcode matched.
• locality_centroid — only city/locality matched.
• admin_centroid — only admin region (state/province) matched.

true when the coordinate identifies one address (rooftop or arrival_point), false for any derived/area tier. Branch on this rather than on accuracy_type literals — it stays correct when new tiers are added. Emitted on matches and street-tier partials; omitted on postcode/locality/admin-centroid fallbacks.

Internal/legacy precision tier with the score table below. New clients should prefer accuracy_type for branching.

Unlike accuracy_type, this enum is CLOSED — the score table is fixed and no further values will be added. An arrival_point coordinate is reported here as rooftop, because the address is premise-verified either way; only accuracy_type states what the coordinate is. Score table:

• rooftop → 1.0
• parcel_centroid → 0.9
• interpolated → 0.8
• street_level → 0.6
• zip_centroid → 0.4
• city_centroid → 0.2
• no_match → 0.0
• non_deliverable → 0.0 — the input is a PO Box / Rural Route / Postfach etc. and can never resolve to a street address (USA/CAN/MEX/DEU/AUT/CHE detection). Returned on the 400 body (with non_deliverable_type) unless iso20022: true opted in to a labelled 200.

true when the address could not be fully verified but a coordinate was still produced — at street level (street_interpolated / street_centroid: street confirmed, house number not) or via the SEG cascade (postcode / locality / admin centroid). Absent or false on full verified/corrected matches. The response still carries standardized, but it echoes the caller's input for every component that could not be verified (only the components confirmed in match_components are reference data) — treat lat/lng as the only trustworthy output, and check reasons for what could not be pinned down.

With street_postcodes, how many postcodes the street covers (not capped).

With street_postcodes, true when the street covers more postcodes than are listed.

Portugal only, optional. true when the point is a town / area centre standing in for the address: a city- or neighbourhood-only request (reason street_missing), a street that could not be placed (reason fell_back_to_locality), or an estate / urbanisation name sent with a town we can place (reasons street_not_found + fell_back_to_locality). accuracy_type is then locality_centroid or admin_centroid and confidence is 0.4 or lower. Absent otherwise.

Portugal (country: prt) only. Which kind of place an approximate point (approximate: true) stands for. Open set — pass unknown values through.

• locality — a locality (village / town).
• postal_town — the town name of the postal address.
• municipality — a municipality (concelho).
• district — a district.
• lisbon_parish — a Lisbon parish or neighbourhood name; the point is Lisbon's.

Portugal only, with approximate: true: the name of that place as spelled in the reference data (e.g. Cascais; Lisboa for a Lisbon neighbourhood).

Retained for backward compatibility. New clients should use match_type.

Retained for backward compatibility. Human-readable label (e.g. "Perfect match", "Partial match (street only)").

The house number you sent is not on file for the matched street — either flagged by the matcher itself, or caught by the input-vs-returned comparison (a fallback row carried a different number). standardized keeps YOUR house number in this case; match tier is capped at street_level.

true only when the address verified confidently against the reference data — confidence_level high or medium AND not a partial/centroid fallback AND a premise is identified (a house number you supplied, or a UK premise anchor / named building). This is the same threshold the on-page widget uses for its "valid & deliverable" verdict, so API and UI never disagree. Reflects confirmation against our authoritative reference data; it is not a CASS/DPV-certified delivery guarantee.

The house number was confirmed against an official numbering RANGE for the street, not an individual premise row (interpolated-tier evidence, e.g. Brazil's official street ranges). Caps confidence_level at medium — high is reserved for premise-level verification.

Spain, Latvia and Singapore only. Present and true only when the sub-building unit you sent is listed for the matched building. Spain: staircase / floor / door (e.g. Esc. 1, 1º B) listed for the matched portal in a 2017 building-unit snapshot. It means "listed in that snapshot", nothing more: the snapshot is not current and covers multi-unit portals only. Latvia: the flat is in the State Address Register's dwelling list for the matched building. Singapore: the #floor-unit you sent (e.g. #12-1415, #B2-19) is in the unit list of the matched block; the floor-unit may be written with or without the # marker. Absent when no unit was sent, when no house number was sent, and in every other country. It never changes confidence.

Singapore only. The tenant or shop name (e.g. MCDONALD'S) that text in your input matched at the returned building, exactly as we hold it. The name is not part of the standardized address and never enters formatted_address. Absent when your input carried no tenant name.

Singapore only. The building name that text in your input matched at the returned building, when it differs from standardized.building_name (another name the same building is known by). Absent when it is the same name or none was matched.

Spain, Latvia and Singapore only. What the reference unit list could say about the unit you sent. verified: listed at this building. not_in_list: the building has a unit list and yours is not in it. no_data: no usable list for this building (Spain: portal not covered, ambiguous match, or a single-dwelling portal; Latvia: checked against the State Address Register's dwelling list, and no_data when the building has no registered dwellings, as for single-dwelling houses, or the match is ambiguous; Singapore: the unit lists are not complete for every building, so not_in_list means the unit should be re-checked with the addressee, never that it does not exist, and no_data is returned when the building has no usable list or the list cannot rule the unit out). For not_in_list and no_data the response also lists "unit" in unverified_fields; the address match and confidence are unchanged and your unit is still echoed in standardized.unit. A unit the parser cannot read at all (pta, Oficina 3, Bloque) also answers no_data. Absent when no unit was sent.

The postcode was echoed from the caller, never read from a reference row.

The city was derived from the postcode rather than typed by the caller.

No city was sent; the one in standardized.city was derived from the postcode (or, Netherlands, from the postcode + house number). A disclosure, not a correction. Absent otherwise.

Netherlands: no street was sent; the street in standardized.street is the one that holds the house number at the postcode sent. A disclosure, not a correction (corrections stays empty). Absent otherwise.

The locality matched through a recognised alias (e.g. a USPS alternate city name) rather than the primary name. usps_city and locality_note disclose the specifics where applicable.

USA: the USPS-preferred city name when it differs from the input.

Human-readable note on how the locality was matched (alias / municipality disclosure).

The typed city disagreed with the matched row but was overridden by stronger evidence (street + postcode); disclosed rather than silently dropped.

Postcode-repair forensics — the postcode the caller sent. Also present on its own (without postcode_suggested) when the reasons carry postcode_not_matched (Sweden): the typed postcode matched nothing in the reference data, so it is returned here as typed and standardized.postcode is null.

Postcode-repair forensics — the reference postcode for the matched premise, when it differs from postcode_supplied.

true when the supplied postcode does not fit the matched street/locality at all (rather than being a near-miss).

Malaysia: whether the postcode is held with addresses (stocked), real but with no addresses on file (valid_not_stocked — see the matching reason code), or unknown. Companion fields postcode_place / postcode_state name the postal place when known.

Human-readable form of the served tier (e.g. "postcode centroid"). Display-only; branch on accuracy_type / point_coordinate.

Classification of non-deliverable input (e.g. po_box). Appears on the 400 rejection body, or on the 200 body under iso20022: true.

UK only. Distance in metres between the Royal Mail PAF delivery point and the matched OS Open UPRN coordinate (0.0 is a real and best value). Present when extended UK fields are enabled (on by default).

After keyed validation.