Geocoding

A backend proxy for reverse geocoding, address autocomplete, and place details, with results biased to Venezuela. Paths are relative to the /api/v1 prefix; /geocoding/reverse is public, while /geocoding/autocomplete and /geocoding/place require Authorization: Bearer {token}.

See Common errors.

Endpoints

All three share the same upstream failure modes: 503 GeocodingNotConfigured when the backend has no Google Maps API key, and 502 UpstreamError for any other upstream failure.

GET /geocoding/reverse

Resolves a coordinate pair to its nearest street address.

Query

Response 200

{
  "address": "Av. Principal, Las Mercedes, Caracas",
  "components": [ { "long_name": "Las Mercedes", "short_name": "Las Mercedes", "types": ["neighborhood"] } ],
  "placeId": "ChIJ..."
}

When the coordinates match nothing, the response is { "address": null, "components": null }.

Errors

GET /geocoding/autocomplete

Address predictions for a partial query, biased to Venezuela. Pass a sessionToken to group keystrokes into one billable Google session.

Query

Response 200

{
  "suggestions": [
    {
      "placeId": "ChIJ...",
      "description": "Av. Principal, Las Mercedes, Caracas",
      "mainText": "Av. Principal",
      "secondaryText": "Las Mercedes, Caracas"
    }
  ]
}

suggestions is [] when Google returns no matches.

Errors

GET /geocoding/place

Resolves a placeId (typically from autocomplete) into a precise location. Reuse the same sessionToken you used for autocomplete.

Query

Response 200

{
  "placeId": "ChIJ...",
  "address": "Av. Principal, Las Mercedes, Caracas",
  "latitude": 10.487,
  "longitude": -66.88
}

Errors

Examples

# Reverse geocode a coordinate (public)
curl "/api/v1/geocoding/reverse?lat=10.487&lng=-66.88"

# Autocomplete + resolve, sharing a session token
curl "/api/v1/geocoding/autocomplete?query=Av%20Principal&sessionToken=abc123" \
  -H "Authorization: Bearer {token}"
curl "/api/v1/geocoding/place?placeId=ChIJ...&sessionToken=abc123" \
  -H "Authorization: Bearer {token}"