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 codes. E.g. |
id string |
A comma-separated list of place identifiers. E.g. |
limit number |
The maximum number of results to return. The default limit is E.g. |
location coordinate |
A coordinate in the form E.g. |
q string |
A full-text search query. E.g. |
type string |
A comma-separated list of place types. Possible values:
Supports extra types:
E.g. |
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.
JSON Schemas are available for the Places endpoint and for a single place:
Field |
Description |
---|---|
country string read-only |
The name of the place's administrative level 0 place, or E.g. |
country_alpha2 string read-only |
The ISO 3166-1 alpha-2 country code, or E.g. |
country_alpha3 string read-only |
The ISO 3166-1 alpha-3 country code, or E.g. |
county string read-only |
The name of the place's administrative level 2 place, or E.g. |
id string read-only |
The unique identifier of the place. E.g. |
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. |
name string read-only |
The name of the place. E.g. |
region string read-only |
The name of the place's administrative level 1 place, or E.g. |
type string read-only |
The administrative level of the place. Possible values:
E.g. |
Retrieve Places Hierarchies
This endpoint returns the full place hierarchies for a given coordinate. A place hierarchy is a list of place identifiers from the planet
level down to the level
specified in your query (please note that level
defaults to locality
if not specified in your query).
Multiple hierarchies
The response might include more than one hierarchy for a given coordinate. The reason for this is that we try to match the closest place's hierarchy but we also include the closest major city's hierarchy within a radius of 50km. This only applies if the level
is below region
and, if it exists, the major city's hierarchy will always be the second item in the list.
For instance, if you specify ?location.origin=47.615337,-122.203981
, which is a coordinate located in Bellevue, Washington, you'll get two hierarchies, one for Bellevue but also one for Seattle.
Parameters
Parameter |
Description |
---|---|
country string |
An ISO 3166-1 alpha-2 country code. E.g. |
location.origin coordinate |
A coordinate in the form Please note that this parameter is required. E.g. |
level string |
A place level. Possible values:
Defaults to E.g. |