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

Search for places by text query, country, geographic coordinates, or place IDs.

At least one of q, country, location, or id must be provided — otherwise a 400 is returned.

Filtering:

• q — free-text search on place name.
• country — comma-separated ISO 3166-1 alpha-2 country codes.
• location — coordinates in lat,lon or @lat,lon format. Lat must be between −90 and 90, lon between −180 and 180.
• id — comma-separated place IDs. When id is the only filter and no pagination parameters are set, an optimised multi-get is used instead of a search query.
• type — comma-separated place types. Accepts admin level values as well as aliases (e.g. local expands to neighbourhood, locality, and localadmin).

Results are paginated with offset and limit.

Authorizations

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

Zero-based index of the first result to return.

Default: 0

limitinteger · min: 1 · max: 10000Optional

Maximum number of results to return per page.

Default: 10

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. ?location=@40.66677,-73.88236

qstringOptional

A full-text search query.

E.g. ?q=New+York

Responses

200

Successful Response

application/json

countintegerRequired

Total number of places matching the query

nextstring · nullableOptional

URL to next page

previousstring · nullableOptional

URL to previous page

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

get/v1/places

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

python

import requests

response = requests.get(
    url="https://api.predicthq.com/v1/places/",
    headers={
      "Authorization": "Bearer $API_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