--- title: "Validate an address (versioned alias)" method: POST path: "/v1/validate" tags: ["Versioned aliases (v1)"] --- # Validate an address (versioned alias) `POST /v1/validate` ## Request - Base URL: `https://api.acuris-geo.com` - URL: `https://api.acuris-geo.com/v1/validate` - Auth: one of: - API key in header `X-Acuris-Key` - HTTP bearer - API key in header `X-API-Key` - API key in query parameter `key` - none Versioned alias of `POST /validate` — same handler, same request/response shapes, same billing. Accepts a single-line address string **or** structured fields in `input`, plus required `country`. The API key may be supplied in the `X-Acuris-Key` header or in the JSON body as `key`. **Credits:** `validate=1` Stripe-plan transaction per call. The trial pool decrements **1** regardless. Anonymous callers consume one free slot per IP (per-product daily free limits apply — check remaining via `/validate-credits`; anonymous access is rate-limited per IP). ## Request body - ValidateRequest - `country` string, required: 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. - `input` union: Single-line address string **or** object with `street`, `house_number`, `city`, `postcode`, `state`, `unit`, `floor`, `po_box`, `sublocality`, etc. **`sublocality`** is the administrative tier *below* the city — Vietnamese phường/xã, Indonesian kelurahan, Thai tambon, Philippine barangay. Send it in its own field rather than folding it into `city`, which carries the tier the reference data keys on (in Vietnam, the district). Your own word for the tier is accepted as an alias: `ward`, `sub_locality`, `sub_district`, `subdistrict`, `kelurahan`, `barangay`, `tambon`. It **narrows, it never vetoes**: a sub-locality we do not hold, or one written in a naming scheme newer than the reference data, returns exactly the result the same request returns without it. So it is always safe to send. Wired for **`vnm`** today, where it separates addresses that share a district, street and house number across different wards. Other countries accept and ignore it until their reference data carries the tier. - string - object - `key` string: API key in the body (legacy). Header auth is preferred. - `db_version` string: Ignored. Same reference DB as geocode (ref_dbs.json). ## Response `200` Validation succeeded **or** partial fallback returned. Inspect `partial_match` to distinguish: when `true`, the address was not fully confirmed — either the street resolved but not the house number (`street_interpolated` / `street_centroid`), or the SEG cascade inferred a `postcode_centroid` / `locality_centroid` / `admin_centroid` for `lat`/`lng`. `reasons` states what could not be pinned down. - ValidateResponse: Successful validation **or** centroid-fallback. The canonical form **always lives in `standardized`**. When value-changing corrections were applied, the response carries `status: "corrected"` with a human-readable `corrections` list, and `standardized` holds the corrected canonical form. When neither was attainable but SEG produced a centroid, the response carries `partial_match: true` with `lat`/`lng` set; `standardized` then echoes the caller's input for every component that could not be verified — only the components confirmed in `match_components` are reference data. All responses carry the match-quality contract (`match_type`, `match_score`, `match_components`, `input_corrected`). - `standardized` StandardizedAddress: Canonical address as stored in the reference database. - `street` string - `house_number` string - `city` string: Spain (`/suggest`): for the officially bilingual municipalities the suggestion prints the Castilian name by default (`Alicante`, `Elche`, `San Sebastián`, `Castellón de la Plana`, `Valencia`); if your query already spells the regional form (`Alacant`, `Elx`, `Donostia`, `València`) that spelling is kept. Postcode and coordinates are the same either way, and submitting the suggestion to `/validate` matches the same address. `/validate` itself echoes the spelling you sent. Sweden, city + postcode without a street (`/validate`, `/geocode`): the stored spelling of the locality (`Goteborg`, `göteborg` -> `GÖTEBORG`), as on full matches; an English or variant name (`Gothenburg`) is returned in the stored spelling too, and `/validate` lists `City` under `corrections`. - `state` string: Present for countries with regions (e.g. USA, CAN, AUS, MYS). - `postcode` string - `postcode_formatted` string: The postcode as it is written on a letter, in a field of its own, for integrations that look the postcode up elsewhere. Sweden: `412 50` (`postcode` stays `41250`). Where no written form differs, it equals `postcode`. `postcode` itself is unchanged. Returned by `/validate`. - `country` string - `formatted_address` string: Country-specific pretty-printed form, multi-line. - `street_type` string: The thoroughfare type as its own element, where the reference data carries it separately: Malaysia (`street_type: "Jalan"`, `street: "Melor 1"`), and Canada / France where the split comes straight from the reference columns (France is type-first — `street_type: "Place"`, `street_name: "de la Comédie"`). NOT emitted for the USA, which would need a USPS-suffix parse, nor for German, Dutch, Danish, Swedish or Swiss addresses, where the type is fused into the word (*Eckenbertstraße*) and splitting it is a morphological judgement rather than a field read. - `street_name` string: Canada and France: the bare street name with the type and any directional removed. Companion to `street_type` / `street_suffix`; `street` always holds the full form. - `street_suffix` string: Canada: the directional element (N, SW, …) as its own field. - `street_id` string: France: the reference data's stable identifier for the thoroughfare. - `building_name` string: Hong Kong: the building name from the matched premise. Emitted only when every co-matched row agrees on it — a query resolving to many rows (a tower with hundreds of flats) omits it rather than picking one arbitrarily. Singapore: the building name of the matched block, when it has one (house-number-level matches, and addresses identified by a building or tenant name). It is not part of `formatted_address`. - `level_number` string: Denmark (`etage`) and Hong Kong (floor). Same unambiguity rule as `building_name`, and additionally requires a confirmed house number. - `unit_identifier` string: Denmark (`dør`), the Netherlands (sub-address) and Hong Kong (flat). Same unambiguity rule as `level_number`. - `ine_municipality` string: Spain: the 5-digit INE municipality code of the matched address (leading zeros preserved — always a string). - `nis_code` string: Belgium: the NIS municipality code of the matched address. - `statistical_sector` string: Belgium: the 9-character Statbel statistical sector of the matched address (the trailing hyphen is part of the code, e.g. `"41002A00-"`). This is the key the Belgian enrichment joins on. - `county` string: UK only (`country: "gbr"`). Traditional/postal county, derived from the Royal Mail PAF postcode → county map. - `udprn` string: UK only. Royal Mail Unique Delivery Point Reference Number (PAF) — stable identifier for the delivery point. - `uprn` string: UK only. Ordnance Survey Unique Property Reference Number. Present when the address matches OS Open UPRN. - `unit` string: Sub-building unit, echoed from the caller's input (reference rows carry no unit, so this value is never invented). Rendered into `formatted_address` per country convention (e.g. Canada Post `23-4 Vata Crt`). When the reference data cannot confirm the unit at the matched premise, the response lists `"unit"` in the top-level `unverified_fields` array — the premise match itself still stands. Spain: staircase / floor / door in any common spelling (`ESC.1-PISO 1, PTA.B`, `1º B`, `3º izq`, `bajo`) are normalised to one form, e.g. `Esc. 1, 1º B`; see `unit_verified` / `unit_check`. Latvia: the flat (dzīvoklis) in any common spelling (`Brīvības iela 100 - 5`, `100-5`, `100 dz. 5`, `100 kv. 5`) is returned as the flat number, e.g. `5`, and rendered as `Brīvības iela 100 - 5`; a korpuss (`10k2`, `10 k. 2`) is part of the house number (`10 k-2`), never a unit. - `suburb` string: New Zealand. The NZ Post suburb line between street and post town (`68 Rintoul Street / Newtown / Wellington 6021`). Filled from the matched reference row — including when the caller typed only the city. A suburb typed in the city slot is a verified match, never a `City` correction. - `district` string: Neighborhood / sub-locality where the country convention carries one (e.g. the Turkish mahalle, Austrian Bezirk sublocality). Enriched from the reference row even when the caller omitted it. - `province` string: Italy only. Two-letter province sigla (MI, RM, …) for the mandatory Poste Italiane locality line (`20067 PAULLO MI`). - `dependent_street` string: UK only (Royal Mail PAF dependent thoroughfare). The minor road the house number is addressed on (`18 Latium Close, Holywell Hill`); the parent thoroughfare stays in `street`. - `dependent_locality` string: UK (Royal Mail PAF): village / dependent locality printed between the thoroughfare and the post town. Malaysia: the Taman / Kampung sub-locality line, printed above the postcode line. - `double_dependent_locality` string: UK only (PAF). Sub-locality below `dependent_locality`. - `administrative_county` string: UK only. PAF Administrative County (local authority). Present when extended UK fields are enabled; on some postcodes it is the only county held (`county` blank). - `welsh` object: UK only, Wales. The Welsh-language form of the SAME delivery point (Royal Mail ships Welsh addresses bilingually): `street`, `city` (post town, e.g. CAERDYDD for CARDIFF) and, where they exist, translated `dependent_locality` / `double_dependent_locality` / `dependent_street`. Present on an English-form match when a Welsh counterpart exists. Typing the Welsh form is a verified match, never a `Street`/`City` correction. - `english` object: UK only, Wales. Mirror of `welsh`: the English-language form, present when the matched row is the Welsh one. At most one of `welsh`/`english` appears. - `corrected` StandardizedAddress: Canonical address as stored in the reference database. - `street` string - `house_number` string - `city` string: Spain (`/suggest`): for the officially bilingual municipalities the suggestion prints the Castilian name by default (`Alicante`, `Elche`, `San Sebastián`, `Castellón de la Plana`, `Valencia`); if your query already spells the regional form (`Alacant`, `Elx`, `Donostia`, `València`) that spelling is kept. Postcode and coordinates are the same either way, and submitting the suggestion to `/validate` matches the same address. `/validate` itself echoes the spelling you sent. Sweden, city + postcode without a street (`/validate`, `/geocode`): the stored spelling of the locality (`Goteborg`, `göteborg` -> `GÖTEBORG`), as on full matches; an English or variant name (`Gothenburg`) is returned in the stored spelling too, and `/validate` lists `City` under `corrections`. - `state` string: Present for countries with regions (e.g. USA, CAN, AUS, MYS). - `postcode` string - `postcode_formatted` string: The postcode as it is written on a letter, in a field of its own, for integrations that look the postcode up elsewhere. Sweden: `412 50` (`postcode` stays `41250`). Where no written form differs, it equals `postcode`. `postcode` itself is unchanged. Returned by `/validate`. - `country` string - `formatted_address` string: Country-specific pretty-printed form, multi-line. - `street_type` string: The thoroughfare type as its own element, where the reference data carries it separately: Malaysia (`street_type: "Jalan"`, `street: "Melor 1"`), and Canada / France where the split comes straight from the reference columns (France is type-first — `street_type: "Place"`, `street_name: "de la Comédie"`). NOT emitted for the USA, which would need a USPS-suffix parse, nor for German, Dutch, Danish, Swedish or Swiss addresses, where the type is fused into the word (*Eckenbertstraße*) and splitting it is a morphological judgement rather than a field read. - `street_name` string: Canada and France: the bare street name with the type and any directional removed. Companion to `street_type` / `street_suffix`; `street` always holds the full form. - `street_suffix` string: Canada: the directional element (N, SW, …) as its own field. - `street_id` string: France: the reference data's stable identifier for the thoroughfare. - `building_name` string: Hong Kong: the building name from the matched premise. Emitted only when every co-matched row agrees on it — a query resolving to many rows (a tower with hundreds of flats) omits it rather than picking one arbitrarily. Singapore: the building name of the matched block, when it has one (house-number-level matches, and addresses identified by a building or tenant name). It is not part of `formatted_address`. - `level_number` string: Denmark (`etage`) and Hong Kong (floor). Same unambiguity rule as `building_name`, and additionally requires a confirmed house number. - `unit_identifier` string: Denmark (`dør`), the Netherlands (sub-address) and Hong Kong (flat). Same unambiguity rule as `level_number`. - `ine_municipality` string: Spain: the 5-digit INE municipality code of the matched address (leading zeros preserved — always a string). - `nis_code` string: Belgium: the NIS municipality code of the matched address. - `statistical_sector` string: Belgium: the 9-character Statbel statistical sector of the matched address (the trailing hyphen is part of the code, e.g. `"41002A00-"`). This is the key the Belgian enrichment joins on. - `county` string: UK only (`country: "gbr"`). Traditional/postal county, derived from the Royal Mail PAF postcode → county map. - `udprn` string: UK only. Royal Mail Unique Delivery Point Reference Number (PAF) — stable identifier for the delivery point. - `uprn` string: UK only. Ordnance Survey Unique Property Reference Number. Present when the address matches OS Open UPRN. - `unit` string: Sub-building unit, echoed from the caller's input (reference rows carry no unit, so this value is never invented). Rendered into `formatted_address` per country convention (e.g. Canada Post `23-4 Vata Crt`). When the reference data cannot confirm the unit at the matched premise, the response lists `"unit"` in the top-level `unverified_fields` array — the premise match itself still stands. Spain: staircase / floor / door in any common spelling (`ESC.1-PISO 1, PTA.B`, `1º B`, `3º izq`, `bajo`) are normalised to one form, e.g. `Esc. 1, 1º B`; see `unit_verified` / `unit_check`. Latvia: the flat (dzīvoklis) in any common spelling (`Brīvības iela 100 - 5`, `100-5`, `100 dz. 5`, `100 kv. 5`) is returned as the flat number, e.g. `5`, and rendered as `Brīvības iela 100 - 5`; a korpuss (`10k2`, `10 k. 2`) is part of the house number (`10 k-2`), never a unit. - `suburb` string: New Zealand. The NZ Post suburb line between street and post town (`68 Rintoul Street / Newtown / Wellington 6021`). Filled from the matched reference row — including when the caller typed only the city. A suburb typed in the city slot is a verified match, never a `City` correction. - `district` string: Neighborhood / sub-locality where the country convention carries one (e.g. the Turkish mahalle, Austrian Bezirk sublocality). Enriched from the reference row even when the caller omitted it. - `province` string: Italy only. Two-letter province sigla (MI, RM, …) for the mandatory Poste Italiane locality line (`20067 PAULLO MI`). - `dependent_street` string: UK only (Royal Mail PAF dependent thoroughfare). The minor road the house number is addressed on (`18 Latium Close, Holywell Hill`); the parent thoroughfare stays in `street`. - `dependent_locality` string: UK (Royal Mail PAF): village / dependent locality printed between the thoroughfare and the post town. Malaysia: the Taman / Kampung sub-locality line, printed above the postcode line. - `double_dependent_locality` string: UK only (PAF). Sub-locality below `dependent_locality`. - `administrative_county` string: UK only. PAF Administrative County (local authority). Present when extended UK fields are enabled; on some postcodes it is the only county held (`county` blank). - `welsh` object: UK only, Wales. The Welsh-language form of the SAME delivery point (Royal Mail ships Welsh addresses bilingually): `street`, `city` (post town, e.g. CAERDYDD for CARDIFF) and, where they exist, translated `dependent_locality` / `double_dependent_locality` / `dependent_street`. Present on an English-form match when a Welsh counterpart exists. Typing the Welsh form is a verified match, never a `Street`/`City` correction. - `english` object: UK only, Wales. Mirror of `welsh`: the English-language form, present when the matched row is the Welsh one. At most one of `welsh`/`english` appears. - `status` 'verified' | 'corrected': `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. - `confidence` number, float: 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. - `confidence_level` 'high' | 'medium' | 'low' | 'none': 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. - `corrections` string[]: Human-readable list of corrected input fields (e.g. `["Postal code", "City"]`). `"House number"` appears when the house number in the answer differs from the one you sent because the building was renumbered (Latvia, see `former_address`). - `accuracy_type` string, nullable, required: 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. - `point_coordinate` boolean: `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. - `match_type` 'rooftop' | 'parcel_centroid' | 'interpolated' | 'street_level' | 'zip_centroid' | 'city_centroid' | 'no_match' | 'non_deliverable', required: 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. - `match_score` number, float, required - `match_components` MatchComponents, required: Which input fields were confirmed by the match. - `house_number` boolean, required - `street` boolean, required - `city` boolean, required - `zip` boolean, required - `state` boolean, required - `input_corrected` boolean, required - `reasons` FailureReason[]: Present on `partial_match` responses: why full verification failed (e.g. `street_not_matched`, `house_number_unconfirmed`). The same codes appear on 404/422 error bodies. - `provided_components` MatchComponents: Which input fields were confirmed by the match. - `house_number` boolean, required - `street` boolean, required - `city` boolean, required - `zip` boolean, required - `state` boolean, required - `partial_match` boolean: `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. - `nearby_house_numbers` NearbyHouseNumbers: **Portugal (`country: prt`) only.** Present on a 200 answer when the street was matched but the house number you sent is not in the reference data — the answer is then either street-level (`street_centroid`) or `street_interpolated` at a point between the nearest same-parity house numbers (`pin_between`). It lists which numbers of that street ARE held, on the same side of the street (odd and even numbers usually face each other). Informational only: it never changes the coordinate, tier, confidence or `deliverable`. Sent with reason `house_number_not_in_reference`. Pass unrecognized fields through. - `requested` string: The house number as you sent it. - `parity` string - `before` NearbyHouseNumber - `hno` string - `lat` number, float, nullable - `lng` number, float, nullable - `accuracy` string, nullable: The coordinate tier of that house number (e.g. `rooftop`), `null` without a coordinate. - `has_coordinates` boolean: `false` when the number exists in the reference data without its own coordinate (`lat`/`lng`/`accuracy` are then `null`). - `after` NearbyHouseNumber - `hno` string - `lat` number, float, nullable - `lng` number, float, nullable - `accuracy` string, nullable: The coordinate tier of that house number (e.g. `rooftop`), `null` without a coordinate. - `has_coordinates` boolean: `false` when the number exists in the reference data without its own coordinate (`lat`/`lng`/`accuracy` are then `null`). - `pin_between` string[], nullable: The two held numbers the interpolated point was placed between (both may be the same number, e.g. `41` for a requested `41B`); `null` when the answer is street-level rather than interpolated. - `same_parity_available` string[]: Up to 40 held numbers on the same side nearest to the requested one, in ascending order (letter suffixes such as `2A` included). - `total_doors` integer: Number of distinct house numbers held for the street. - `coordinated_doors` integer: How many of those carry their own coordinate. - `street_postcodes` object[]: Netherlands only, optional. Present only on STREET-LEVEL answers (`accuracy_type` `street_centroid`, `street_segment_centroid` or `street_interpolated`): the postcodes the matched street covers, each with its house-number range. Sorted by `house_number_from`, then `postcode`; at most 50 entries (see `street_postcodes_total` and `street_postcodes_truncated`). Ranges count numeric house numbers only; addresses whose number carries letters are not counted. Absent on rooftop and other house-number-level answers. - `postcode` string - `house_number_from` integer - `house_number_to` integer - `parity` 'odd' | 'even' | 'both': Which side(s) of the street the postcode covers within that range. - `street_postcodes_total` integer: With `street_postcodes`, how many postcodes the street covers (not capped). - `street_postcodes_truncated` boolean: With `street_postcodes`, `true` when the street covers more postcodes than are listed. - `postcode_range` object: Netherlands only, optional. Sent with `street_postcodes` when the street covers MORE THAN ONE postcode: the lowest and highest postcode over the whole street (an outer bound, not a continuous run; `street_postcodes` lists the exact ones). In that case `standardized.postcode` carries `text` instead of a single postcode and `standardized.formatted_address` prints it. Check for this field before treating `standardized.postcode` as one postcode. - `from` string - `to` string - `text` string - `approximate` boolean: 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. - `resolved_level` string: **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. - `resolved_name` string: Portugal only, with `approximate: true`: the name of that place as spelled in the reference data (e.g. `Cascais`; `Lisboa` for a Lisbon neighbourhood). - `enrichment` object: Free geographic enrichment, attached automatically (no extra charge, no request parameter) for eighteen countries — USA, Canada, Germany, Austria, Switzerland, France, United Kingdom, Belgium, Spain, Portugal, Ireland, Netherlands, Finland, Sweden, Luxembourg, Japan, Singapore and Hong Kong — whenever the result is precise enough for a small-area lookup to be trustworthy (gates below). Omitted otherwise — never null, never an empty object. Fields whose geography does not apply to the point are likewise omitted, never null. Sub-fields are country-specific; every layer is public government data. **When it appears** - USA, Canada, Germany, Austria, Switzerland and the France admin fields need a street-accurate coordinate (`rooftop`, `arrival_point`, `street_interpolated` or `street_centroid` — never a postcode/locality/admin centroid, where the point could fall in the wrong small area). - The France `building` block and the whole UK block need a premise-level match (`rooftop` / `arrival_point`). The UK block is keyed on the matched address's `uprn` (ONS National Statistics UPRN Lookup). Great Britain only — Northern Ireland (BT postcodes) carries no block because NI statistical geography is separately licensed. - Finland and the Netherlands are keyed on the validated postcode; the block describes the whole postal area (see its `scope` field), not the individual household. - Japan derives the 500 m JIS X 0410 mesh cell from the coordinate. - Singapore joins on the standardized block number + street; HDB blocks only, so a miss on private housing is normal. - Belgium is keyed on the matched row's 9-character Statbel statistical sector (also emitted as `statistical_sector`); a Belgian postcode spans several sectors, so a postcode-grain join would attribute one sector's figures to all of them. - Spain resolves the 10-digit census section (CUSEC) from the INE Callejero — municipality + street + house-number range + parity — and falls back to municipality level when no range covers the number. The block's `scope` says which tier answered (`census_section` or `municipality`); the parity filter is load-bearing and refuses rather than assigning the wrong side of the street. - Portugal, Ireland, Sweden, Luxembourg and Hong Kong are point-in-polygon on the returned coordinate, each returning a `statistical_area` block whose `code` is that country's finest published unit: Portugal BGRI subsecção (11 chars, block-level), Ireland CSO Small Area (2022), Sweden DeSO, Luxembourg commune (LAU2), Hong Kong Small Subunit Group. - Three Irish Small Areas genuinely overlap (slivers of 38–433 m² from 20 m generalisation). A point inside one is reported as ambiguous rather than silently resolved — picking the smallest area would cross an electoral-district boundary in Carlow. Enrichment can accompany `partial_match: true` when the inferred coordinate still reaches a qualifying tier (e.g. `street_centroid`); postcode-, locality- and admin-centroid fallbacks never carry it. Statistical layers respect the publisher's disclosure control: withheld values are absent from the block — an absent value is not a zero (Swiss hectare grid, Dutch PC6, Japanese age bands) — and German Zensus grid counts are Cell-Key perturbed. Each such block says so in its `note`. - `state_fips` string: USA: 2-digit state FIPS. - `county_fips` string: USA: 5-digit county FIPS (state+county). - `census_tract` string: USA: 11-digit census tract GEOID. Canada: CTUID (urban areas only). - `block_group` string: USA: 12-digit block-group GEOID. - `cbsa` object: USA: Core-Based Statistical Area (metro/micro). Omitted (not null) outside any CBSA. - `code` string - `name` string - `type` 'metro' | 'micro' - `congressional_district` object: USA: 119th-Congress district (`00` at-large; `98`/`99` non-voting). - `state_fips` string - `district` string - `congress` integer - `school_district` object: USA: school district. - `name` string - `type` 'unified' | 'elementary' | 'secondary' - `dissemination_area` string: Canada: 8-digit Dissemination Area UID (province + census division + DA). - `province_code` string: Canada: 2-digit province/territory (SGC). - `census_division` string: Canada: 4-digit census division UID. - `census_subdivision` object: Canada: census subdivision (municipality). - `code` string - `name` string - `cma_ca` object: Canada: Census Metropolitan Area / Census Agglomeration. Omitted outside both. - `code` string - `name` string - `type` 'metro' | 'agglomeration' - `federal_electoral_district` object: Canada: federal electoral district. - `code` string - `name` string - `ags` string: Germany: 8-digit Amtlicher Gemeindeschlüssel. - `ars` string: Germany: 12-digit Amtlicher Regionalschlüssel. - `gemeinde` string: Germany / Austria / Switzerland: municipality name. - `gemeinde_type` string: Germany: municipality kind (Stadt, Gemeinde, Kreisfreie Stadt, …). - `bundesland` object: Germany / Austria: federal state. - `code` string - `name` string - `kreis` object: Germany: district. - `code` string - `name` string - `type` string - `nuts3` string: Germany: NUTS-3 code (e.g. DEA12). - `bundestagswahlkreis` object: Germany: Bundestag electoral constituency. - `number` integer - `name` string - `gkz` string: Austria: 5-digit Gemeindekennziffer. - `politischer_bezirk` object: Austria: political district. - `code` string - `name` string - `regionalwahlkreis` object: Austria: regional electoral constituency. - `code` string - `name` string - `zaehlsprengel` string: Austria: census enumeration district (smallest census unit). - `bfs_nummer` string: Switzerland: BFS municipality number. - `kanton` object: Switzerland: canton — also the Nationalrat electoral constituency. - `number` integer - `code` string - `name` string - `bezirk` object: Switzerland: district. - `number` integer - `name` string - `grossregion` object: Switzerland: major region = Swiss NUTS-2 unit. - `number` integer - `nuts2` string - `name` string - `sprachgebiet` object: Switzerland: official language region — which language to address this customer in. - `language` string: ISO 639-1: de/fr/it/rm - `name` string - `degree_of_urbanisation` object: Switzerland: Eurostat DEGURBA class. - `code` 'city' | 'town_suburb' | 'rural' - `name` string - `stadt_land` 'urban' | 'intermediate' | 'rural': Switzerland: BFS Stadt/Land typology. - `gemeindetyp` object: Switzerland: BFS municipality typology (9 classes); `class` is the 3-fold split. - `code` string - `class` 'urban' | 'periurban' | 'rural' - `agglomeration` object: Switzerland: agglomeration. - `code` string - `name` string - `arbeitsmarktregion` object: Switzerland: labour-market region. - `code` string - `name` string - `macro_region` string - `insee` string: France: INSEE commune code. - `commune` string: France: commune name. - `departement` object: France: département. - `code` string - `name` string - `region` object: France: région. UK: ONS region. - `code` string - `name` string - `iris` object: France: INSEE IRIS statistical district (metropolitan France). - `code` string - `name` string - `type` 'residential' | 'economic_activity' | 'miscellaneous' | 'whole_commune' - `building` object: France, premise-level matches only: the IGN BD TOPO building the coordinate falls on (or the nearest within 8 m). `coord_verified` is true when the point is inside or ≤ 2 m from the footprint. `sub_unit_expected` is true when the building is multi-dwelling and the caller supplied no apartment/unit — the address is probably incomplete. - `coord_verified` boolean - `match_type` 'inside' | 'nearest' - `distance_m` number - `building_type` string: e.g. Unspecified, Church, Castle, … - `usage` string: Residential, Commercial and services, Industrial, … - `usage_secondary` string - `height_m` number - `floors` integer - `dwellings` integer - `is_multi_dwelling` boolean - `rnb_id` string: French national building registry (RNB) id. - `sub_unit_expected` boolean - `source` string - `output_area` string: UK: 2021 Output Area code — finest ONS tier; output areas have no name. - `lsoa` object: UK: Lower layer Super Output Area. - `code` string - `name` string - `msoa` object: UK: Middle layer Super Output Area. - `code` string - `name` string - `local_authority` object: UK: local authority district. - `code` string - `name` string - `ward` object: UK: electoral ward. - `code` string - `name` string - `westminster_constituency` object: UK: Westminster parliamentary constituency. - `code` string - `name` string - `country` object: UK: constituent country (England, Scotland, Wales). - `code` string - `name` string - `police_force_area` object: UK: police force area. - `code` string - `name` string - `rural_urban` object: UK: rural/urban classification. - `code` string - `description` string - `demographics` object: Germany: Zensus 2022 100 m grid — grid_cell, population, avg_age, avg_household_size, avg_net_rent_per_sqm, owner_occupier_pct, vacancy_pct, foreign_national_pct; small counts are Cell-Key perturbed (approximate). Switzerland: BFS STATPOP 100 m hectare grid — hectare_cell, population, buildings, dwellings; withheld cells are absent (an absent value is not a zero). Always carries `note` and `source`. - `economy` object: Switzerland: BFS STATENT hectare-grid workplace stats — hectare_cell, workplaces, employees_fte, note, source. - `postal_area` object: Finland: Statistics Finland PAAVO statistics for the whole postal area (`scope: postal_area`) — names (fi/sv), municipality_code, area_km2, centroid, population + age bands, mean/median incomes (personal and household), employment, jobs_total, households by type/tenure, dwellings, avg_dwelling_area_m2, summer_cottages. CC BY 4.0; `source` inside the block. - `postcode_area` object: Netherlands: CBS Kerncijfers for the six-character postcode (`scope: postcode6_area`) — inhabitants + age bands, households by type, dwellings, avg_home_value_eur, pct_owner_occupied, pct_rented, persons_on_benefits, avg_gas_m3, avg_electricity_kwh. CBS-suppressed cells are absent, never 0. - `mesh_area` object: Japan: 2020 Population Census on the 500 m JIS X 0410 mesh (`scope: mesh_500m`) — mesh_code, pop_total, pop_male, pop_female, pop_0_14, pop_15_64, pop_65_plus, households. Withheld age bands are absent. - `hdb_block` object: Singapore: HDB Property Information for the matched block (`scope: hdb_block`) — bldg_contract_town, max_floor_lvl, year_completed, residential / commercial / market_hawker / multistorey_carpark / precinct_pavilion / miscellaneous flags, total_dwelling_units and the full unit mix (units_1room … units_studio, rental_1room … rental_other). HDB blocks only — private housing has no block. - `statistical_sector_area` object: Belgium: Statbel figures for the address's statistical sector (`scope: statistical_sector`) — municipality NIS code and names (NL/FR), sector names, population, density, area, and median / mean taxable income with its reference year. - `census_section_area` object: Spain: INE figures for the census section resolved from the Callejero (`scope: census_section`), or for the municipality when no house-number range covers the address (`scope: municipality`). Carries `cusec` (10-digit section code) when section-level, plus population, age structure, nationality mix, household size, education breakdown and the household income series (net / gross, per person and per household). `income_top_coded: true` marks INE's censoring ceiling. Withheld figures are absent, not zero. - `statistical_area` object: Portugal, Ireland, Sweden, Luxembourg and Hong Kong: the country's finest published statistical unit, resolved by point-in-polygon on the returned coordinate (`scope: statistical_area`). `code` is the official identifier — Portugal BGRI subsecção (11 chars, block-level, with its dt / dtmn / dicofre components and the Censos 2021 building, dwelling, household and population counts); Ireland CSO Small Area 2022 (~100 dwellings, with SAPS age, tenure, education and commuting); Sweden DeSO (with its RegSO, kommun and län codes); Luxembourg commune LAU2 (with canton, district and STATEC census figures); Hong Kong Small Subunit Group (2021 Census, names in English and Traditional Chinese). ⚠️ Ireland only: three Small Areas overlap in slivers of 38–433 m². A point inside one is reported ambiguous rather than resolved to a single area. - `source` string: Attribution for the country's primary layer (present for USA, Canada, Germany, Austria, Switzerland, France and the UK). Sub-blocks (`demographics`, `economy`, `building`) and the whole-block countries (`postal_area`, `postcode_area`, `mesh_area`, `hdb_block`) carry their own `source` inside the block — there is no top-level `source` for Finland, the Netherlands, Japan or Singapore. Reproduce these strings where the underlying data licence requires attribution (CC BY 4.0, Etalab 2.0, dl-de/by-2-0, Statistics Canada Open Licence, Singapore Open Data Licence). - `match_type_legacy` 'exact' | 'fuzzy': Retained for backward compatibility. New clients should use `match_type`. - `match_score_legacy` string: Retained for backward compatibility. Human-readable label (e.g. `"Perfect match"`, `"Partial match (street only)"`). - `suggestions` Suggestion[]: Ranked near-miss candidates (score ≥ 0.5, below the correction threshold). Appears on 200 `partial_match` responses where the street could not be matched — the closest real streets in the caller's postcode/locality (up to 3 items) — and on 404 no-match responses. Not normally present on verified/corrected successes. - `standardized` StandardizedAddress, required: Canonical address as stored in the reference database. - `street` string - `house_number` string - `city` string: Spain (`/suggest`): for the officially bilingual municipalities the suggestion prints the Castilian name by default (`Alicante`, `Elche`, `San Sebastián`, `Castellón de la Plana`, `Valencia`); if your query already spells the regional form (`Alacant`, `Elx`, `Donostia`, `València`) that spelling is kept. Postcode and coordinates are the same either way, and submitting the suggestion to `/validate` matches the same address. `/validate` itself echoes the spelling you sent. Sweden, city + postcode without a street (`/validate`, `/geocode`): the stored spelling of the locality (`Goteborg`, `göteborg` -> `GÖTEBORG`), as on full matches; an English or variant name (`Gothenburg`) is returned in the stored spelling too, and `/validate` lists `City` under `corrections`. - `state` string: Present for countries with regions (e.g. USA, CAN, AUS, MYS). - `postcode` string - `postcode_formatted` string: The postcode as it is written on a letter, in a field of its own, for integrations that look the postcode up elsewhere. Sweden: `412 50` (`postcode` stays `41250`). Where no written form differs, it equals `postcode`. `postcode` itself is unchanged. Returned by `/validate`. - `country` string - `formatted_address` string: Country-specific pretty-printed form, multi-line. - `street_type` string: The thoroughfare type as its own element, where the reference data carries it separately: Malaysia (`street_type: "Jalan"`, `street: "Melor 1"`), and Canada / France where the split comes straight from the reference columns (France is type-first — `street_type: "Place"`, `street_name: "de la Comédie"`). NOT emitted for the USA, which would need a USPS-suffix parse, nor for German, Dutch, Danish, Swedish or Swiss addresses, where the type is fused into the word (*Eckenbertstraße*) and splitting it is a morphological judgement rather than a field read. - `street_name` string: Canada and France: the bare street name with the type and any directional removed. Companion to `street_type` / `street_suffix`; `street` always holds the full form. - `street_suffix` string: Canada: the directional element (N, SW, …) as its own field. - `street_id` string: France: the reference data's stable identifier for the thoroughfare. - `building_name` string: Hong Kong: the building name from the matched premise. Emitted only when every co-matched row agrees on it — a query resolving to many rows (a tower with hundreds of flats) omits it rather than picking one arbitrarily. Singapore: the building name of the matched block, when it has one (house-number-level matches, and addresses identified by a building or tenant name). It is not part of `formatted_address`. - `level_number` string: Denmark (`etage`) and Hong Kong (floor). Same unambiguity rule as `building_name`, and additionally requires a confirmed house number. - `unit_identifier` string: Denmark (`dør`), the Netherlands (sub-address) and Hong Kong (flat). Same unambiguity rule as `level_number`. - `ine_municipality` string: Spain: the 5-digit INE municipality code of the matched address (leading zeros preserved — always a string). - `nis_code` string: Belgium: the NIS municipality code of the matched address. - `statistical_sector` string: Belgium: the 9-character Statbel statistical sector of the matched address (the trailing hyphen is part of the code, e.g. `"41002A00-"`). This is the key the Belgian enrichment joins on. - `county` string: UK only (`country: "gbr"`). Traditional/postal county, derived from the Royal Mail PAF postcode → county map. - `udprn` string: UK only. Royal Mail Unique Delivery Point Reference Number (PAF) — stable identifier for the delivery point. - `uprn` string: UK only. Ordnance Survey Unique Property Reference Number. Present when the address matches OS Open UPRN. - `unit` string: Sub-building unit, echoed from the caller's input (reference rows carry no unit, so this value is never invented). Rendered into `formatted_address` per country convention (e.g. Canada Post `23-4 Vata Crt`). When the reference data cannot confirm the unit at the matched premise, the response lists `"unit"` in the top-level `unverified_fields` array — the premise match itself still stands. Spain: staircase / floor / door in any common spelling (`ESC.1-PISO 1, PTA.B`, `1º B`, `3º izq`, `bajo`) are normalised to one form, e.g. `Esc. 1, 1º B`; see `unit_verified` / `unit_check`. Latvia: the flat (dzīvoklis) in any common spelling (`Brīvības iela 100 - 5`, `100-5`, `100 dz. 5`, `100 kv. 5`) is returned as the flat number, e.g. `5`, and rendered as `Brīvības iela 100 - 5`; a korpuss (`10k2`, `10 k. 2`) is part of the house number (`10 k-2`), never a unit. - `suburb` string: New Zealand. The NZ Post suburb line between street and post town (`68 Rintoul Street / Newtown / Wellington 6021`). Filled from the matched reference row — including when the caller typed only the city. A suburb typed in the city slot is a verified match, never a `City` correction. - `district` string: Neighborhood / sub-locality where the country convention carries one (e.g. the Turkish mahalle, Austrian Bezirk sublocality). Enriched from the reference row even when the caller omitted it. - `province` string: Italy only. Two-letter province sigla (MI, RM, …) for the mandatory Poste Italiane locality line (`20067 PAULLO MI`). - `dependent_street` string: UK only (Royal Mail PAF dependent thoroughfare). The minor road the house number is addressed on (`18 Latium Close, Holywell Hill`); the parent thoroughfare stays in `street`. - `dependent_locality` string: UK (Royal Mail PAF): village / dependent locality printed between the thoroughfare and the post town. Malaysia: the Taman / Kampung sub-locality line, printed above the postcode line. - `double_dependent_locality` string: UK only (PAF). Sub-locality below `dependent_locality`. - `administrative_county` string: UK only. PAF Administrative County (local authority). Present when extended UK fields are enabled; on some postcodes it is the only county held (`county` blank). - `welsh` object: UK only, Wales. The Welsh-language form of the SAME delivery point (Royal Mail ships Welsh addresses bilingually): `street`, `city` (post town, e.g. CAERDYDD for CARDIFF) and, where they exist, translated `dependent_locality` / `double_dependent_locality` / `dependent_street`. Present on an English-form match when a Welsh counterpart exists. Typing the Welsh form is a verified match, never a `Street`/`City` correction. - `english` object: UK only, Wales. Mirror of `welsh`: the English-language form, present when the matched row is the Welsh one. At most one of `welsh`/`english` appears. - `score` number, float, required - `lat` number, float - `lng` number, float - `alternative_matches` AlternativeMatch[]: Reserved — not currently emitted (disabled pending an index). Planned behaviour: same street + house number in a different state, USA / CAN `verified` matches, up to 5 items. - `standardized` StandardizedAddress, required: Canonical address as stored in the reference database. - `street` string - `house_number` string - `city` string: Spain (`/suggest`): for the officially bilingual municipalities the suggestion prints the Castilian name by default (`Alicante`, `Elche`, `San Sebastián`, `Castellón de la Plana`, `Valencia`); if your query already spells the regional form (`Alacant`, `Elx`, `Donostia`, `València`) that spelling is kept. Postcode and coordinates are the same either way, and submitting the suggestion to `/validate` matches the same address. `/validate` itself echoes the spelling you sent. Sweden, city + postcode without a street (`/validate`, `/geocode`): the stored spelling of the locality (`Goteborg`, `göteborg` -> `GÖTEBORG`), as on full matches; an English or variant name (`Gothenburg`) is returned in the stored spelling too, and `/validate` lists `City` under `corrections`. - `state` string: Present for countries with regions (e.g. USA, CAN, AUS, MYS). - `postcode` string - `postcode_formatted` string: The postcode as it is written on a letter, in a field of its own, for integrations that look the postcode up elsewhere. Sweden: `412 50` (`postcode` stays `41250`). Where no written form differs, it equals `postcode`. `postcode` itself is unchanged. Returned by `/validate`. - `country` string - `formatted_address` string: Country-specific pretty-printed form, multi-line. - `street_type` string: The thoroughfare type as its own element, where the reference data carries it separately: Malaysia (`street_type: "Jalan"`, `street: "Melor 1"`), and Canada / France where the split comes straight from the reference columns (France is type-first — `street_type: "Place"`, `street_name: "de la Comédie"`). NOT emitted for the USA, which would need a USPS-suffix parse, nor for German, Dutch, Danish, Swedish or Swiss addresses, where the type is fused into the word (*Eckenbertstraße*) and splitting it is a morphological judgement rather than a field read. - `street_name` string: Canada and France: the bare street name with the type and any directional removed. Companion to `street_type` / `street_suffix`; `street` always holds the full form. - `street_suffix` string: Canada: the directional element (N, SW, …) as its own field. - `street_id` string: France: the reference data's stable identifier for the thoroughfare. - `building_name` string: Hong Kong: the building name from the matched premise. Emitted only when every co-matched row agrees on it — a query resolving to many rows (a tower with hundreds of flats) omits it rather than picking one arbitrarily. Singapore: the building name of the matched block, when it has one (house-number-level matches, and addresses identified by a building or tenant name). It is not part of `formatted_address`. - `level_number` string: Denmark (`etage`) and Hong Kong (floor). Same unambiguity rule as `building_name`, and additionally requires a confirmed house number. - `unit_identifier` string: Denmark (`dør`), the Netherlands (sub-address) and Hong Kong (flat). Same unambiguity rule as `level_number`. - `ine_municipality` string: Spain: the 5-digit INE municipality code of the matched address (leading zeros preserved — always a string). - `nis_code` string: Belgium: the NIS municipality code of the matched address. - `statistical_sector` string: Belgium: the 9-character Statbel statistical sector of the matched address (the trailing hyphen is part of the code, e.g. `"41002A00-"`). This is the key the Belgian enrichment joins on. - `county` string: UK only (`country: "gbr"`). Traditional/postal county, derived from the Royal Mail PAF postcode → county map. - `udprn` string: UK only. Royal Mail Unique Delivery Point Reference Number (PAF) — stable identifier for the delivery point. - `uprn` string: UK only. Ordnance Survey Unique Property Reference Number. Present when the address matches OS Open UPRN. - `unit` string: Sub-building unit, echoed from the caller's input (reference rows carry no unit, so this value is never invented). Rendered into `formatted_address` per country convention (e.g. Canada Post `23-4 Vata Crt`). When the reference data cannot confirm the unit at the matched premise, the response lists `"unit"` in the top-level `unverified_fields` array — the premise match itself still stands. Spain: staircase / floor / door in any common spelling (`ESC.1-PISO 1, PTA.B`, `1º B`, `3º izq`, `bajo`) are normalised to one form, e.g. `Esc. 1, 1º B`; see `unit_verified` / `unit_check`. Latvia: the flat (dzīvoklis) in any common spelling (`Brīvības iela 100 - 5`, `100-5`, `100 dz. 5`, `100 kv. 5`) is returned as the flat number, e.g. `5`, and rendered as `Brīvības iela 100 - 5`; a korpuss (`10k2`, `10 k. 2`) is part of the house number (`10 k-2`), never a unit. - `suburb` string: New Zealand. The NZ Post suburb line between street and post town (`68 Rintoul Street / Newtown / Wellington 6021`). Filled from the matched reference row — including when the caller typed only the city. A suburb typed in the city slot is a verified match, never a `City` correction. - `district` string: Neighborhood / sub-locality where the country convention carries one (e.g. the Turkish mahalle, Austrian Bezirk sublocality). Enriched from the reference row even when the caller omitted it. - `province` string: Italy only. Two-letter province sigla (MI, RM, …) for the mandatory Poste Italiane locality line (`20067 PAULLO MI`). - `dependent_street` string: UK only (Royal Mail PAF dependent thoroughfare). The minor road the house number is addressed on (`18 Latium Close, Holywell Hill`); the parent thoroughfare stays in `street`. - `dependent_locality` string: UK (Royal Mail PAF): village / dependent locality printed between the thoroughfare and the post town. Malaysia: the Taman / Kampung sub-locality line, printed above the postcode line. - `double_dependent_locality` string: UK only (PAF). Sub-locality below `dependent_locality`. - `administrative_county` string: UK only. PAF Administrative County (local authority). Present when extended UK fields are enabled; on some postcodes it is the only county held (`county` blank). - `welsh` object: UK only, Wales. The Welsh-language form of the SAME delivery point (Royal Mail ships Welsh addresses bilingually): `street`, `city` (post town, e.g. CAERDYDD for CARDIFF) and, where they exist, translated `dependent_locality` / `double_dependent_locality` / `dependent_street`. Present on an English-form match when a Welsh counterpart exists. Typing the Welsh form is a verified match, never a `Street`/`City` correction. - `english` object: UK only, Wales. Mirror of `welsh`: the English-language form, present when the matched row is the Welsh one. At most one of `welsh`/`english` appears. - `score` number, float, required: Always 1.0 — these are exact DB matches in a different state. - `lat` number, float - `lng` number, float - `lat` number, float - `lng` number, float - `arrival_point` object: Entrance / access coordinate (arrival point) of the matched premise, returned beside the served coordinate on house-number-level matches when the reference row carries one. With `accuracy_type: rooftop` this is the door/curb point of the same address (useful for delivery and navigation); with `accuracy_type: arrival_point` it simply equals `lat`/`lng`. Omitted when the match is not premise-level or no arrival point is on file — never null. - `lat` number, float - `lng` number, float - `landmark_used` object: Present ONLY with `accuracy_type: landmark_proximity` (India). The address itself resolved no further than its postcode/locality, so the served coordinate was taken from a landmark named in the input. This block says which one, so the substitution is never silent: `name` is the stored name of the place we used, `matched_from` is the caller's own words that matched it, `scope` is the evidence that identified it uniquely (`pin_exact`, `pin_contains`, `locality_exact`, `locality_contains`), and `source` is the data attribution. Omitted on every other tier — never null. - `name` string, required - `matched_from` string, required: The landmark text as the caller wrote it. - `scope` string, required - `source` string, required - `house_number_not_found` boolean: 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. - `postcode_corrected` boolean - `deliverable` boolean: `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. - `hno_range_verified` boolean: 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. - `parsed` object: Always returned. For single-line `input`: the parser's field breakdown (informational echo; lowercase). For fielded input: an echo of the supplied fields. Keys include `street`, `house_number`, `city`, `postcode`, `state`, `sublocality`, `unit`, `floor`, `po_box`, `country`. Useful for debugging why a free-form string matched the way it did. Informational only, not a stable contract: formats can change between releases (for Spain, `floor` carries a normalised code such as `1`, `BJ` for ground floor or `-1` for a basement). Use `standardized` for anything you store or display. - `match_details` object: Per-component flags from the DB lookup — keys `street`, `house_number`, `city`, `postcode` (not `zip`), `state` (when applicable), plus a duplicated `postcode_corrected` boolean. Unlike `match_components` — which scores only what the caller provided — `match_details` reports what the matched row confirmed, so the two may legitimately differ. Absent on SEG centroid-fallback responses (still present on street-tier partials). - `unverified_fields` string[]: Components echoed from the caller's input that reference data could NOT confirm (e.g. `["unit"]` — reference rows carry no unit data). The match itself still stands; treat the listed components as unverified input, not reference data. - `unit_verified` boolean: 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`. - `former_address` object: Latvia only. The address you sent is a FORMER address of the matched building in the State Address Register: the street was renamed, the building was renumbered, or a named property got a street address (or the reverse). `standardized` holds the current address. The change is disclosed in `corrections` (`Street`, `House number`) and `status` is `corrected`. Absent when the address you sent is current, and in every other country. - `street` string: The former street, or the former property name. - `house_number` string: The former house number (empty for a former property name). - `city` string: City or village at the time (may be empty). - `parish` string: Parish (pagasts) at the time (may be empty). - `postcode` string: Postcode at the time (empty for records older than 2003). - `valid_until` string, date, nullable: Last day the former address was in force, when recorded. - `change` 'renumbered' | 'street_renamed' | 'renamed_and_renumbered' | 'street_to_property' | 'property_renamed' | 'property_to_street': What changed between the former and the current address. - `tenant_name_matched` string: 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. - `building_name_matched` string: 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. - `unit_check` 'verified' | 'not_in_list' | 'no_data': 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. - `postcode_unverified` boolean: The postcode was echoed from the caller, never read from a reference row. - `locality_from_postcode` boolean: The city was derived from the postcode rather than typed by the caller. - `city_backfilled_from_postcode` boolean: 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. - `street_backfilled_from_postcode` boolean: 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. - `matched_via_alias` boolean: 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. - `usps_city` string: USA: the USPS-preferred city name when it differs from the input. - `locality_note` string: Human-readable note on how the locality was matched (alias / municipality disclosure). - `city_mismatch_ignored` boolean: The typed city disagreed with the matched row but was overridden by stronger evidence (street + postcode); disclosed rather than silently dropped. - `postcode_supplied` string: 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_suggested` string: Postcode-repair forensics — the reference postcode for the matched premise, when it differs from `postcode_supplied`. - `postcode_incoherent` boolean: `true` when the supplied postcode does not fit the matched street/locality at all (rather than being a near-miss). - `postcode_status` string: 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. - `accuracy_label` string: Human-readable form of the served tier (e.g. `"postcode centroid"`). Display-only; branch on `accuracy_type` / `point_coordinate`. - `non_deliverable_type` string: Classification of non-deliverable input (e.g. `po_box`). Appears on the 400 rejection body, or on the 200 body under `iso20022: true`. - `uprn_match_m` number: 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). - `credits_remaining` integer: After keyed validation. - `validation_credits_remaining` integer - `geocode_credits_remaining` integer - `key_accepted` boolean ## Other responses - `400`: Missing country, unsupported country, or bad payload. A missing `street`/`city` only surfaces as 400 when the SEG cascade also has no centroid to offer — when SEG can supply one, a 200 with `partial_match: true` is returned instead. Netherlands: `postcode` + `house_number` with no street and no city is never a 400 (see the Netherlands postcode + house number note in the `/validate` description). Portugal: a street without a city is a 404 (see below), not a 400; a city-only request returns a labelled approximate 200 (`approximate: true`) when the place is found. Also returned for `country: gbr` requests sent to this host — the UK is served from `https://paf.acuris-geo.com` (body: `country_not_served_by_this_endpoint` with `use_instead`). Also returned for **non-deliverable input** (PO Box, Postfach, Rural Route, …): the body then carries the full match-quality contract with `match_type: "non_deliverable"`, `non_deliverable_type` (e.g. `po_box`) and `reasons: ["non_deliverable_address"]` — see `MatchType`. With `iso20022: true` the same input is instead accepted as a labelled 200 (`non_deliverable_type` on the success body). - `401`: Invalid or inactive API key - `402`: Payment required (Stripe-plan keys): `subscription_canceled`, `pack_expired` (body includes `expired_at`), or `credits_wrong_region` (body includes `country`, `have_regions`, `needed`). - `403`: Insufficient transaction balance. Body shapes: `{"error": "quota_exceeded", "pool", "limit", "used", "message"}` for exhausted plan quota; trial keys return `{"error": "insufficient_credits" | "trial_expired", "key_accepted": true, "credits_remaining", "validation_credits_remaining", "geocode_credits_remaining"}`. Key-level 403s: `{"error": "key_blocked", "message"}` when the API key has been blocked (the `message` says why), and `{"error": "ip_not_allowed", "message", "ip"}` when the key is restricted to approved source IP addresses and this request came from another one (`ip` is the address we saw). Source-IP restriction is optional and set up per key on request via support. - `404`: Address not found **and** SEG cascade had no centroid to offer. Body includes `match_type: no_match`, `suggestions` (if any near-misses scored ≥ 0.5), and `reasons`. When SEG _does_ have a centroid, the response is 200 with `partial_match: true` instead of 404. Portugal (`country: prt`): `reasons` names the cause (e.g. `city_not_found`, `street_not_found`, `street_found_in_multiple_localities` + `city_missing`, `locality_ambiguous` + `street_missing`), and `did_you_mean` lists what the input most likely meant (never applied automatically) — alongside the unchanged `suggestions`. A street sent without a city returns this 404 (with the candidate towns in `did_you_mean`) rather than a 400, unless exactly one town holds the street, in which case that town is used and disclosed as a `City` correction. - `422`: Input could not be parsed (e.g. `input` was neither a string nor an object). - `429`: Too many requests (anonymous limit or WAF/limiter) - `504`: Validation timed out --- [API](https://skmtc.dev/acuris-geo/apis/acuris-geo-api.md) · [All operations](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/revisions/8547b31dd96a?raw)