GeocodeResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/acuris-geo-com/json-schema/acuris-geo-com-geocode-response-schema.json",
  "title": "GeocodeResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/acuris-geo-com-openapi.json#/components/schemas/GeocodeResponse",
  "type": "object",
  "additionalProperties": true,
  "required": [
    "match_type",
    "match_score",
    "match_components",
    "input_corrected",
    "accuracy_type"
  ],
  "properties": {
    "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"
        }
      }
    },
    "formatted_address": {
      "type": "string"
    },
    "street": {
      "type": "string"
    },
    "city": {
      "type": "string",
      "description": "Present for countries with regions (USA, CAN)."
    },
    "town": {
      "type": "string",
      "description": "Alternative to `city` for countries without regions."
    },
    "state": {
      "type": "string"
    },
    "postcode": {
      "type": "string"
    },
    "hno": {
      "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"
    },
    "matched_via_alias": {
      "type": "boolean",
      "description": "True when a locality alias (USPS city / CAN community) was used."
    },
    "usps_city": {
      "type": "string"
    },
    "locality_note": {
      "type": "string"
    },
    "city_mismatch_ignored": {
      "type": "boolean",
      "description": "Canada only — matched by province + street + HNO, city name ignored."
    },
    "address_type": {
      "type": "string",
      "x-extensible-enum": [
        "po_box"
      ],
      "description": "Present when the answer is not a street address. Today only `po_box` (Canada and Singapore): a PO Box matched against the reference lock-box ranges (Canada) or the box register (Singapore), served with the `po_box` object as on `/validate`. Absent on street addresses."
    },
    "po_box": {
      "type": "object",
      "additionalProperties": true,
      "description": "With `address_type: po_box`: the box, as on `/validate`. Canada: `number`, `station_type`, `station_name`, `station`, `installation_area`, `municipality`, `box_range`. Singapore: `number`, `office`, `office_address`, and `kind: locked_bag` on a Locked Bag row (absent on a PO Box)."
    },
    "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. Optional but always emitted on a match."
    },
    "match_type": {
      "$ref": "#/$defs/MatchType"
    },
    "match_score": {
      "type": "number",
      "format": "float",
      "minimum": 0,
      "maximum": 1
    },
    "match_components": {
      "$ref": "#/$defs/MatchComponents"
    },
    "input_corrected": {
      "type": "boolean"
    },
    "balance": {
      "type": "integer",
      "description": "Remaining geocode transactions after keyed call."
    },
    "validation_credits": {
      "type": "integer"
    },
    "free_remaining": {
      "type": "integer"
    }
  },
  "$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"
    },
    "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"
      ]
    }
  }
}