Versioned aliases (v1)

Geocode an address (versioned alias, JSON body)

Versioned alias of GET /geocode — same handler, same response shape, same billing. Accepts the geocode parameters as a JSON body instead of a query string (scalar body fields are folded onto the query params; query-string values win on collision). In addition to the fielded parameters, this alias accepts a single-line free-text address as q, which is parsed into components with the same parser the /validate path uses (explicit fielded params take precedence over the parsed line). q also works on GET /geocode; and GET /v1/geocode with the same query parameters as the unversioned route is accepted too.

Credits: geocode=1 Stripe-plan transaction per call. Combined AV+GEO pool since 2026-07-23: an address validation costs one transaction and includes coordinates at no extra cost; a standalone geocode also costs one transaction, from the same plan allowance. The trial pool decrements 1 regardless. Anonymous callers consume one free slot per IP (per-product daily free limits apply — check remaining via /geocode-credits; anonymous access is rate-limited per IP).

post/v1/geocode

Request

  • Base URL: https://api.acuris-geo.com
  • URL: https://api.acuris-geo.com/v1/geocode
  • 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

Request body

countrystring required
qstring

Single-line free-text address, parsed into components.

streetstring
hnostring

House number

citystring
townstring

Alternative to city for some countries

statestring

State (USA) or province (Canada)

postalcodestring

Postcode. The aliases postcode, zip, zipcode, zip_code and postal_code are also accepted; postalcode wins when several are sent.

keystring

API key in the body (legacy; folded onto ?key=). Header auth is preferred.

db_versionstring

Ignored. Reference DBs are configured at server startup via ref_dbs.json.

Example request

{
  "country": "usa",
  "q": "1600 Pennsylvania Ave NW, Washington, DC 20500"
}

Response

Geocode result — a whitelist of geocoding-only fields. See GET /geocode for worked examples.

latnumber float required
lngnumber float required
accuracy_typestring 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_coordinateboolean required

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.

formatted_addressstring required

Printable multi-line address block, e.g. for a shipping label.

input_modifiedstring[]

Lowercase names of the components the engine changed from what the caller sent in a single-line q= input (e.g. ["street", "city"]), deduped. States a fact about the input, not a verdict about the address — it is not a re-admission of the forbidden corrections / input_corrected AV fields. Present only when non-empty: no key at all when nothing was modified, never an empty array.

attributionstring

GBR only.

uprnstring

GBR only. Ordnance Survey Unique Property Reference Number, present when known.

digipinstring

IND only. India Post DIGIPIN, a deterministic 10-character code derived purely from lat/lng (never from address existence — it says nothing about whether the address itself was verified). Present only when this deployment has DIGIPIN enabled; not guaranteed on every India response even from a deployment that has it enabled (omitted if no coordinate was resolved, or the encoder found none).

reasonsFailureReason[]

PRT only, optional. Present when the point is not a confirmed house: what could not be pinned down (e.g. house_number_unconfirmed + house_number_not_in_reference, below_verification_threshold + house_number_missing, or street_missing / fell_back_to_locality on an approximate point). Same codes as /validate.

street_postcodes_totalinteger

With street_postcodes, how many postcodes the street covers (not capped).

street_postcodes_truncatedboolean

With street_postcodes, true when the street covers more postcodes than are listed.

approximateboolean

PRT only, optional. true when the point is a town / area centre standing in for the address — a city- or neighbourhood-only request (street_missing) or a street that could not be placed (fell_back_to_locality). accuracy_type is then locality_centroid or admin_centroid.

resolved_levelstring

Portugal (country: prt) only. Which kind of place an approximate point (approximate: true) stands for. Open set — pass unknown values through.

  • locality — a locality (village / town).
  • postal_town — the town name of the postal address.
  • municipality — a municipality (concelho).
  • district — a district.
  • lisbon_parish — a Lisbon parish or neighbourhood name; the point is Lisbon's.
resolved_namestring

PRT only, with approximate. The place's name as spelled in the reference data.

balanceinteger

Remaining geocode transactions after a keyed, non-free-tier call.

validation_creditsinteger
free_remaininginteger

Free calls left today, for anonymous and non-free_av_geo free-tier callers.

key_classstring

Present only for verified free_av_geo keys — "free_av_geo". See /check-key.

free_daily_limitinteger

Present only for verified free_av_geo keys. Always 1000 (the shared daily allowance).

Example response

{
  "standardized": {
    "country": "deu"
  },
  "attribution": "Contains OS data © Crown copyright and database right 2026",
  "digipin": "39J49LL8T4",
  "nearby_house_numbers": {
    "requested": "46",
    "before": {
      "hno": "44"
    },
    "after": {
      "hno": "44"
    },
    "pin_between": [
      "44",
      "50"
    ]
  },
  "street_postcodes": [
    {
      "postcode": "9573 PA",
      "house_number_from": 3,
      "house_number_to": 22
    }
  ],
  "postcode_range": {
    "from": "9573 PA",
    "to": "9573 PH",
    "text": "from 9573 PA to 9573 PH"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.