Geocoding API

Search locations globally in any language

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		Location name or postal code. Append a country or first-level administrative area after a comma to narrow the results. See matching rules and examples below.
count	Integer	No	10	The number of search results to return. Up to 100 results can be retrieved. Country and administrative-area filters are applied before the result limit.
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.
countryCode	String	No		ISO-3166-1 alpha2 country code, which the results will be filtered for. Use this parameter for unambiguous country-code filtering. It can be combined with a first-level administrative-area qualifier in name.

The name parameter accepts a location optionally followed by a comma and a country or first-level administrative area, in the form <location>[, <country or admin1>]. For example, Paris, France, Los Angeles, California or Los Angeles, CA. The following matching rules apply:

Location

Two characters match an exact name. Three or more use normalized prefix matching. Matching is case-insensitive and diacritic-insensitive, but the characters must match the beginning of an indexed name. Empty and single-character searches return no results.

Country or admin1

The qualifier must match exactly; partial and prefix matching are not supported. For example, Los Angeles, Calif does not match Los Angeles, California. Country names, 2-letter ISO country codes, admin1 names and admin1 abbreviations are accepted. Localized qualifiers follow the language parameter; English and language-neutral aliases are also accepted.

Note: If an abbreviation is both an admin1 abbreviation and a country code, the admin1 abbreviation takes precedence. Use countryCode for unambiguous country filtering. If the search term contains multiple commas, only the text between the first and second comma is used as the qualifier.

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 ISO-3166-1 alpha2 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

*Note: All IDs can be can be resolved via the API endpoint https://geocoding-api.open-meteo.com/v1/get?id=2950159

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