Preview and API URL
You can copy this API URL into your application
API Documentation
The API endpoint https://geocoding-api.open-meteo.com/v1/search accepts a search term and returns a list of matching locations. URL parameters are listed below:
| Parameter | Format | Required | Default | Description |
|---|---|---|---|---|
| name | String | Yes | String to search for. An empty string or only 1 character will return an empty result. 2 characters will only match exact matching locations. 3 and more characters will perform fuzzy matching. The search string can be a location name or a postal code. | |
| count | Integer | No | 10 | The number of search results to return. Up to 100 results can be retrieved. |
| format | String | No | json | By default, results are returned as JSON. Alternatively, protobuf is supported for more efficient encoding and transfer. The .proto file to decode the protobuf message is available in the geocoding GitHub repository. |
| language | String | No | en | Return translated results, if available, otherwise return english or the native location name. Lower-cased. |
| apikey | String | No | Only required to commercial use to access reserved API resources for customers. The server URL requires the prefix customer-. See pricing for more information. |
Additional optional URL parameters will be added. For API stability, no required parameters will be added in the future!
JSON Return Object
On success a JSON object will be returned. Empty fields are not returned. E.g. admin4 will be missing if no fourth administrative level is available.
"results": [
{
"id": 2950159,
"name": "Berlin",
"latitude": 52.52437,
"longitude": 13.41053,
"elevation": 74.0,
"feature_code": "PPLC",
"country_code": "DE",
"admin1_id": 2950157,
"admin2_id": 0,
"admin3_id": 6547383,
"admin4_id": 6547539,
"timezone": "Europe/Berlin",
"population": 3426354,
"postcodes": [
"10967",
"13347"
],
"country_id": 2921044,
"country": "Deutschland",
"admin1": "Berlin",
"admin2": "",
"admin3": "Berlin, Stadt",
"admin4": "Berlin"
},
{
...
}]
| Parameter | Format | Description |
|---|---|---|
| id | Integer | Unique ID for this location |
| name | String | Location name. Localized following the &language= parameter, if possible |
| latitude, longitude | Floating point | Geographical WGS84 coordinates of this location |
| elevation | Floating point | Elevation above mean sea level of this location |
| timezone | String | Time zone using time zone database definitions |
| feature_code | String | Type of this location. Following the GeoNames feature_code definition |
| country_code | String | 2-Character FIPS country code. E.g. DE for Germany |
| country | String | Country name. Localized following the &language= parameter, if possible |
| country_id | Integer | Unique ID for this country |
| population | Integer | Number of inhabitants |
| postcodes | String array | List of postcodes for this location |
| admin1, admin2, admin3, admin4 | String | Name of hierarchical administrative areas this location resides in. Admin1 is the first administrative level. Admin2 the second administrative level. Localized following the &language= parameter, if possible |
| admin1_id, admin2_id, admin3_id, admin4_id | Integer | Unique IDs for the administrative areas |
Errors
In case an error occurs, for example a URL parameter is not correctly specified, a JSON error object is returned with a HTTP 400 status code.
"error": true,
"reason": "Parameter count must be between 1 and 100."
Attribution
- Location data based on GeoNames
- Country flags from HatScripts/circle-flags