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

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 code.

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 type of places.

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


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.

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