POST /v1/geography/resolve
POST /v1/geography/resolve
| Scope | Idempotency-Key | Operation ID |
|---|---|---|
geography.read | — | resolveLocation |
Resolve a pin to suburb, zone and gateway.
Resolution order: plausibility (bounds, precision, reported accuracy) → containment in the
ACTIVE boundary version → nearest suburb within the configured tolerance (approximate)
→ cross-check of address_text against suburb names and aliases (address_text_disagrees;
surfaced, never overriding) → derived zone and gateway. A location is always a pin: there
is no suburb-name input, and an unresolvable pin never becomes valid.
Failures are exactly LOCATION_NOT_SUPPORTED (outside the service area, or implausible),
LOCATION_NOT_CONFIRMED (contradictory data) and LOCATION_VERIFICATION_FAILED
(technical failure; retry). Read-only: no Idempotency-Key.
Request
Signed with your API credential: see Authentication.
Body
| Field | Type | Required | Description |
|---|---|---|---|
latitude | number | Yes | WGS84; precision is judged as sent |
longitude | number | Yes | |
accuracy_m | number | No | The device's reported accuracy radius, if known |
address_text | string | No | Cross-checked against suburb names and aliases; never a location At most 300 characters. |
Responses
200
The resolution.
| Field | Type | Required | Description |
|---|---|---|---|
suburb | object | Yes | |
suburb.reference | string | Yes | Pattern ^SUB-[0-9A-HJKMNP-TV-Z]{8}$. |
suburb.name | string | Yes | |
zone | object | Yes | |
zone.code | string | Yes | |
zone.name | string | Yes | |
gateway | object | Yes | |
gateway.code | string | Yes | |
gateway.name | string | Yes | |
description | string | Yes | The human-readable description every customer surface shows |
approximate | boolean | Yes | |
address_text_disagrees | boolean | Yes | |
boundary_version | string | Yes |
400
Structural validation failed or an Idempotency-Key is missing.
The error envelope: code, message, detail, request_id.
401
Unknown, revoked or wrong-environment credential, bad signature, or expired session.
The error envelope: code, message, detail, request_id.
403
Tenant access denied (existence is not disclosed), insufficient scope, MFA/step-up required, partner blocked or module disabled.
The error envelope: code, message, detail, request_id.
404
No such route, or no such resource visible to the caller.
The error envelope: code, message, detail, request_id.
422
Semantically invalid (location, vehicle, server-controlled field, bulk limits).
The error envelope: code, message, detail, request_id.
429
Rate limit reached; honour Retry-After.
The error envelope: code, message, detail, request_id.
500
Unexpected failure. Only code and request_id are returned.
The error envelope: code, message, detail, request_id.
503
Pricing/routing unavailable, request timeout, retryable contention, or an operator must act first (ACCOUNTING_PERIOD_UNAVAILABLE, outcome REQUIRES_ADMIN), or the payment provider cannot start a payment (PAYMENT_PROVIDER_UNAVAILABLE, outcome REQUIRES_PAYMENT; nothing charged).
The error envelope: code, message, detail, request_id.