v1
latestOpenAPI 3.1.02026-07-2342137210.8 KBGet Place Hierarchies
Return the administrative hierarchy chain for one or more places.
Exactly one of location.place_id or location.origin must be provided — supplying both or neither returns 400.
By place ID (location.place_id): Returns stored hierarchies for the given place IDs. Results are paginated over the matched places. The country filter is not applied in this mode.
By coordinates (location.origin): Finds the nearest locality to the given lat,lon and returns its hierarchy chain.
- When level is region or above (planet, continent, country, region), only nearby localities are considered.
- When level is more granular than region (county, localadmin, locality, neighbourhood) or not specified, the search is extended to include major and metro areas within the same region as the nearest locality.
- If no locality is found at the exact coordinates, a 500 km fallback radius is applied before giving up.
- Use country (comma-separated ISO 3166-1 alpha-2 codes) to restrict the coordinate lookup to specific countries.
Use level to scope which hierarchy levels are returned.
Results are paginated with offset and limit.
Query parameters
A comma-separated list of place_id in the form {place_id1},{place_id2},....
Please note that you must specify either location.origin or location.place_id in your request.
E.g. ?location.place_id=5809844,6252001
An ISO 3166-1 alpha-2 country code.
E.g. ?country=US
Administrative level of a place in the Geonames hierarchy.
Administrative level at which to return hierarchy results. Defaults to locality.
- 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
A coordinate in the form {latitude},{longitude}.
Please note that you must specify either location.origin or location.place_id in your request.
E.g. ?location.origin=47.615337,-122.203981
Zero-based index of the first result to return.
Maximum number of results to return per page.
Response
Successful Response