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.

Request

HTTP Request

GET https://api.predicthq.com/v1/places/

Query Parameters

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.

Parameter Description

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`

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

Response

Response Fields

Field Description

Field	Description
`country` string	The name of the place's administrative level 0 place, or `null` if it does not apply. E.g. `United States`
`country_alpha2` string	The ISO 3166-1 alpha-2 country code, or `null` if there is no country. E.g. `US`
`country_alpha3` string	The ISO 3166-1 alpha-3 country code, or `null` if there is no country. E.g. `USA`
`county` string	The name of the place's administrative level 2 place, or `null` if it does not apply. E.g. `Kings County`
`id` string	The unique identifier of the place. E.g. `5115985`
`location` array	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	The name of the place. E.g. `East New York`
`region` string	The name of the place's administrative level 1 place, or `null` if it does not apply. E.g. `New York`
`type` string	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`

country string

The name of the place's administrative level 0 place, or null if it does not apply. E.g. United States

country_alpha2 string

The ISO 3166-1 alpha-2 country code, or null if there is no country. E.g. US

country_alpha3 string

The ISO 3166-1 alpha-3 country code, or null if there is no country. E.g. USA

county string

The name of the place's administrative level 2 place, or null if it does not apply. E.g. Kings County

id string

The unique identifier of the place. E.g. 5115985

location array

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

The name of the place. E.g. East New York

region string

The name of the place's administrative level 1 place, or null if it does not apply. E.g. New York

type string

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

Example response

Below is an example response:

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

Examples

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

Guides

Below are some guides relevant to this API:

PreviousPlaces NextGet Place Hierarchies

Last updated 9 months ago