{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/acuris-geo-com/json-schema/acuris-geo-com-reverse-response-schema.json",
  "title": "ReverseResponse",
  "description": "Reverse geocoding response. When the request's `limit=1` (default), the body\nis a single flat result. When `limit>1`, the body contains a `results` array\nof flat result objects plus `count` and top-level `match_type` / `match_score`\nreflecting the best (closest) match.\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/ReverseResponse",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "country": {
      "type": "string"
    },
    "lat": {
      "type": "number",
      "format": "float",
      "description": "Latitude of the matched address (not the query point)."
    },
    "lng": {
      "type": "number",
      "format": "float"
    },
    "distance_m": {
      "type": "integer",
      "description": "Distance in metres from the query point to this result."
    },
    "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. **Not yet emitted by `/reverse`** — until it is, derive it from `accuracy_type` (`rooftop` / `arrival_point`)."
    },
    "match_type": {
      "$ref": "#/$defs/MatchType"
    },
    "match_score": {
      "type": "number",
      "format": "float"
    },
    "input_corrected": {
      "type": "boolean",
      "description": "Always `false` for reverse geocoding (input is coordinates, not an address)."
    },
    "street": {
      "type": "string"
    },
    "hno": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "description": "Present for countries with regions (USA, CAN)."
    },
    "zip": {
      "type": "string"
    },
    "query": {
      "type": "object",
      "description": "Echo of the effective query parameters (after clamping).",
      "properties": {
        "lat": {
          "type": "number"
        },
        "lng": {
          "type": "number"
        },
        "radius_m": {
          "type": "integer"
        }
      }
    },
    "results": {
      "type": "array",
      "description": "Only present when `limit > 1`.",
      "items": {
        "type": "object"
      }
    },
    "count": {
      "type": "integer",
      "description": "Only present when `limit > 1`; equals `results.length`."
    },
    "units_charged": {
      "type": "integer",
      "description": "Echoes the number of addresses returned (`count`, or `1` when the\nbody is a flat single result). This equals the trial-key debit;\nStripe-plan keys are debited a flat `1` per request regardless.\nAlways `1` for RapidAPI traffic.\n"
    },
    "balance": {
      "type": "integer",
      "description": "Remaining geocode transactions after keyed call."
    },
    "free_remaining": {
      "type": "integer",
      "description": "Remaining anonymous geocodes for this IP today."
    }
  },
  "$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"
    },
    "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"
      ]
    }
  }
}