Sign in

v1

latestOpenAPI 3.0.32026-07-1761214.3 KB
Geocoding

Forward geocoding (autocomplete + admin enrichment)

Sequential pipeline:

  1. libpostal normalizes the query.
  2. Photon returns ranked candidates.
  3. Placeholder fills in missing admin chain (country / state / city) per candidate.

Returns gracefully when Photon is down: data: [], meta.upstream: "unavailable".

get/api/v1/search

Query parameters

qstring required
limitinteger
langstring
latnumber double

Optional proximity bias

lonnumber double

Response

results returned (possibly empty)

Example response

{
  "data": [
    {
      "id": "node:240109189",
      "name": "Berlin",
      "label": "Berlin, Germany",
      "type": "city",
      "coords": {
        "lat": 52.52,
        "lon": 13.405
      },
      "admin": {
        "country": "Germany",
        "state": "Berlin",
        "city": "Berlin"
      }
    }
  ],
  "meta": {
    "upstream": "ok",
    "count": 5
  }
}