Places

The Places API gives you a read-only interface to PredictHQ's places data. A place represents a Geonames Feature, which can be either an Area, an Administrative Feature, or a Populated Place.

Places can be used to search and filter events using named geographic features rather than a radius, latitude and longitude (see events' place.scope and place.exact parameters). This is helpful when searching for all events that apply to a continent, country, state, region, province, county or city.

Search Places

Use the below parameters to search and filter all places. Places are sorted by relevance (location or text query proximity).

A search requires at least one of the qidcountry or location parameters.

Parameters

Parameter Description
country
string
A comma-separated list of ISO 3166-1 alpha-2 country codes.

E.g. ?country=US
id
string
A comma-separated list of place identifiers.

E.g. ?id=5115985
limit
number
The maximum number of results to return. The default limit is 10.

E.g. ?limit=10
location
coordinate
A coordinate in the form @{latitude},{longitude}.

E.g. ?location=@40.66677,-73.88236
q
string
A full-text search query.

E.g. ?q=New+York
type
string
A comma-separated list of place types.

Possible values:
  • neighbourhood
  • locality
  • localadmin
  • county
  • region
  • country
  • continent
  • planet
Supports extra types:
  • local: synonym for neighbourhood,locality,localadmin
  • metro: metropolitan areas
  • major: major cities
E.g. ?type=country

Action

GET /v1/places/

Example

curl -X GET https://api.predicthq.com/v1/places/?q=New+York&limit=5 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "5128638",
      "type": "region",
      "name": "New York",
      "county": null,
      "region": "New York",
      "country": "United States",
      "country_alpha2": "US",
      "country_alpha3": "USA",
      "location": [
        -75.4999,
        43.00035
      ]
    },
    {
      "id": "5128594",
      "type": "county",
      "name": "New York County",
      "county": "New York County",
      "region": "New York",
      "country": "United States",
      "country_alpha2": "US",
      "country_alpha3": "USA",
      "location": [
        -73.96981,
        40.77427
      ]
    },
    {
      "id": "5115985",
      "type": "neighbourhood",
      "name": "East New York",
      "county": "Kings County",
      "region": "New York",
      "country": "United States",
      "country_alpha2": "US",
      "country_alpha3": "USA",
      "location": [
        -73.88236,
        40.66677
      ]
    },
    {
      "id": "5106292",
      "type": "locality",
      "name": "West New York",
      "county": "Hudson County",
      "region": "New Jersey",
      "country": "United States",
      "country_alpha2": "US",
      "country_alpha3": "USA",
      "location": [
        -74.01431,
        40.78788
      ]
    }
  ]
}

Fields

Below are the fields returned by the Places endpoint. Please note that these are not the fields used for filtering - please refer to the Search Places section to discover which parameters can be used for filtering places.

JSON Schemas are available for the Places endpoint and for a single place:

Field Description
country
string
read-only
The name of the place's administrative level 0 place, or null if it does not apply.

E.g. United States
country_alpha2
string
read-only
The ISO 3166-1 alpha-2 country code, or null if there is no country.

E.g. US
country_alpha3
string
read-only
The ISO 3166-1 alpha-3 country code, or null if there is no country.

E.g. USA
county
string
read-only
The name of the place's administrative level 2 place, or null if it does not apply.

E.g. Kings County
id
string
read-only
The unique identifier of the place.

E.g. 5115985
location
array
read-only
A 2-tuple representing the centroid of the place. Note that the longitude/latitude coordinates use the GeoJSON order [lon, lat].

E.g. [-73.88236, 40.66677]
name
string
read-only
The name of the place.

E.g. East New York
region
string
read-only
The name of the place's administrative level 1 place, or null if it does not apply.

E.g. New York
type
string
read-only
The administrative level of the place.

Possible values:
  • neighbourhood: subdivision of a populated place
  • locality: populated place
  • localadmin: administrative level 3
  • county: administrative level 2
  • region: administrative level 1
  • country: administrative level 0
  • continent: Africa, North America, South America, Antarctica, Asia, Europe, Oceania
  • planet: Earth is the only supported planet at the moment, but we will work hard to support more planets as relevant events become available!
E.g. locality

Retrieve Places Hierarchies

Beta Endpoint

The Places Hierarchies endpoint is currently 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).

Retrieve by coordinates

Multiple hierarchies

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.

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 this parameter is required.
E.g. ?location.origin=47.615337,-122.203981
level
string
A place level.

Possible values:
  • neighbourhood
  • locality
  • localadmin
  • county
  • region
  • country
  • continent
  • planet
Defaults to locality.

E.g. ?level=county

Action

GET /v1/places/hierarchies/?location.origin=47.615337,-122.203981

Example

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"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "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"
            }
        ]
    ]
}

Retrieve by place_id

Default arguments

Retrieving hierarchies by place_id does not accept a country or level parameter.

Parameters

Parameter Description
location.place_id
Array of strings
A list of place_id in the form {place_id1},{place_id2},....

Please note that this parameter is required.

E.g. ?location.place_id=5809844,6252001

Action

GET /v1/places/hierarchies/?location.place_id=5809844,6252001

Example

curl -X GET https://api.predicthq.com/v1/places/hierarchies/?location.place_id=5809844,6252001 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json

{
    "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": "5809844"
            }
        ],
        [
            {
                "type": "planet",
                "place_id": "6295630"
            },
            {
                "type": "continent",
                "place_id": "6255149"
            },
            {
                "type": "country",
                "place_id": "6252001"
            }
        ]
    ]
}