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)

List Countries

Retrieve a list of all countries.

GET /geocoding/countries

Results are sorted alphabetically by name. Returned in English only.

Example Response

{
  "results": [
    {
      "code": "CH",
      "name": "Switzerland",
      "flag": "🇨🇭",
      "population": 8700000,
      "continent": "EU"
    }
  ],
  "count": 1
}

Country Details

Retrieve details for a single country by its ISO 3166-1 alpha-2 code.

GET /geocoding/countries/{code}

Parameters

Parameter	Required	Description
`code`	Yes	ISO 3166-1 alpha-2 country code (case-insensitive, e.g. `CH`, `at`)

Example Request

GET /geocoding/countries/CH

Example Response

{
  "code": "CH",
  "name": "Switzerland",
  "flag": "🇨🇭",
  "population": 8700000,
  "continent": "EU",
  "timezone": "Europe/Zurich",
  "capital": "Bern"
}

Country Response Fields

Field	Type	Description
`code`	string	ISO 3166-1 alpha-2 country code
`name`	string	Country name (English)
`flag`	string	Flag emoji derived from the ISO code
`population`	integer	Country population (may be null)
`continent`	string	Continent code (may be null)
`timezone`	string	Primary IANA timezone (detail endpoint only, may be null)
`capital`	string	Capital city name (detail endpoint only, may be null)

Errors

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