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.

Properties

Property

Description

id string read-only

The unique identifier of the place.

E.g. 5115985

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

name string read-only

The name of the place.

E.g. East New York

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

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

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

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]


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

limit number

The maximum number of results to return. The default limit is 10, and maximum 200.

E.g. ?limit=10

q string

A full-text search query.

E.g. ?q=New+York

id string

A comma-separated list of place identifiers.

E.g. ?id=5115985

country sring

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

E.g. ?country=US

location centroid

A centroid in the form @{latitude},{longitude},

E.g. ?location=@40.66677,-73.88236

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