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

Authorizations

BearerAuth

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

A place level.

Defaults to locality.

E.g. ?level=county

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

limitinteger · min: 1Optional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/v1/places/hierarchies

HTTPcURLJavaScriptPython

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

python

OpenAPI Spec

The OpenAPI spec for Places API can be found here.

Guides

Below are some guides relevant to this API:

• Understanding Place Hierarchies