Overview

The Geocoding API lets you search for locations worldwide and retrieve location details. It supports fuzzy matching, localized results, and direct ID lookups.

Search

Search for locations by name with optional fuzzy matching.

GET /geocoding/lookup?q={query}

Parameters

Parameter	Required	Default	Description
`q`	Yes	—	Search query (minimum 2 characters)
`language`	No	`en`	Language code for localized results (e.g. `de`, `it`, `fr`)
`field`	No	`name`	Search scope. `name` searches location names only. `all` searches name, administrative region, and country.
`country`	No	—	ISO 3166-1 alpha-2 country code to filter results (e.g. `AT`, `CH`, `US`)
`limit`	No	`10`	Maximum number of results (max 50)

Example Request

GET /geocoding/lookup?q=Zurich&language=en&limit=5

Example Response

{
  "results": [
    {
      "id": "3704415940",
      "name": "Zürich",
      "lat": 47.36667,
      "lon": 8.55,
      "country_code": "CH",
      "country_name": "Switzerland",
      "admin1_name": "Kanton Zürich",
      "timezone": "Europe/Zurich",
      "population": 341730,
      "feature_code": "PPLA"
    }
  ],
  "count": 1
}

Lookup by ID

Retrieve a specific location by its unique ID.

GET /geocoding/lookup?id={location_id}

Parameters

Parameter	Required	Description
`id`	Yes	The location’s unique public ID

Example Request

GET /geocoding/lookup?id=3704415940

Example Response

{
  "id": "3704415940",
  "name": "Zürich",
  "lat": 47.36667,
  "lon": 8.55,
  "country_code": "CH",
  "country_name": "Switzerland",
  "admin1_name": "Kanton Zürich",
  "admin2_name": "Bezirk Zürich",
  "timezone": "Europe/Zurich",
  "population": 341730,
  "elevation": null,
  "feature_code": "PPLA"
}

Response Fields

Field	Type	Description
`id`	string	Unique location identifier
`name`	string	Location name (localized when `language` parameter is set)
`lat`	float	Latitude
`lon`	float	Longitude
`country_code`	string	ISO 3166-1 alpha-2 country code
`country_name`	string	Country name
`admin1_name`	string	First-level administrative division (e.g. state, canton)
`admin2_name`	string	Second-level administrative division (e.g. district, county)
`timezone`	string	IANA timezone identifier
`population`	integer	Population (may be null)
`elevation`	integer	Elevation in meters (may be null)
`feature_code`	string	Feature code indicating location type (e.g. `PPL` for city, `PPLA` for capital, `AIRP` for airport)

Errors

Status	Description
`400`	Missing required parameter (`id` or `q`)
`404`	Location not found (ID lookup only)
`503`	Geocoding data not yet loaded