---
title: "Geocode (United States shorthand)"
method: GET
path: "/geocode-usa"
tags: ["Geocoding"]
---

# Geocode (United States shorthand)

`GET /geocode-usa`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/geocode-usa`
- Auth: one of:
  - API key in header `X-Acuris-Key`
  - HTTP bearer
  - API key in header `X-API-Key`
  - API key in query parameter `key`
  - none

Same as `/geocode?country=usa` with `city` and `state` parameters.

## Query parameters

- `key` string
- `street` string, required
- `hno` string
- `city` string, required
- `state` string, required

## Response `200`

Geocode result with coordinates and `accuracy_type` precision tier.

- GeocodeResponse
  - `lat` number, float
  - `lng` number, float
  - `arrival_point` object: Entrance / access coordinate (arrival point) of the matched premise, returned beside the served coordinate on house-number-level matches when the reference row carries one. With `accuracy_type: rooftop` this is the door/curb point of the same address (useful for delivery and navigation); with `accuracy_type: arrival_point` it simply equals `lat`/`lng`. Omitted when the match is not premise-level or no arrival point is on file — never null.
    - `lat` number, float
    - `lng` number, float
  - `formatted_address` string
  - `street` string
  - `city` string: Present for countries with regions (USA, CAN).
  - `town` string: Alternative to `city` for countries without regions.
  - `state` string
  - `postcode` string
  - `hno` string
  - `house_number_not_found` boolean: The house number you sent is not on file for the matched street — either flagged by the matcher itself, or caught by the input-vs-returned comparison (a fallback row carried a different number). standardized keeps YOUR house number in this case; match tier is capped at street_level.
  - `postcode_corrected` boolean
  - `matched_via_alias` boolean: True when a locality alias (USPS city / CAN community) was used.
  - `usps_city` string
  - `locality_note` string
  - `city_mismatch_ignored` boolean: Canada only — matched by province + street + HNO, city name ignored.
  - `accuracy_type` string, nullable, required: What the returned coordinate represents. `null` on `no_match`. **This is an OPEN set.** New tiers are added as reference data improves. Clients MUST pass unrecognized values through rather than throwing, and SHOULD branch on `point_coordinate` rather than on these literals. A **point coordinate** identifies one address: * `rooftop` — a point on the building itself. * `arrival_point` — the address's entrance, gate or curb-side access point. A point for *this* address, typically a few metres from the roof — deliberately not claimed as the building footprint. Everything else is derived rather than observed — a segment or an area, not an address: * `street_interpolated` — HNO estimated along a street segment polyline (SEG cascade) from the position of neighbouring house numbers. * `street_centroid` — street confirmed; exact HNO not located. **Singapore:** block numbers are not linear along a road and a letter-suffixed block (e.g. `700D`) is a separate building with its own postcode, so Singapore never returns `street_interpolated`. An unconfirmed block (or a street with no block) answers `street_centroid` at the street's centre, and `standardized.postcode` is left empty unless you supplied a postcode that exists on that street — a postcode names one building, and another building's postcode is never shown as yours. * `landmark_proximity` — India only. The address itself resolved no further than its postcode/locality, so the coordinate is that of a LANDMARK the caller named in the input ("opp. Swami Samarth Math"). It is a point on a *neighbouring* place, never the address, and it is only ever used when it out-ranks what would otherwise be returned. The landmark used is named back to you in `landmark_used` (`name`, `matched_from`, `scope`, `source`). * `postcode_centroid` — only postcode matched. * `locality_centroid` — only city/locality matched. * `admin_centroid` — only admin region (state/province) matched.
  - `point_coordinate` boolean: `true` when the coordinate identifies one address (`rooftop` or `arrival_point`), `false` for any derived/area tier. Branch on this rather than on `accuracy_type` literals — it stays correct when new tiers are added. Optional but always emitted on a match.
  - `match_type` 'rooftop' | 'parcel_centroid' | 'interpolated' | 'street_level' | 'zip_centroid' | 'city_centroid' | 'no_match' | 'non_deliverable', required: Internal/legacy precision tier with the score table below. New clients should prefer `accuracy_type` for branching. Unlike `accuracy_type`, this enum is CLOSED — the score table is fixed and no further values will be added. An `arrival_point` coordinate is reported here as `rooftop`, because the address is premise-verified either way; only `accuracy_type` states what the coordinate is. Score table: * `rooftop` → 1.0 * `parcel_centroid` → 0.9 * `interpolated` → 0.8 * `street_level` → 0.6 * `zip_centroid` → 0.4 * `city_centroid` → 0.2 * `no_match` → 0.0 * `non_deliverable` → 0.0 — the input is a PO Box / Rural Route / Postfach etc. and can never resolve to a street address (USA/CAN/MEX/DEU/AUT/CHE detection). Returned on the 400 body (with `non_deliverable_type`) unless `iso20022: true` opted in to a labelled 200.
  - `match_score` number, float, required
  - `match_components` MatchComponents, required: Which input fields were confirmed by the match.
    - `house_number` boolean, required
    - `street` boolean, required
    - `city` boolean, required
    - `zip` boolean, required
    - `state` boolean, required
  - `input_corrected` boolean, required
  - `balance` integer: Remaining geocode transactions after keyed call.
  - `validation_credits` integer
  - `free_remaining` integer

## Other responses

- `400`: Missing parameters
- `403`: Limit or transaction balance. Key-level 403s: `{"error": "key_blocked", "message"}` when the API key has been blocked (the `message` says why), and `{"error": "ip_not_allowed", "message", "ip"}` when the key is restricted to approved source IP addresses and this request came from another one (`ip` is the address we saw). Source-IP restriction is optional and set up per key on request via support.
- `404`: Address not found. Body carries `match_type: no_match`, zeroed `match_score`, and a full-false `match_components`.
- `429`: Too many requests (anonymous limit or WAF/limiter)

---

[API](https://skmtc.dev/acuris-geo/apis/acuris-geo-api.md) · [All operations](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/revisions/8547b31dd96a?raw)