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
Place Fields

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 q, id, country 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 centroid	A centroid 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

GET /v1/places/?q=New+York&limit=5 HTTP/1.1
Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/places/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
        "q": "New York",
        "limit": 5
    }
)

print(response.json())

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. E.g. `US`
country_alpha3 string read-only	The ISO 3166-1 alpha-3 country code. 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`

Technical Documentation

Help

Places

Search Places

Parameters

Fields