v1
latestOpenAPI 3.1.02026-07-2342137210.8 KBPlaces
Search Places
Search for places by text query, country, geographic coordinates, or place IDs.
At least one of q, country, location, or id must be provided — otherwise a 400 is returned.
Filtering:
- q — free-text search on place name.
- country — comma-separated ISO 3166-1 alpha-2 country codes.
- location — coordinates in lat,lon or @lat,lon format. Lat must be between −90 and 90, lon between −180 and 180.
- id — comma-separated place IDs. When id is the only filter and no pagination parameters are set, an optimised multi-get is used instead of a search query.
- type — comma-separated place types. Accepts admin level values as well as aliases (e.g. local expands to neighbourhood, locality, and localadmin).
Results are paginated with offset and limit.
get/v1/places
Query parameters
offsetinteger
Zero-based index of the first result to return.
limitinteger
Maximum number of results to return per page.
idstring[]
A comma-separated list of place identifiers.
E.g. ?id=5115985
countrystring[]
A comma-separated list of ISO 3166-1 alpha-2 country code.
E.g. ?country=US
locationstring
A coordinate in the form @{latitude},{longitude}.
E.g. ?location=@40.66677,-73.88236
qstring
A full-text search query.
E.g. ?q=New+York
typestring[]
Comma-separated list of place types to filter results. Accepts administrative levels and aliases.
- planet — Earth (top level)
- continent — Continent (e.g. North America, Europe)
- country — Sovereign nation
- region — Administrative level 1 (e.g. US state, Australian state)
- county — Administrative level 2 (e.g. US county)
- localadmin — Local administrative area (e.g. a municipality)
- locality — Populated place (e.g. a city or town)
- neighbourhood — Subdivision of a locality
- major — Major populated place
- metro — Metropolitan area
- local — Alias expanding to neighbourhood, locality, and localadmin combined
Response
Successful Response