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.

Request

HTTP Request

GET https://api.predicthq.com/v1/places/hierarchies/

Query Parameters

Parameter	Description
country string	An ISO 3166-1 alpha-2 country code. E.g. ?country=US
location.origin coordinate	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
location.place_id string	A 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
level string	A place level. Possible values: neighbourhood locality localadmin county region country continent planet Defaults to locality. E.g. ?level=county

Response

Example response

Below is an example response:

{
    "place_hierarchies": [
        [
            {
                "type": "planet",
                "place_id": "6295630"
            },
            {
                "type": "continent",
                "place_id": "6255149"
            },
            {
                "type": "country",
                "place_id": "6252001"
            },
            {
                "type": "region",
                "place_id": "5815135"
            },
            {
                "type": "county",
                "place_id": "5799783"
            },
            {
                "type": "locality",
                "place_id": "5786882"
            }
        ],
        [
            {
                "type": "planet",
                "place_id": "6295630"
            },
            {
                "type": "continent",
                "place_id": "6255149"
            },
            {
                "type": "country",
                "place_id": "6252001"
            },
            {
                "type": "region",
                "place_id": "5815135"
            },
            {
                "type": "county",
                "place_id": "5799783"
            },
            {
                "type": "locality",
                "place_id": "5809844"
            }
        ]
    ]
}

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 $ACCESS_TOKEN"

python

import requests

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

print(response.json())

Guides

Below are some guides relevant to this API:

• Understanding Place Hierarchies