Geocoding

The geocoding product converts between place descriptions and coordinates:

• Forward — a query string (a place name or address) to matching coordinates and a normalized address.
• Reverse — a latitude/longitude to nearby addresses.

Both endpoints are GET, require authentication, and are metered per request. Every successful response is wrapped in the standard data envelope with a results array (which may be empty).

• Base path: https://api.altuq.ai/v1/geocoding

Forward — GET /v1/geocoding/forward

Resolve a place name or address to coordinates.

Query parameters

Parameter	Required	Type	Description
query	yes	string	The place name or address to look up.
country	no	string	A country hint as an ISO 3166-1 alpha-2 code (exactly two letters, e.g. JP, US). Narrows results to that country.
language	no	string	Preferred language for the returned address text (e.g. en, ja).
limit	no	integer	Maximum number of results. Must be a non-negative integer; values above 50 are clamped to 50. Omit for the default.

Example request

curl "https://api.altuq.ai/v1/geocoding/forward?query=Tokyo%20Station&country=JP&limit=2" \
  -H "Authorization: Bearer ak_1a2b3c4d_9f8e7d6c5b4a3210fedcba9876543210"

Example response

{
  "data": {
    "results": [
      {
        "formatted": "Tokyo Station",
        "latitude": 35.681,
        "longitude": 139.767,
        "components": {
          "country": "JP",
          "region": "Tokyo",
          "locality": "Chiyoda",
          "neighborhood": "Marunouchi",
          "block": "1",
          "number": "9"
        },
        "postal_code": "100-0005",
        "confidence": 0.9,
        "precision": "parcel"
      }
    ]
  }
}

Reverse — GET /v1/geocoding/reverse

Resolve a coordinate to nearby addresses.

Query parameters

Parameter	Required	Type	Description
latitude	yes	number	Latitude, between -90 and 90.
longitude	yes	number	Longitude, between -180 and 180.
radius_meters	no	number	Search radius in metres. Must be non-negative. Omit to leave it unbounded.
limit	no	integer	Maximum number of results. Must be a non-negative integer; values above 50 are clamped to 50. Omit for the default.

Example request

curl "https://api.altuq.ai/v1/geocoding/reverse?latitude=35.681&longitude=139.767&limit=2" \
  -H "Authorization: Bearer ak_1a2b3c4d_9f8e7d6c5b4a3210fedcba9876543210"

Example response

{
  "data": {
    "results": [
      {
        "formatted": "Near Tokyo Station",
        "latitude": 35.681,
        "longitude": 139.767,
        "components": {
          "country": "JP",
          "region": "Tokyo",
          "locality": "Chiyoda",
          "block": "2"
        },
        "postal_code": "100-0005",
        "confidence": 0.8,
        "precision": "block",
        "distance_meters": 12.5
      }
    ]
  }
}

Response fields

Each entry in results has the following fields. Optional fields are omitted when empty rather than sent as null.

Field	Type	Always present?	Description
latitude	number	yes	Latitude of the result. Always present — 0 is a valid value (the equator) and is never omitted.
longitude	number	yes	Longitude of the result. Always present — 0 is a valid value (the prime meridian) and is never omitted.
confidence	number	yes	Match confidence, from 0 to 1. Always present, including a genuine 0.
formatted	string	no	A single-line formatted address. Omitted when the upstream has none.
postal_code	string	no	Postal or ZIP code. Omitted when unknown.
precision	string	no	Granularity of the match: one of parcel, block, street, locality, admin. Omitted when unspecified.
components	object	no	Normalized address parts (see below). The whole object is omitted when every part is empty.
distance_meters	number	reverse only	Distance from the queried point to this result, in metres. Present on every reverse result (including a genuine 0 for an exact point match) and never present on forward results.

components

The components object breaks the address into normalized parts. Every field is optional and omitted when empty; the whole object is omitted when all are empty.

Field	Type	Description
country	string	Country, as an ISO 3166-1 alpha-2 code (e.g. JP).
region	string	Top-level administrative area (prefecture, state, province).
locality	string	City, ward, town, or village.
sublocality	string	A subdivision of the locality.
neighborhood	string	Neighborhood or district.
block	string	Block-level identifier.
number	string	Building or lot number.

note

Responses contain only the fields documented above. They never reveal which provider or dataset produced a result. Any required third-party data notices are published separately on the data notices page, not in API responses.

Errors

Geocoding uses the shared error envelope. The cases you are most likely to hit:

Status	code	Cause
400	bad_request	Missing query (forward); missing or out-of-range latitude/longitude (reverse); a malformed country, limit, or radius_meters.
401	unauthorized	Missing or invalid API key.
404	not_found	An unknown sub-path under /v1/geocoding/ (only forward and reverse exist).
405	method_not_allowed	A non-GET method — both endpoints are GET only.
429	rate_limited	The key's rate limit was exceeded; honour Retry-After.
502 / 503 / 504	bad_gateway / unavailable / gateway_timeout	Transient upstream or platform issues — retry with backoff.