Geocode an address (all supported countries)
Provide country and either a single-line q or fielded address components. Resolution runs the same parse → infer → lookup chain /validate uses — if /validate can place an input, /geocode places it, by construction. No component is required at the gate: street, city/town and state are all optional, including for USA and Canada. Omitting street degrades the match to a locality/postcode tier rather than failing.
Portugal (country=prt): a city-only or neighbourhood-only request (no street) returns a labelled approximate point: a 200 with approximate: true, resolved_level, resolved_name, reason street_missing, accuracy_type locality_centroid or admin_centroid. A place name that is a locality in several municipalities is never guessed: 404 with reasons: ["locality_ambiguous", "street_missing"] and the candidates in did_you_mean. A place name not found at all returns 400 Missing required field: street. A street sent without a city is placed when exactly one town holds it (the town is filled in); otherwise the 404 lists the candidate towns in did_you_mean. When the street cannot be placed in the town sent, the town centre may be served with approximate: true and reason fell_back_to_locality. This includes an estate, urbanisation or neighbourhood name sent with a town we can place (for example "Cerrado do Poço" in Porto Salvo), or with the town as the last words of the text and no city field (for example "Tapada Vale dos Lobos Belas"): the 200 is a labelled town-level point, and its reasons then carry street_not_found next to fell_back_to_locality. A street-type name (Rua, Avenida, ...) that is not found, or a name sent with an ambiguous or unknown town, stays a 404. When the house number is not in the reference data, the 200 carries nearby_house_numbers (see ForwardGeocodeResponse).
A single-line free-text address may be passed as q instead of the fielded parameters; it is parsed with the same parser the /validate path uses. This works for every supported country, including the eight (aus, bra, can, jpn, mex, mys, tur, usa) that used to require fielded street/city/state and 400 on single-line input. Explicit fielded parameters, when present, take precedence over the parsed single line.
Response vocabulary: the response is a whitelist of geocoding-only fields — lat, lng, accuracy_type, point_coordinate, standardized, formatted_address, and, conditionally, arrival_point, input_modified, attribution, uprn and digipin. See ForwardGeocodeResponse below. It never carries the /validate verdict vocabulary (status, match_type, match_score, confidence, corrections, and similar fields) — a miss is a plain {"error": "no_match", "message": "..."} body, not a verdict with everything zeroed out.
Credits: A geocode costs 1 Stripe-plan transaction (geocode=1). 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 of endpoint weight. Anonymous callers consume one free slot per IP (per-product daily free limits apply — check remaining via /geocode-credits).
Request
- Base URL: https://api.acuris-geo.com
- URL: https://api.acuris-geo.com/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
Query parameters
Legacy API key query parameter (?key=...). Prefer Authorization: Bearer <key> or X-API-Key: <key> header auth instead.
Single-line free-text address, parsed into components with the /validate parser. Works for every supported country. Explicit fielded parameters, when present, take precedence.
Optional for every country, including USA/CAN. Omitting it degrades the match to a locality/postcode tier rather than failing.
House number
City or locality (USA/CAN style). Optional — a single-line q or postalcode alone can still resolve a match.
Alternative to city for some countries. Optional.
State (USA) or province (Canada). Optional — omitting it does not fail the gate, though it can widen the fallback tier.
Postcode. The aliases postcode, zip, zipcode, zip_code and postal_code are also accepted; postalcode wins when several are sent.
Administrative tier below the city — Vietnamese phường/xã, Indonesian kelurahan, Thai tambon, Philippine barangay. Aliases: ward, subdistrict. It narrows the match and can never veto one: a value we do not hold returns the same result as omitting it. Wired for vnm; accepted and ignored elsewhere.
Ignored. Reference DBs are configured at server startup via ref_dbs.json under GEOCODE_REF_DB_ROOT.
Response
Geocode result — a whitelist of geocoding-only fields.
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.