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

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

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

A coordinate in the form @{latitude},{longitude}.

E.g. [email protected],-73.88236

qstringOptional

A full-text search query.

E.g. ?q=New+York

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/v1/places

HTTPcURLJavaScriptPython

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

{
  "count": 1,
  "next": "text",
  "previous": "text",
  "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

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