Get place hierarchies

Get the list of hierarchies for a Place.

This endpoint is in Beta.

The currently available filters and response data change are subject to change.

This endpoint allows you to get the full place hierarchies for

• a given coordinate
• list of place_id.

A place hierarchy is a list of place identifiers and types from the planet level down to the level specified in your query (please note that level defaults to locality if not specified in your query).

The response might include more than one hierarchy for a given coordinate. The reason for this is that we try to match the closest place's hierarchy but we also include the closest major city's hierarchy within a radius of 50km. This only applies if the level is below region and, if it exists, the major city's hierarchy will always be the second item in the list.

For instance, if you specify ?location.origin=47.615337,-122.203981, which is a coordinate located in Bellevue, Washington, you'll get two hierarchies, one for Bellevue but also one for Seattle.

Get Place Hierarchies

get

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.

Authorizations

AuthorizationstringRequired

Enter your PredictHQ API key. The Bearer prefix is added automatically.

When calling the API directly, send: Authorization: Bearer <YOUR_API_KEY> as documented at https://docs.predicthq.com/api/overview/authenticating

Query parameters

location.place_idstring[]Optional

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

countrystring[]Optional

An ISO 3166-1 alpha-2 country code.

E.g. ?country=US

levelstring · enumOptional

Administrative level of a place in the Geonames hierarchy.

Possible values:

location.originstringOptional

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

offsetintegerOptional

Zero-based index of the first result to return.

Default: 0

limitinteger · min: 1 · max: 10000Optional

Maximum number of results to return per page.

Default: 10

Responses

200

Successful Response

application/json

countintegerRequired

Total number of hierarchy chains matching the query

nextstring · nullableOptional

URL to next page

previousstring · nullableOptional

URL to previous page

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

get/v1/places/hierarchies

GET /v1/places/hierarchies HTTP/1.1
Host: api.predicthq.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1,
  "next": "text",
  "previous": "text",
  "place_hierarchies": [
    [
      {
        "type": "planet",
        "place_id": "text"
      }
    ]
  ]
}

Examples

curl

curl -X GET "https://api.predicthq.com/v1/places/hierarchies/?location.origin=47.615337,-122.203981" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $API_TOKEN"

python

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/places/hierarchies/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "location.place_id": "5809844,6252001"
    }
)

print(response.json())

OpenAPI Spec

The OpenAPI spec for Places API can be found here.

Guides

Below are some guides relevant to this API:

• Understanding place hierarchies