---
title: "Validate up to 200 addresses in one request (versioned alias)"
method: POST
path: "/v1/validate/batch"
tags: ["Versioned aliases (v1)"]
---

# Validate up to 200 addresses in one request (versioned alias)

`POST /v1/validate/batch`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/v1/validate/batch`
- 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

Synchronous bulk validation. Each row is billed and matched exactly as a
standalone `POST /validate` call would be (`validate=1` transaction each). An
**API key is required** — the free-tier per-IP allowance is for single
`POST /validate` only.

Every row shares the top-level `country` unless the row is an object of the
form `{"input": <input>, "country": "usa"}`, which overrides the country for
that row (letting you mix countries in one batch). For volumes above 200,
submit an async job via `POST /validate/jobs` (up to 50,000 addresses).

## Request body

- ValidateBatchRequest: Bulk validation payload. An **API key** (header or credentials) is required.
  - `addresses` union[], required: Up to 200 rows. Each row is either the same `input` shape accepted by `POST /validate` (a single-line string or an object of address fields), **or** an object `{"input": <input>, "country": "usa"}` that overrides `country` for that one row.
    - union
      - string
      - object
  - `country` string: Default ISO-3 country for every row that does not carry its own `country` override.

## Response `200`

Per-row results, in request order. Each element is the same body a
standalone `POST /validate` would return (including per-row `error`
objects for rows that failed).

- ValidateBatchResponse
  - `count` integer: Number of rows processed (after empty rows are dropped).
  - `results` ValidateResponse[]: Per-row results in request order; each element is the same body a standalone `POST /validate` returns.
    - `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`: `addresses` is not an array, is empty, or exceeds 200 entries (`batch_too_large`).
- `401`: API key required (`api_key_required`) — batch has no anonymous free tier.
- `429`: Too many requests (anonymous limit or WAF/limiter)

---

[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)