---
title: "Get Place Hierarchies"
method: GET
path: "/v1/places/hierarchies"
tags: ["Hierarchies"]
---

# Get Place Hierarchies

`GET /v1/places/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

- `location.place_id` string[]
- `country` string[]
- `level` 'planet' | 'continent' | 'country' | 'region' | 'county' | 'localadmin' | 'locality' | 'neighbourhood' — Administrative level of a place in the Geonames hierarchy.
- `location.origin` string
- `offset` integer
- `limit` integer

## Response `200`

Successful Response

- HierarchiesResponse
  - `count` integer, required — Total number of hierarchy chains matching the query
  - `next` string, nullable — URL to next page
  - `previous` string, nullable — URL to previous page
  - `place_hierarchies` array[], required — Array of hierarchy chains, each an ordered list from broadest to most specific administrative level
    - HierarchyDetails[]
      - `type` 'planet' | 'continent' | 'country' | 'region' | 'county' | 'localadmin' | 'locality' | 'neighbourhood', required — Administrative level of a place in the Geonames hierarchy.
      - `place_id` string, required — Unique PredictHQ place identifier for this hierarchy entry

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/predicthq/apis/predicthq-events-api.md) · [All operations](https://skmtc.net/predicthq/apis/predicthq-events-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/predicthq/predicthq-events-api/revisions/66cd8ff349dd/schema)