Search Places

Search for a Place.

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

get

Authorizations

BearerAuth

Query parameters

offsetintegerOptional

limitinteger · min: 1Optional

idstring[]Optional

A comma-separated list of place identifiers.

E.g. ?id=5115985

countrystring[]Optional

A comma-separated list of ISO 3166-1 alpha-2 country code.

E.g. ?country=US

locationstringOptional

lat,lon

qstringOptional

A full-text search query.

E.g. ?q=New+York

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

HTTPcURLJavaScriptPython

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "text",
      "type": "planet",
      "name": "text",
      "county": "text",
      "region": "text",
      "country": "text",
      "country_alpha2": "text",
      "country_alpha3": "text",
      "location": [
        1
      ]
    }
  ]
}

Examples

curl

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

python

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())

OpenAPI Spec

The OpenAPI spec for Places API can be found here.

Guides

Below are some guides relevant to this API:

• Understanding Place Hierarchies

• Find Events by Place ID

• Find Broadcasts by County Place ID