{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/acuris-geo-com/json-schema/acuris-geo-com-validate-response-schema.json", "title": "ValidateResponse", "description": "Successful validation **or** centroid-fallback. The canonical form\n**always lives in `standardized`**. When value-changing corrections were\napplied, the response carries `status: \"corrected\"` with a\nhuman-readable `corrections` list, and `standardized` holds the\ncorrected canonical form. When neither was attainable but SEG produced a\ncentroid, the response carries `partial_match: true` with `lat`/`lng`\nset; `standardized` then echoes the caller's input for every component\nthat could not be verified — only the components confirmed in\n`match_components` are reference data. All responses carry the\nmatch-quality contract (`match_type`, `match_score`, `match_components`,\n`input_corrected`).\n", "x-generated": "2026-10-30", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/acuris-geo-com-openapi.json#/components/schemas/ValidateResponse", "type": "object", "additionalProperties": true, "required": [ "match_type", "match_score", "match_components", "input_corrected", "accuracy_type" ], "properties": { "standardized": { "$ref": "#/$defs/StandardizedAddress" }, "corrected": { "deprecated": true, "description": "Reserved legacy key — not emitted. The corrected canonical form is returned in `standardized` (with `status: \"corrected\"` and the `corrections` list); read that instead.", "allOf": [ { "$ref": "#/$defs/StandardizedAddress" } ] }, "status": { "type": "string", "enum": [ "verified", "corrected" ], "description": "`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": { "type": "number", "format": "float", "description": "How strongly the match AND the returned coordinate are evidenced, 0–1. It is not the validity verdict: whether the address is valid is given by `status` (verified / corrected), `deliverable` and `confidence_level`. The number starts at 1.0 for a verified match (the similarity score, 0.85–1.0, for a corrected one) and is then capped by the precision of the coordinate: every `accuracy_type` has a ceiling — e.g. `rooftop` / `arrival_point` 1.0, `street_interpolated` 0.9, `street_centroid` 0.75, `postcode_centroid` 0.6, `locality_centroid` 0.5, `admin_centroid` 0.4, Canadian `po_box` 0.9 and `po_box_postcode_area` 0.5 — so a verified address with a coarse pin carries a lower number. Exception: when a house number you supplied was confirmed on a premise row, the coordinate ceiling is not applied (the address itself is proved; `accuracy_type` still states the pin). The number is also 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 those cases." }, "confidence_level": { "type": "string", "enum": [ "high", "medium", "low", "none" ], "description": "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. The grade of a confirmed address does not depend on the coordinate: an address the register holds without a coordinate (derived pin, `point_coordinate: false`) is still `high`." }, "corrections": { "type": "array", "description": "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`).", "items": { "type": "string" } }, "accuracy_type": { "$ref": "#/$defs/AccuracyType" }, "point_coordinate": { "type": "boolean", "description": "`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": { "$ref": "#/$defs/MatchType" }, "match_score": { "type": "number", "format": "float", "minimum": 0, "maximum": 1 }, "match_components": { "$ref": "#/$defs/MatchComponents" }, "input_corrected": { "type": "boolean" }, "reasons": { "type": "array", "items": { "$ref": "#/$defs/FailureReason" }, "description": "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." }, "truncated": { "type": "boolean", "description": "Present (always `true`) when the search was cut short by its time limit; `reasons` then includes `search_budget_exhausted`. United States only on 200 answers: the answer is the best one found in time, and a finer pin may exist. Absent otherwise." }, "provided_components": { "$ref": "#/$defs/MatchComponents", "description": "**Always returned.** Echoes which components the caller actually supplied (non-empty after parsing), keyed identically to `match_components` (`house_number`, `street`, `city`, `zip`, `state`). Pair it with `match_components` field-by-field to tell \"not provided\" apart from \"provided but not matched\"." }, "partial_match": { "type": "boolean", "description": "`true` when the address could not be fully verified but a coordinate was still\nproduced — at street level (`reasons` `house_number_unconfirmed` /\n`house_number_not_found`; pin `street_interpolated` / `street_centroid`) or via\nthe SEG cascade (postcode / locality / admin\ncentroid). Absent or `false` on full verified/corrected matches. The response\nstill carries `standardized`, but it echoes the caller's input for every\ncomponent that could not be verified (only the components confirmed in\n`match_components` are reference data) — treat `lat`/`lng` as the only\ntrustworthy output, and check `reasons` for what could not be pinned down.\n" }, "nearby_house_numbers": { "allOf": [ { "$ref": "#/$defs/NearbyHouseNumbers" } ], "description": "Portugal only, optional. The street was matched but the house number you sent is not in the reference data (`street_centroid`, or `street_interpolated` between the nearest same-parity numbers with `confidence` 0.8 and `deliverable: false`); names the nearest numbers that are held. Sent with reason `house_number_not_in_reference`." }, "street_postcodes": { "type": "array", "description": "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.", "items": { "type": "object", "properties": { "postcode": { "type": "string" }, "house_number_from": { "type": "integer" }, "house_number_to": { "type": "integer" }, "parity": { "type": "string", "enum": [ "odd", "even", "both" ], "description": "Which side(s) of the street the postcode covers within that range." } } } }, "street_postcodes_total": { "type": "integer", "description": "With `street_postcodes`, how many postcodes the street covers (not capped)." }, "street_postcodes_truncated": { "type": "boolean", "description": "With `street_postcodes`, `true` when the street covers more postcodes than are listed." }, "postcode_range": { "type": "object", "description": "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.", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "text": { "type": "string" } } }, "approximate": { "type": "boolean", "description": "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": { "allOf": [ { "$ref": "#/$defs/ResolvedLevel" } ], "description": "Portugal only, with `approximate: true`: which kind of place the point stands for (`locality`, `postal_town`, `municipality`, `district`, `lisbon_parish`)." }, "resolved_name": { "type": "string", "description": "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": { "type": "object", "description": "Free geographic enrichment, attached automatically (no extra\ncharge, no request parameter) for eighteen countries — USA,\nCanada, Germany, Austria, Switzerland, France, United Kingdom,\nBelgium, Spain, Portugal, Ireland, Netherlands, Finland, Sweden,\nLuxembourg, Japan, Singapore and Hong Kong — whenever the result\nis precise\nenough for a small-area lookup to be trustworthy (gates below).\nOmitted otherwise — never null, never an empty object. Fields whose\ngeography does not apply to the point are likewise omitted, never\nnull. Sub-fields are country-specific; every layer is public\ngovernment data.\n\n**When it appears**\n\n- USA, Canada, Germany, Austria, Switzerland and the France admin\n fields need a street-accurate coordinate (`rooftop`,\n `arrival_point`, `street_interpolated` or `street_centroid` —\n never a postcode/locality/admin centroid, where the point could\n fall in the wrong small area).\n- The France `building` block and the whole UK block need a\n premise-level match (`rooftop` / `arrival_point`). The UK block\n is keyed on the matched address's `uprn` (ONS National Statistics\n UPRN Lookup). Great Britain only — Northern Ireland (BT\n postcodes) carries no block because NI statistical geography is\n separately licensed.\n- Finland and the Netherlands are keyed on the validated postcode;\n the block describes the whole postal area (see its `scope`\n field), not the individual household.\n- Japan derives the 500 m JIS X 0410 mesh cell from the\n coordinate.\n- Singapore joins on the standardized block number + street; HDB\n blocks only, so a miss on private housing is normal.\n- Belgium is keyed on the matched row's 9-character Statbel\n statistical sector (also emitted as `statistical_sector`); a\n Belgian postcode spans several sectors, so a postcode-grain join\n would attribute one sector's figures to all of them.\n- Spain resolves the 10-digit census section (CUSEC) from the INE\n Callejero — municipality + street + house-number range + parity —\n and falls back to municipality level when no range covers the\n number. The block's `scope` says which tier answered\n (`census_section` or `municipality`); the parity filter is\n load-bearing and refuses rather than assigning the wrong side of\n the street.\n- Portugal, Ireland, Sweden, Luxembourg and Hong Kong are\n point-in-polygon on the returned coordinate, each returning a\n `statistical_area` block whose `code` is that country's finest\n published unit: Portugal BGRI subsecção (11 chars, block-level),\n Ireland CSO Small Area (2022), Sweden DeSO, Luxembourg commune\n (LAU2), Hong Kong Small Subunit Group.\n- Three Irish Small Areas genuinely overlap (slivers of 38–433 m²\n from 20 m generalisation). A point inside one is reported as\n ambiguous rather than silently resolved — picking the smallest\n area would cross an electoral-district boundary in Carlow.\n\nEnrichment can accompany `partial_match: true` when the inferred\ncoordinate still reaches a qualifying tier (e.g.\n`street_centroid`); postcode-, locality- and admin-centroid\nfallbacks never carry it.\n\nStatistical layers respect the publisher's disclosure control:\nwithheld values are absent from the block — an absent value is not\na zero (Swiss hectare grid, Dutch PC6, Japanese age bands) — and\nGerman Zensus grid counts are Cell-Key perturbed. Each such block\nsays so in its `note`.\n", "additionalProperties": true, "properties": { "state_fips": { "type": "string", "description": "USA: 2-digit state FIPS." }, "county_fips": { "type": "string", "description": "USA: 5-digit county FIPS (state+county)." }, "census_tract": { "type": "string", "description": "USA: 11-digit census tract GEOID. Canada: CTUID (urban areas only)." }, "block_group": { "type": "string", "description": "USA: 12-digit block-group GEOID." }, "cbsa": { "type": "object", "description": "USA: Core-Based Statistical Area (metro/micro). Omitted (not null) outside any CBSA.", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "metro", "micro" ] } } }, "congressional_district": { "type": "object", "description": "USA: 119th-Congress district (`00` at-large; `98`/`99` non-voting).", "properties": { "state_fips": { "type": "string" }, "district": { "type": "string" }, "congress": { "type": "integer" } } }, "school_district": { "type": "object", "description": "USA: school district.", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "unified", "elementary", "secondary" ] } } }, "dissemination_area": { "type": "string", "description": "Canada: 8-digit Dissemination Area UID (province + census division + DA)." }, "province_code": { "type": "string", "description": "Canada: 2-digit province/territory (SGC)." }, "census_division": { "type": "string", "description": "Canada: 4-digit census division UID." }, "census_subdivision": { "type": "object", "description": "Canada: census subdivision (municipality).", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "cma_ca": { "type": "object", "description": "Canada: Census Metropolitan Area / Census Agglomeration. Omitted outside both.", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "metro", "agglomeration" ] } } }, "federal_electoral_district": { "type": "object", "description": "Canada: federal electoral district.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "ags": { "type": "string", "description": "Germany: 8-digit Amtlicher Gemeindeschlüssel." }, "ars": { "type": "string", "description": "Germany: 12-digit Amtlicher Regionalschlüssel." }, "gemeinde": { "type": "string", "description": "Germany / Austria / Switzerland: municipality name." }, "gemeinde_type": { "type": "string", "description": "Germany: municipality kind (Stadt, Gemeinde, Kreisfreie Stadt, …)." }, "bundesland": { "type": "object", "description": "Germany / Austria: federal state.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "kreis": { "type": "object", "description": "Germany: district.", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "nuts3": { "type": "string", "description": "Germany: NUTS-3 code (e.g. DEA12)." }, "bundestagswahlkreis": { "type": "object", "description": "Germany: Bundestag electoral constituency.", "properties": { "number": { "type": "integer" }, "name": { "type": "string" } } }, "gkz": { "type": "string", "description": "Austria: 5-digit Gemeindekennziffer." }, "politischer_bezirk": { "type": "object", "description": "Austria: political district.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "regionalwahlkreis": { "type": "object", "description": "Austria: regional electoral constituency.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "zaehlsprengel": { "type": "string", "description": "Austria: census enumeration district (smallest census unit)." }, "bfs_nummer": { "type": "string", "description": "Switzerland: BFS municipality number." }, "kanton": { "type": "object", "description": "Switzerland: canton — also the Nationalrat electoral constituency.", "properties": { "number": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" } } }, "bezirk": { "type": "object", "description": "Switzerland: district.", "properties": { "number": { "type": "integer" }, "name": { "type": "string" } } }, "grossregion": { "type": "object", "description": "Switzerland: major region = Swiss NUTS-2 unit.", "properties": { "number": { "type": "integer" }, "nuts2": { "type": "string" }, "name": { "type": "string" } } }, "sprachgebiet": { "type": "object", "description": "Switzerland: official language region — which language to address this customer in.", "properties": { "language": { "type": "string", "description": "ISO 639-1: de/fr/it/rm" }, "name": { "type": "string" } } }, "degree_of_urbanisation": { "type": "object", "description": "Switzerland: Eurostat DEGURBA class.", "properties": { "code": { "type": "string", "enum": [ "city", "town_suburb", "rural" ] }, "name": { "type": "string" } } }, "stadt_land": { "type": "string", "enum": [ "urban", "intermediate", "rural" ], "description": "Switzerland: BFS Stadt/Land typology." }, "gemeindetyp": { "type": "object", "description": "Switzerland: BFS municipality typology (9 classes); `class` is the 3-fold split.", "properties": { "code": { "type": "string" }, "class": { "type": "string", "enum": [ "urban", "periurban", "rural" ] } } }, "agglomeration": { "type": "object", "description": "Switzerland: agglomeration.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "arbeitsmarktregion": { "type": "object", "description": "Switzerland: labour-market region.", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "macro_region": { "type": "string" } } }, "insee": { "type": "string", "description": "France: INSEE commune code." }, "commune": { "type": "string", "description": "France: commune name." }, "departement": { "type": "object", "description": "France: département.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "region": { "type": "object", "description": "France: région. UK: ONS region.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "iris": { "type": "object", "description": "France: INSEE IRIS statistical district (metropolitan France).", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "residential", "economic_activity", "miscellaneous", "whole_commune" ] } } }, "building": { "type": "object", "description": "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.", "properties": { "coord_verified": { "type": "boolean" }, "match_type": { "type": "string", "enum": [ "inside", "nearest" ] }, "distance_m": { "type": "number" }, "building_type": { "type": "string", "description": "e.g. Unspecified, Church, Castle, …" }, "usage": { "type": "string", "description": "Residential, Commercial and services, Industrial, …" }, "usage_secondary": { "type": "string" }, "height_m": { "type": "number" }, "floors": { "type": "integer" }, "dwellings": { "type": "integer" }, "is_multi_dwelling": { "type": "boolean" }, "rnb_id": { "type": "string", "description": "French national building registry (RNB) id." }, "sub_unit_expected": { "type": "boolean" }, "source": { "type": "string" } } }, "output_area": { "type": "string", "description": "UK: 2021 Output Area code — finest ONS tier; output areas have no name." }, "lsoa": { "type": "object", "description": "UK: Lower layer Super Output Area.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "msoa": { "type": "object", "description": "UK: Middle layer Super Output Area.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "local_authority": { "type": "object", "description": "UK: local authority district.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "ward": { "type": "object", "description": "UK: electoral ward.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "westminster_constituency": { "type": "object", "description": "UK: Westminster parliamentary constituency.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "country": { "type": "object", "description": "UK: constituent country (England, Scotland, Wales).", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "police_force_area": { "type": "object", "description": "UK: police force area.", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "rural_urban": { "type": "object", "description": "UK: rural/urban classification.", "properties": { "code": { "type": "string" }, "description": { "type": "string" } } }, "demographics": { "type": "object", "description": "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`.", "additionalProperties": true }, "economy": { "type": "object", "description": "Switzerland: BFS STATENT hectare-grid workplace stats — hectare_cell, workplaces, employees_fte, note, source.", "additionalProperties": true }, "postal_area": { "type": "object", "description": "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.", "additionalProperties": true }, "postcode_area": { "type": "object", "description": "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.", "additionalProperties": true }, "mesh_area": { "type": "object", "description": "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.", "additionalProperties": true }, "hdb_block": { "type": "object", "description": "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.", "additionalProperties": true }, "statistical_sector_area": { "type": "object", "description": "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.", "additionalProperties": true }, "census_section_area": { "type": "object", "description": "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.", "additionalProperties": true }, "statistical_area": { "type": "object", "description": "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.", "additionalProperties": true }, "source": { "type": "string", "description": "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": { "type": "string", "enum": [ "exact", "fuzzy" ], "description": "Retained for backward compatibility. New clients should use `match_type`." }, "match_score_legacy": { "type": "string", "description": "Retained for backward compatibility. Human-readable label (e.g. `\"Perfect match\"`, `\"Partial match (street only)\"`)." }, "suggestions": { "type": "array", "description": "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.", "items": { "$ref": "#/$defs/Suggestion" } }, "alternative_matches": { "type": "array", "description": "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.", "items": { "$ref": "#/$defs/AlternativeMatch" } }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" }, "arrival_point": { "type": "object", "description": "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.", "properties": { "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" } } }, "landmark_used": { "type": "object", "description": "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.", "required": [ "name", "matched_from", "scope", "source" ], "properties": { "name": { "type": "string" }, "matched_from": { "type": "string", "description": "The landmark text as the caller wrote it." }, "scope": { "type": "string", "x-extensible-enum": [ "pin_exact", "pin_contains", "locality_exact", "locality_contains" ] }, "source": { "type": "string" } } }, "house_number_not_found": { "type": "boolean", "description": "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": { "type": "boolean" }, "deliverable": { "type": "boolean", "description": "`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. Netherlands: an address the BAG register holds without a postcode (garage box, storage cellar) is `false` even when verified; see `address_class`." }, "hno_range_verified": { "type": "boolean", "description": "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. Not set for a house number the register holds as its own premise row without a coordinate: that is premise-level verification, and `accuracy_type` / `point_coordinate` state the derived pin." }, "parsed": { "type": "object", "description": "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`. A Canadian PO Box answer (`address_type: po_box`) also echoes `po_box_station`: the station as read from the input, e.g. `STN A` or `SUCC Terminus` (which may differ from the verified `po_box.station`). 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.", "additionalProperties": true }, "match_details": { "type": "object", "description": "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).", "additionalProperties": true }, "unverified_fields": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "boolean", "description": "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": { "type": "object", "description": "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.", "properties": { "street": { "type": "string", "description": "The former street, or the former property name." }, "house_number": { "type": "string", "description": "The former house number (empty for a former property name)." }, "city": { "type": "string", "description": "City or village at the time (may be empty)." }, "parish": { "type": "string", "description": "Parish (pagasts) at the time (may be empty)." }, "postcode": { "type": "string", "description": "Postcode at the time (empty for records older than 2003)." }, "valid_until": { "type": [ "string", "null" ], "format": "date", "description": "Last day the former address was in force, when recorded." }, "change": { "type": "string", "enum": [ "renumbered", "street_renamed", "renamed_and_renumbered", "street_to_property", "property_renamed", "property_to_street" ], "description": "What changed between the former and the current address." } } }, "tenant_name_matched": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "enum": [ "verified", "not_in_list", "no_data" ], "description": "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": { "type": "boolean", "description": "The postcode was echoed from the caller, never read from a reference row." }, "locality_from_postcode": { "type": "boolean", "description": "The city was derived from the postcode rather than typed by the caller." }, "city_backfilled_from_postcode": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "boolean", "description": "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": { "type": "string", "description": "USA: the USPS-preferred city name when it differs from the input." }, "locality_note": { "type": "string", "description": "Human-readable note on how the locality was matched (alias / municipality disclosure)." }, "city_mismatch_ignored": { "type": "boolean", "description": "The typed city disagreed with the matched row but was overridden by stronger evidence (street + postcode); disclosed rather than silently dropped." }, "postcode_supplied": { "type": "string", "description": "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": { "type": "string", "description": "Postcode-repair forensics — the reference postcode for the matched premise, when it differs from `postcode_supplied`." }, "postcode_incoherent": { "type": "boolean", "description": "`true` when the supplied postcode does not fit the matched street/locality at all (rather than being a near-miss)." }, "postcode_status": { "type": "string", "x-extensible-enum": [ "stocked", "unknown", "valid_not_stocked" ], "description": "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": { "type": "string", "description": "Human-readable form of the served tier (e.g. `\"postcode centroid\"`). Display-only; branch on `accuracy_type` / `point_coordinate`." }, "non_deliverable_type": { "type": "string", "description": "Classification of non-deliverable input (e.g. `po_box`). Appears on the 400 rejection body, or on the 200 body under `iso20022: true`. Never set on a verified Canadian PO Box (see `address_type`)." }, "address_type": { "type": "string", "x-extensible-enum": [ "po_box" ], "description": "Present when the answer is not a street address. Today only `po_box`, in Canada and Singapore. Canada: the input is a PO Box, matched against the reference lock-box ranges of Canada Post installations. Singapore: the input is a PO Box confirmed in the box register (box number, post office, 6-digit box postcode). It says WHAT the address is, not whether it is verified: a verified box has `status` verified / corrected and `deliverable: true` (it takes mail; it has no door for a courier); a partial one has `partial_match: true`, `deliverable: false` and one of the reasons `po_box_not_in_range`, `po_box_ambiguous`, `po_box_postcode_town_mismatch` (Canada) or `po_box_number_missing` (Singapore). A Singapore box line that is not in the register answers 404 with reason `po_box_not_found` and `address_type: po_box`." }, "address_class": { "type": "string", "x-extensible-enum": [ "nonpostal" ], "description": "Present when the matched address is real but not a postal delivery point. Today only `nonpostal` (Netherlands): the official BAG register holds the address exactly as you sent it (e.g. a wharf cellar \"Oudegracht aan de Werf 1001T, Utrecht\") but without a postcode, so PostNL does not deliver to it. `status` stays `verified` (nothing you sent was wrong, no correction), `deliverable` is `false` and `standardized.postcode` is empty unless you sent one: a postcode you sent is echoed but not confirmed (`unverified_fields` lists `postcode`, `match_components.zip` is `false`). `/suggest` does not offer these addresses unless the typed text carries their letter or addition (\"Weideweg 44 G\", \"Oudegracht aan de Werf 1001T\"). See `address_note`. Not the same as `address_type`: `address_type` describes the FORM of the address (e.g. `po_box`, not a street address), while `address_class` describes its POSTAL CLASS; the two can appear together." }, "address_note": { "type": "string", "description": "Plain-language explanation that accompanies `address_class`, e.g. \"This address exists in the official BAG register but has no postcode; it is not a postal delivery point.\"" }, "po_box": { "type": "object", "description": "Canada, with `address_type: po_box`. The box: `number`, `station_type` (`STN`, `SUCC`, `RPO`, `PO`, ...), `station_name` (e.g. `A`, `CENTRAL`, `MAIN`), `station` (type and name together, empty for a plain post office), `installation_area` and `municipality` of the serving post office and `box_range` ([first, last] box of the range the number fell in). On a partial answer with reason `po_box_ambiguous` or `po_box_postcode_town_mismatch`, or `po_box_not_in_range` when the town you sent is not the postal code's, only `number` is present: no post office was identified for you. Singapore, with `address_type: po_box`: `number`, `office` (the post office that holds the box, e.g. `TANGLIN POST OFFICE`), `kind: locked_bag` on a Locked Bag (absent on a PO Box) and, when that post office has a coordinate, `office_address` (`house_number`, `street`, `postcode` of the post office itself). On a partial answer only what was identified is present.", "additionalProperties": true }, "po_box_alternatives": { "type": "array", "description": "Canada, partial PO Box answers only (`po_box_ambiguous`, `po_box_postcode_town_mismatch`, and `po_box_not_in_range` when the town you sent is not the postal code's): the post offices whose ranges hold the box number in the town you sent, and (mismatch) the post office of the postal code you sent (`station`, `postcode`, `city`, `state`). Singapore, partial PO Box answers (`po_box_not_in_range`, `po_box_ambiguous`): up to 10 post offices holding the box number (`office`, `postcode`).", "items": { "type": "object", "additionalProperties": true } }, "verdict_note": { "type": "string", "description": "Plain-language note on a component listed in `unverified_fields`, e.g. a Canadian PO Box whose station you named differently from the reference data (`po_box_station`)." }, "uprn_match_m": { "type": "number", "description": "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": { "type": "integer", "description": "After keyed validation." }, "validation_credits_remaining": { "type": "integer" }, "geocode_credits_remaining": { "type": "integer" }, "key_accepted": { "type": "boolean" } }, "$defs": { "AccuracyType": { "type": [ "string", "null" ], "x-extensible-enum": [ "rooftop", "arrival_point", "street_interpolated", "street_segment_centroid", "street_centroid", "landmark_proximity", "postcode_centroid", "locality_centroid", "admin_centroid", "po_box", "po_box_postcode_area", "po_box_office" ], "description": "What the returned coordinate represents. `null` on `no_match`, and\n`null` on an answer whose address is confirmed but has no coordinate\n(reason `no_coordinate_available`).\n\n**This is an OPEN set.** New tiers are added as reference data improves.\nClients MUST pass unrecognized values through rather than throwing, and\nSHOULD branch on `point_coordinate` rather than on these literals.\n\nA **point coordinate** identifies one address:\n * `rooftop` — a point on the building itself.\n * `arrival_point` — the address's entrance, gate or curb-side access\n point. A point for *this* address, typically a few metres from the\n roof — deliberately not claimed as the building footprint.\n\nEverything else is derived rather than observed — a segment or an area,\nnot an address:\n * `street_interpolated` — HNO estimated along a street segment polyline\n (SEG cascade) from the position of neighbouring house numbers.\n * `street_centroid` — street confirmed; exact HNO not located.\n **Singapore:** block numbers are not linear along a road and a\n letter-suffixed block (e.g. `700D`) is a separate building with its\n own postcode, so Singapore never returns `street_interpolated`. An\n unconfirmed block (or a street with no block) answers\n `street_centroid` at the street's centre, and\n `standardized.postcode` is left empty unless you supplied a\n postcode that exists on that street — a postcode names one\n building, and another building's postcode is never shown as yours.\n * `landmark_proximity` — India only. The address itself resolved no\n further than its postcode/locality, so the coordinate is that of a\n LANDMARK the caller named in the input (\"opp. Swami Samarth Math\").\n It is a point on a *neighbouring* place, never the address, and it\n is only ever used when it out-ranks what would otherwise be\n returned. The landmark used is named back to you in\n `landmark_used` (`name`, `matched_from`, `scope`, `source`).\n * `postcode_centroid` — only postcode matched.\n * `locality_centroid` — only city/locality matched.\n * `admin_centroid` — only admin region (state/province) matched.\n * `po_box` — Canada only. A PO Box matched to a Canada Post\n installation (post office / station) by its box number, station,\n town and postal code against the reference lock-box ranges. This\n tier says where the pin is, not whether the box is verified:\n that is `status` (verified / corrected), `deliverable` and\n `reasons` — a partial answer on this tier carries\n `po_box_not_in_range`. A box has no door, so the coordinate is\n the centre of the locality the post office is in;\n `point_coordinate` is `false`. See `address_type` and the\n `po_box` object.\n * `po_box_postcode_area` — Canada only. The same PO Box match, but\n the post office's locality has no coordinate of its own, so the\n pin is the centre of the box postcode's forward sortation area\n (its first three characters). The position is graded like\n `locality_centroid` (lower `confidence`); verified or not is again\n `status` / `deliverable` / `reasons` (a verified box stays\n `status` verified and `deliverable` true on this tier).\n Partial PO Box answers that name no post office\n (`po_box_ambiguous`, `po_box_postcode_town_mismatch`) and a\n not-in-range box whose typed town is not the postal code's carry\n `locality_centroid` (the centre of the town you sent) with\n `address_type: po_box`.\n * `po_box_office` — Singapore only. A PO Box confirmed in the box\n register by its box number, post office and/or 6-digit box\n postcode (90xxxx / 91xxxx). A box has no door, so the pin is the\n post office that holds the box; `point_coordinate` is `false`.\n When that post office has no coordinate, the box is still\n `status` verified and `deliverable: true`, with `lat`/`lng` and\n `accuracy_type` `null` and reason `no_coordinate_available`\n (validity and coordinates are separate). See `address_type` and\n the `po_box` object.\n" }, "AlternativeMatch": { "type": "object", "description": "**Reserved — not currently emitted** (disabled in production pending a\nstreet-leading index). Planned behaviour: same street + same house\nnumber in a different state, on USA / CAN `verified` (exact) matches\nonly, bounded to 5 rows.\n", "required": [ "standardized", "score" ], "properties": { "standardized": { "$ref": "#/$defs/StandardizedAddress" }, "score": { "type": "number", "format": "float", "description": "Always 1.0 — these are exact DB matches in a different state." }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" } } }, "FailureReason": { "type": "string", "x-extensible-enum": [ "street_not_found", "city_not_matching", "locality_unknown", "house_number_interpolated", "house_number_not_found", "house_number_unconfirmed", "house_number_range_interpolated", "street_not_matched", "street_unconfirmed", "street_not_found_in_locality", "postcode_not_matched", "postcode_unconfirmed", "postcode_town_mismatch", "postcode_locality_conflict", "postcode_valid_not_stocked", "city_unconfirmed", "below_verification_threshold", "no_coordinate_available", "resolved_to_administrative_area_only", "positioned_at_named_landmark", "non_deliverable_address", "po_box_not_in_range", "po_box_ambiguous", "po_box_postcode_town_mismatch", "po_box_number_missing", "po_box_not_found", "search_budget_exhausted", "fuzzy_budget_exceeded", "street_type_ambiguous", "city_not_found", "city_missing", "street_found_in_multiple_localities", "street_type_mismatch", "street_particle_mismatch", "street_spelling_mismatch", "locality_ambiguous", "street_missing", "fell_back_to_locality", "house_number_not_in_reference", "house_number_missing", "postcode_house_number_ambiguous", "house_number_extension_missing" ], "description": "Why a validation failed to confirm the address (or part of it).\n\n**This is an OPEN set** — new codes are added as matching logic\nimproves; pass unrecognized values through rather than throwing.\nReasons appear on 404/422 error bodies AND on 200 `partial_match`\nresponses (stating what the resolved tier could not pin down).\n * `street_not_found` — no street in the candidate set scored highly.\n On a Portugal 200 it appears together with `fell_back_to_locality`\n (`approximate: true`) when the name sent is an estate,\n urbanisation or neighbourhood that is not in the street data but\n whose town we can place: the point is then the town centre.\n * `city_not_matching` — street looked right but the locality did not.\n * `locality_unknown` — we could not even find candidates in the locality.\n * `house_number_interpolated` — house number was interpolated along a street\n segment (`street_interpolated` tier), not confirmed against a rooftop record.\n * `house_number_not_found` — street confirmed but the exact house number is not\n on file.\n * `house_number_unconfirmed` — the house number could not be confirmed\n (`street_centroid` tier partials emit this).\n * `house_number_range_interpolated` — number placed within an official\n numbering range, not a premise row.\n * `street_not_matched` — the street could not be matched; resolution stopped at a\n postcode or locality centroid.\n * `street_unconfirmed` — a street you provided could not be confirmed\n against the matched record.\n * `street_not_found_in_locality` — the street exists but not in the\n stated locality.\n * `postcode_not_matched` — the postcode could not be matched; resolution stopped\n at a locality centroid.\n * `postcode_unconfirmed` / `city_unconfirmed` — the component was echoed\n from input, not confirmed by reference data.\n * `postcode_town_mismatch` — postcode and town point at different places.\n * `postcode_locality_conflict` — postcode and locality conflict (India).\n * `postcode_valid_not_stocked` — the postcode is real but our reference\n data holds no addresses for it (Malaysia; see `postcode_status`).\n * `below_verification_threshold` — the best candidate scored under the\n verification threshold.\n * `no_coordinate_available` — matched a reference row that carries no\n coordinate.\n * `resolved_to_administrative_area_only` — only the admin region (state/province)\n resolved (`admin_centroid` tier).\n * `positioned_at_named_landmark` — coordinate taken from a landmark the\n caller named (India `landmark_proximity`; see `landmark_used`).\n * `non_deliverable_address` — PO Box / Rural Route / Postfach input\n (see `MatchType: non_deliverable`).\n * `po_box_not_in_range` — Canada: the postal code you sent belongs to\n PO Boxes, but the box number is in none of its ranges (partial).\n The town and province are shown as you sent them; one you did not\n send is the postal code's. A province that contradicts the postal\n code's own town is replaced and listed in `corrections`\n (`State`). When your town is not the postal code's, the pin is the\n centre of your town (`accuracy_type: locality_centroid`; looked up\n in the postal code's province if you sent none) and the postal\n code's post office is listed in `po_box_alternatives`. Without any\n pin (your town is unknown there) there is no PO Box answer: the\n request gets today's refusal (400 `non_deliverable_address`).\n Singapore: the 6-digit postcode you sent is a PO Box postcode,\n but the box number is not at it (partial); the post offices that\n hold that box number are listed in `po_box_alternatives`, the\n postcode's own post office first. When you name the post office\n and it holds the box, the postcode is corrected instead\n (`corrections`: `Postal code`).\n * `po_box_ambiguous` — Canada: the town and box number fit more than\n one post office; candidates are listed in `po_box_alternatives`\n (partial). Adding the postal code or the station resolves it. No\n post office is picked: `standardized` keeps the bare box line and\n the postal code you sent (blank if none), and the pin is the\n centre of the town you sent (`accuracy_type: locality_centroid`).\n Singapore: the box number exists at more than one post office and\n neither the post office nor its 6-digit postcode was sent\n (partial, no coordinate); candidates are in `po_box_alternatives`.\n * `po_box_number_missing` — Singapore: a PO Box postcode or post\n office was sent without a box number (partial, no coordinate).\n * `po_box_not_found` — Singapore: the input is a PO Box line (PO Box,\n Post Office Box, Privy Box, Locked Bag, or a 90xxxx / 91xxxx\n postcode) but no such box is in the register; Privy Box and\n Locked Bag addresses are not served. Returned on the 404 no-match\n body with `address_type: po_box`; never answered with a street.\n * `po_box_postcode_town_mismatch` — Canada: the postal code you sent\n belongs to a post office in another town AND another province than\n the ones you sent, so it is not taken as a correction of both\n (partial, `deliverable: false`, no corrections). `standardized`\n keeps what you sent; the pin is the centre of the town you sent\n (`accuracy_type: locality_centroid`), never the postal code's post\n office; that post office is listed in `po_box_alternatives`.\n * `search_budget_exhausted` — the search ran out of its per-request\n time budget (about 10 s; shorter where a per-call time limit\n applies) and the response carries `truncated: true`. On a 404 the\n input did not match directly and the recovery search (typo,\n locality and postcode fallbacks) stopped before finding a\n confident answer. This is a no-match, not a server error: the\n address may still exist. Check the input for typos or add the\n postcode, then retry; do not retry the identical request in a\n tight loop. United States `/validate` can also carry it on a 200:\n the answer is the best one found before the time limit (its\n `status`, `accuracy_type` and pin are exactly as found, never\n upgraded and never a correction), and a finer pin may exist. A\n rooftop answer never carries it.\n * `fuzzy_budget_exceeded` — Sweden (`swe`), `/validate` partial 200s\n and 404s. The street did not match as typed and the search for a\n close real street (typo correction) was cut short by its time\n limit before it finished. It is NOT proof that the street is\n absent: appears together with `street_not_matched` (200) or\n `street_not_found` (404), and the answer stops at a postcode or\n locality centroid. The caller may retry the same request once a\n moment later; a retry usually completes the correction.\n * `street_type_ambiguous` — 404 only (USA). The street NAME exists in\n the given postcode/city, but only with a different street type or\n directional than the one supplied, and more than one real street\n fits (e.g. `12th St N` when both `12th St NE` and `12th St NW` carry\n the house number). We never guess between two real streets: the\n body carries `did_you_mean`, the candidate streets (up to 6) with\n their `city` and `postcode`; resubmit with the intended one.\n Can also appear in a `/geocode-usa` 404 body, when no fallback\n centroid is available for the address.\n\n * `city_missing` — 404. A street was sent without a city or\n postcode and cannot be placed in a single locality. Sent together\n with another code (e.g. `street_not_found` or\n `street_found_in_multiple_localities`). Seen for several countries\n (e.g. Portugal, Brazil, Spain). Netherlands: also when a postcode\n was sent but is not on file (the `message` then asks for a city\n only); a postcode + house number with no street is answered\n without this code (see `postcode_house_number_ambiguous`).\n * `street_found_in_multiple_localities` — 404. The street name exists\n in more than one locality — of the town you sent, or, when no city\n was sent, of the country. Add the locality or the postcode. When\n no city was sent, `did_you_mean` lists the towns holding the\n street (at most 6).\n\n**Portugal (`country: prt`) only.** The codes below are added to\nPortuguese responses on `/validate` and `/geocode` (and their `/v1`\naliases). On a 200 they are appended after the codes listed above,\nwhich keep their meaning and position. On a 404 the first code is the\nmost specific one.\n * `city_not_found` — 404. The city/town you sent is not a place in\n the Portuguese reference data (often sent with\n `locality_unknown`). Check the spelling or send the postcode.\n * `street_type_mismatch` — 404, sent before `street_not_found`. The\n street name exists in the town only with a different street type\n (e.g. `Rua de Portugal` typed, `Avenida de Portugal` held). See\n `did_you_mean`.\n * `street_particle_mismatch` — 404, as above, when the name differs\n only in its linking particles (`da`, `de`, `do`, `das`, `dos`).\n * `street_spelling_mismatch` — 404, as above, for a close spelling\n of a street of that town.\n * `locality_ambiguous` — 404. A place name sent on its own (no\n street) is a locality in several municipalities and nothing\n coarser; it is never guessed. `did_you_mean` lists the candidates\n with `municipality` and `district`. Sent with `street_missing`.\n * `street_missing` — no street was sent. On a 200 it marks the\n labelled approximate point for a city- or neighbourhood-only\n request (`approximate: true`).\n * `fell_back_to_locality` — 200. A street was sent but could not be\n placed, and the point served is the town/area centre\n (`approximate: true`, `resolved_level`, `resolved_name`), not the\n address. For an estate or neighbourhood name sent with a town it is\n accompanied by `street_not_found`; it can also carry a\n `did_you_mean` hint and its `street_*_mismatch` code.\n * `house_number_not_in_reference` — 200. The street was matched but\n the house number you sent is not in the reference data;\n `nearby_house_numbers` names the closest same-parity numbers that\n are.\n * `house_number_missing` — 200. The street was matched but no house\n number was sent, so only a street-level point is possible.\n\n**Netherlands (`country: nld`), postcode + house number with no street:**\n * `postcode_house_number_ambiguous` — 404, with `street_missing`.\n Several streets hold that house number at that postcode; we never\n guess between them. `did_you_mean` lists them (`street`, `city`,\n `postcode`, `house_number`; at most 6).\n * `house_number_extension_missing` — 200. The number exists at that\n postcode only with a letter (`3A`, `3B`, ...) and none was sent; the\n point is that building, and `did_you_mean` lists the letters.\n * `house_number_not_in_reference` — 200 (`postcode_centroid`). The\n number is not on file at that postcode; `standardized.street` is\n empty (nothing is invented).\n" }, "MatchComponents": { "type": "object", "description": "Which input fields were confirmed by the match.", "required": [ "house_number", "street", "city", "zip", "state" ], "properties": { "house_number": { "type": "boolean" }, "street": { "type": "boolean" }, "city": { "type": "boolean" }, "zip": { "type": "boolean" }, "state": { "type": "boolean" } } }, "MatchType": { "type": "string", "description": "Internal/legacy precision tier with the score table below. New clients should\nprefer `accuracy_type` for branching.\n\nUnlike `accuracy_type`, this enum is CLOSED — the score table is fixed\nand no further values will be added. An `arrival_point` coordinate is\nreported here as `rooftop`, because the address is premise-verified\neither way; only `accuracy_type` states what the coordinate is.\nScore table:\n * `rooftop` → 1.0\n * `parcel_centroid` → 0.9\n * `interpolated` → 0.8\n * `street_level` → 0.6\n * `zip_centroid` → 0.4\n * `city_centroid` → 0.2\n * `no_match` → 0.0\n * `non_deliverable` → 0.0 — the input is a PO Box / Rural Route /\n Postfach etc. and can never resolve to a street address\n (USA/CAN/MEX/DEU/AUT/CHE detection). Returned on the 400 body\n (with `non_deliverable_type`) unless `iso20022: true` opted in to\n a labelled 200.\n", "enum": [ "rooftop", "parcel_centroid", "interpolated", "street_level", "zip_centroid", "city_centroid", "no_match", "non_deliverable" ] }, "NearbyHouseNumber": { "type": "object", "additionalProperties": true, "properties": { "hno": { "type": "string" }, "lat": { "type": [ "number", "null" ], "format": "float" }, "lng": { "type": [ "number", "null" ], "format": "float" }, "accuracy": { "type": [ "string", "null" ], "description": "The coordinate tier of that house number (e.g. `rooftop`), `null` without a coordinate." }, "has_coordinates": { "type": "boolean", "description": "`false` when the number exists in the reference data without its own coordinate (`lat`/`lng`/`accuracy` are then `null`)." } } }, "NearbyHouseNumbers": { "type": "object", "description": "**Portugal (`country: prt`) only.** Present on a 200 answer when the\nstreet was matched but the house number you sent is not in the\nreference data — the answer is then either street-level\n(`street_centroid`) or `street_interpolated` at a point between the\nnearest same-parity house numbers (`pin_between`). It lists which\nnumbers of that street ARE held, on the same side of the street (odd\nand even numbers usually face each other). Informational only: it\nnever changes the coordinate, tier, confidence or `deliverable`. Sent\nwith reason `house_number_not_in_reference`. Pass unrecognized fields\nthrough.\n", "additionalProperties": true, "properties": { "requested": { "type": "string", "description": "The house number as you sent it." }, "parity": { "type": "string", "x-extensible-enum": [ "odd", "even" ] }, "before": { "allOf": [ { "$ref": "#/$defs/NearbyHouseNumber" } ], "nullable": true, "description": "The nearest held number below the requested one on the same side, or `null`." }, "after": { "allOf": [ { "$ref": "#/$defs/NearbyHouseNumber" } ], "nullable": true, "description": "The nearest held number above the requested one on the same side, or `null`." }, "pin_between": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "integer", "description": "Number of distinct house numbers held for the street." }, "coordinated_doors": { "type": "integer", "description": "How many of those carry their own coordinate." } } }, "ResolvedLevel": { "type": "string", "description": "**Portugal (`country: prt`) only.** Which kind of place an approximate\npoint (`approximate: true`) stands for. Open set — pass unknown values\nthrough.\n * `locality` — a locality (village / town).\n * `postal_town` — the town name of the postal address.\n * `municipality` — a municipality (concelho).\n * `district` — a district.\n * `lisbon_parish` — a Lisbon parish or neighbourhood name; the point\n is Lisbon's.\n", "x-extensible-enum": [ "locality", "postal_town", "municipality", "district", "lisbon_parish" ] }, "StandardizedAddress": { "type": "object", "description": "Canonical address as stored in the reference database.", "properties": { "street": { "type": "string" }, "house_number": { "type": "string" }, "city": { "type": "string", "description": "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.\nSweden, 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": { "type": "string", "description": "Present for countries with regions (e.g. USA, CAN, AUS, MYS)." }, "postcode": { "type": "string" }, "postcode_formatted": { "type": "string", "description": "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": { "type": "string" }, "formatted_address": { "type": "string", "description": "Country-specific pretty-printed form, multi-line." }, "street_type": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "Canada: the directional element (N, SW, …) as its own field." }, "street_id": { "type": "string", "description": "France: the reference data's stable identifier for the thoroughfare." }, "building_name": { "type": "string", "description": "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": { "type": "string", "description": "Denmark (`etage`) and Hong Kong (floor). Same unambiguity rule as `building_name`, and additionally requires a confirmed house number." }, "unit_identifier": { "type": "string", "description": "Denmark (`dør`), the Netherlands (sub-address) and Hong Kong (flat). Same unambiguity rule as `level_number`." }, "ine_municipality": { "type": "string", "description": "Spain: the 5-digit INE municipality code of the matched address (leading zeros preserved — always a string)." }, "nis_code": { "type": "string", "description": "Belgium: the NIS municipality code of the matched address." }, "statistical_sector": { "type": "string", "description": "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": { "type": "string", "description": "UK only (`country: \"gbr\"`). Traditional/postal county, derived from the Royal Mail PAF postcode → county map." }, "udprn": { "type": "string", "description": "UK only. Royal Mail Unique Delivery Point Reference Number (PAF) — stable identifier for the delivery point." }, "uprn": { "type": "string", "description": "UK only. Ordnance Survey Unique Property Reference Number. Present when the address matches OS Open UPRN." }, "unit": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "Italy only. Two-letter province sigla (MI, RM, …) for the mandatory Poste Italiane locality line (`20067 PAULLO MI`)." }, "dependent_street": { "type": "string", "description": "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": { "type": "string", "description": "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": { "type": "string", "description": "UK only (PAF). Sub-locality below `dependent_locality`." }, "administrative_county": { "type": "string", "description": "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": { "type": "object", "description": "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.", "additionalProperties": true }, "english": { "type": "object", "description": "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.", "additionalProperties": true } } }, "Suggestion": { "type": "object", "description": "A ranked near-miss candidate returned on `/validate` (score ≥ 0.5, below\nthe correction threshold). Appears in `suggestions[]` on 404 no-match\nresponses and on 200 `partial_match` responses where the street could not\nbe matched — offering the closest real streets in the caller's\npostcode/locality. Not normally present on verified/corrected successes.\n", "required": [ "standardized", "score" ], "properties": { "standardized": { "$ref": "#/$defs/StandardizedAddress" }, "score": { "type": "number", "format": "float", "minimum": 0, "maximum": 1 }, "lat": { "type": "number", "format": "float" }, "lng": { "type": "number", "format": "float" } } } } }