# Search Places

The Places API gives you a read-only interface to PredictHQ's places data. A place represents a [Geonames](http://www.geonames.org/) 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

> 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\`.

```json
{"openapi":"3.1.0","info":{"title":"PredictHQ Places API","version":"1.0.0"},"tags":[{"name":"Places"}],"servers":[{"url":"https://api.predicthq.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"$API_KEY","description":"Enter your PredictHQ API key. The Bearer prefix is added automatically.\n\nWhen calling the API directly, send: `Authorization: Bearer <YOUR_API_KEY>` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"parameters":{"OffsetParam":{"name":"offset","in":"query","description":"Zero-based index of the first result to return.","required":false,"schema":{"type":"integer","default":0,"minimum":0}},"LimitParam":{"name":"limit","in":"query","description":"Maximum number of results to return per page.","required":false,"schema":{"type":"integer","default":10,"maximum":10000,"minimum":1}}},"schemas":{"PublicGeonamesPlacesResponse":{"type":"object","properties":{"count":{"description":"Total number of places matching the query","type":"integer","title":"Count"},"next":{"description":"URL to next page","anyOf":[{"type":"string"},{"type":"null"}]},"previous":{"description":"URL to previous page","anyOf":[{"type":"string"},{"type":"null"}]},"results":{"description":"Array of place objects for the current page","type":"array","items":{"$ref":"#/components/schemas/PublicGeonamesPlaceResponse"},"title":"Results"}},"required":["count","results"],"title":"PublicGeonamesPlacesResponse"},"PublicGeonamesPlaceResponse":{"type":"object","properties":{"id":{"description":"The unique identifier of the place.\n\n\nE.g. `5115985`","type":"string","title":"Id"},"type":{"description":"The administrative level of the place.\n\n\nE.g. `locality`","$ref":"#/components/schemas/BaseLevel"},"name":{"description":"The name of the place.\n\n\nE.g. `East New York`","type":"string","title":"Name"},"county":{"description":"The name of the place's administrative level 2 place, or `null` if it does not apply.\n\n\nE.g. `Kings County`","type":"string","title":"County"},"region":{"description":"The name of the place's administrative level 1 place, or `null` if it does not apply.\n\n\nE.g. `East New York`","type":"string","title":"Region"},"country":{"description":"The name of the place's administrative level 0 place, or `null` if it does not apply.\n\n\nE.g. `United States`","type":"string","title":"Country"},"country_alpha2":{"description":"The ISO 3166-1 alpha-2 country code, or `null` if there is no country.\n\n\nE.g. `US`","type":"string","title":"Country Alpha2"},"country_alpha3":{"description":"The ISO 3166-1 alpha-3 country code, or `null` if there is no country.\n\n\nE.g. `USA`","type":"string","title":"Country Alpha3"},"location":{"description":"A 2-tuple representing the centroid of the place.\n\nNote that the longitude/latitude coordinates use the [GeoJSON](http://geojson.org/) order `[lon, lat]`.\n\n\nE.g. `[-73.88236, 40.66677]`","type":"array","items":{"type":"number"},"maxItems":2,"minItems":2,"title":"Location"}},"required":["id","type","name","location"],"title":"PublicGeonamesPlaceResponse"},"BaseLevel":{"description":"Administrative level of a place in the Geonames hierarchy.","type":"string","enum":["planet","continent","country","region","county","localadmin","locality","neighbourhood"],"title":"BaseLevel"},"ErrorResponse":{"type":"object","properties":{"error":{"description":"Error message","type":"string","title":"Error"}},"required":["error"],"title":"ErrorResponse"},"HTTPValidationError":{"type":"object","properties":{"error":{"description":"Error summary message","type":"string","title":"Error"},"details":{"description":"List of validation error details","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Details"}},"required":["error","details"],"title":"HTTPValidationError"},"ValidationErrorDetail":{"type":"object","properties":{"field":{"description":"The field that failed validation","type":"string","title":"Field"},"msg":{"description":"The validation error message","type":"string","title":"Message"},"type":{"description":"The type of validation error","type":"string","title":"Error Type"}},"required":["field","msg","type"],"title":"ValidationErrorDetail"},"QueryValidationError":{"type":"object","properties":{"error":{"description":"List of query parameter validation errors","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"title":"Error"}},"required":["error"],"title":"QueryValidationError"}}},"paths":{"/v1/places":{"get":{"operationId":"list_places","summary":"Search Places","description":"Search for places by text query, country, geographic coordinates, or place IDs.\n\nAt least one of `q`, `country`, `location`, or `id` must be provided — otherwise\na `400` is returned.\n\n**Filtering:**\n- `q` — free-text search on place name.\n- `country` — comma-separated ISO 3166-1 alpha-2 country codes.\n- `location` — coordinates in `lat,lon` or `@lat,lon` format.\n  Lat must be between −90 and 90, lon between −180 and 180.\n- `id` — comma-separated place IDs. When `id` is the only filter and no pagination\n  parameters are set, an optimised multi-get is used instead of a search query.\n- `type` — comma-separated place types. Accepts admin level values as well as aliases\n  (e.g. `local` expands to `neighbourhood`, `locality`, and `localadmin`).\n\nResults are paginated with `offset` and `limit`.","parameters":[{"$ref":"#/components/parameters/OffsetParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"id","in":"query","description":"A comma-separated list of place identifiers.\n\n\nE.g. `?id=5115985`","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Id"},"explode":false,"style":"form"},{"name":"country","in":"query","description":"A comma-separated list of [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.\n\n\nE.g. `?country=US`","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Country"},"explode":false,"style":"form"},{"name":"location","in":"query","description":"A coordinate in the form `@{latitude},{longitude}`.\n\n\nE.g. `?location=@40.66677,-73.88236`","required":false,"schema":{"type":"string","title":"Location"},"explode":false,"style":"form"},{"name":"q","in":"query","description":"A full-text search query.\n\n\nE.g. `?q=New+York`","required":false,"schema":{"type":"string","title":"Q"}},{"name":"type","in":"query","description":"Comma-separated list of place types to filter results. Accepts administrative levels and aliases.\n\n- `planet` — Earth (top level)\n- `continent` — Continent (e.g. North America, Europe)\n- `country` — Sovereign nation\n- `region` — Administrative level 1 (e.g. US state, Australian state)\n- `county` — Administrative level 2 (e.g. US county)\n- `localadmin` — Local administrative area (e.g. a municipality)\n- `locality` — Populated place (e.g. a city or town)\n- `neighbourhood` — Subdivision of a locality\n- `major` — Major populated place\n- `metro` — Metropolitan area\n- `local` — Alias expanding to `neighbourhood`, `locality`, and `localadmin` combined","required":false,"schema":{"type":"array","items":{"type":"string","enum":["planet","continent","country","region","county","localadmin","locality","neighbourhood","major","metro","local"]},"title":"Type"},"explode":false,"style":"form"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicGeonamesPlacesResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/HTTPValidationError"},{"$ref":"#/components/schemas/QueryValidationError"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Places"]}}}}
```

## Examples

{% tabs %}
{% tab title="curl" %}

```bash
curl -X GET "https://api.predicthq.com/v1/places/?q=New+York&limit=5" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
```

{% endtab %}

{% tab title="python" %}

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

{% endtab %}
{% endtabs %}

## OpenAPI Spec

The OpenAPI spec for Places API can be [found here](https://api.predicthq.com/docs/?urls.primaryName=Places+API).

## Guides

Below are some guides relevant to this API:

* [Understanding Place Hierarchies](/getting-started/guides/geolocation-guides/understanding-place-hierarchies.md)
* [Find Events by Place ID](/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-place-id.md)
* [Find Broadcasts by County Place ID](/getting-started/guides/live-tv-event-guides/find-broadcasts-by-county-place-id.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.predicthq.com/api/places/search-places.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.