SuggestItem

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/acuris-geo-com/json-schema/acuris-geo-com-suggest-item-schema.json",
  "title": "SuggestItem",
  "description": "One autocomplete suggestion from `/suggest`. Carries the\nStandardizedAddress fields (flat, not nested) plus the additions below.\nUK identifiers (`udprn`, `uprn`, `county`) are **never** present on\nsuggestions — obtain them by submitting the chosen suggestion to\n`/validate` or via `/postcode-lookup`.\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/SuggestItem",
  "allOf": [
    {
      "$ref": "#/$defs/StandardizedAddress"
    },
    {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number",
          "description": "Omitted when the reference row carries no coordinate — never invented."
        },
        "lng": {
          "type": "number",
          "description": "Omitted when the reference row carries no coordinate — never invented."
        },
        "count": {
          "type": "integer",
          "description": "Number of reference premises merged into this row; present when more than one. Germany (`deu`): when the query carries no house number, the printed `formatted_address` of such a row is street-level (street, postcode and town, no house number) once the street-level label is enabled; `house_number` and the coordinates (v=1) are those of one representative premise, and `GET /suggest/expand` lists the street's premises, up to 50 per page (`offset` selects the next page; `has_more` / `next_offset` in the answer), up to 400 per street."
        },
        "locality": {
          "type": "string",
          "description": "Secondary locality, for countries whose reference data carries no postal code column (e.g. IRL)."
        },
        "building_name": {
          "type": "string",
          "description": "UK postcode-mode: labels each delivery point at the postcode."
        },
        "organisation_name": {
          "type": "string",
          "description": "UK postcode-mode: organisation at the delivery point."
        },
        "department": {
          "type": "string",
          "description": "UK postcode-mode: department within the organisation."
        },
        "city_kanji": {
          "type": "string",
          "description": "JPN: kanji display form of `city`."
        },
        "state_kanji": {
          "type": "string",
          "description": "JPN: kanji display form of `state`."
        },
        "street_kanji": {
          "type": "string",
          "description": "JPN: kanji display form of `street`."
        },
        "jpn_zip": {
          "type": "string",
          "description": "JPN: feed back as the `zip` parameter for the stage-2 banchi-gō lookup."
        },
        "jpn_oaza_norm": {
          "type": "string",
          "description": "JPN: feed back as the `oaza` parameter for the stage-2 lookup."
        },
        "jpn_chome": {
          "type": "string",
          "description": "JPN: feed back as the `chome` parameter for the stage-2 lookup."
        },
        "building": {
          "type": "string",
          "description": "SGP: the building name of the suggested premise. When the query matched a building name, this is the name that was matched (a building known under more than one name shows the one you typed). Never part of `formatted_address`, except on a PO Box row, where it is the post office that holds the box and the second line of `formatted_address`. Also returned on `v=2` list rows."
        },
        "address_type": {
          "type": "string",
          "x-extensible-enum": [
            "po_box"
          ],
          "description": "`po_box` on a PO Box row (Canada, Singapore); absent on street rows. Singapore: a line naming a box (\"Tanglin PO Box 470\", \"PO Box 143, Singapore 900243\") or a 90xxxx / 91xxxx box postcode lists boxes from the box register: the exact box first, then boxes whose number starts with the digits typed, within the post office or postcode typed. Example row: `{\"street\": \"PO BOX 470\", \"house_number\": \"\", \"city\": \"SINGAPORE\", \"postcode\": \"912416\", \"country\": \"sgp\", \"lat\": 1.305612, \"lng\": 103.822963, \"formatted_address\": \"PO BOX 470\\nTANGLIN POST OFFICE\\nSINGAPORE 912416\", \"building\": \"TANGLIN POST OFFICE\", \"accuracy_type\": \"po_box_office\", \"address_type\": \"po_box\", \"po_box\": {\"number\": \"470\", \"office\": \"TANGLIN POST OFFICE\", \"office_address\": {\"house_number\": \"56\", \"street\": \"TANGLIN ROAD\", \"postcode\": \"247964\"}}}`. A box whose post office has no coordinate has `lat`, `lng` and `accuracy_type` `null`. A Locked Bag (\"Locked Bag 10, Singapore 908186\") is listed the same way with `street` `LOCKED BAG 10` and `po_box.kind: locked_bag`; a Locked Bag postcode lists its bags. Privy Box lines return an empty list."
        },
        "po_box": {
          "type": "object",
          "additionalProperties": true,
          "description": "With `address_type: po_box`: the box, as on `/validate`."
        },
        "tenant": {
          "type": "string",
          "description": "SGP: when the query matched the name of a business at the premise (e.g. `mcdonalds`), that name as listed. A business with several outlets returns up to five of its premises, each with its own `building`. Never part of `formatted_address`. Also returned on `v=2` list rows."
        }
      }
    }
  ],
  "$defs": {
    "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
        }
      }
    }
  }
}