# 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. ## GET /v1/places > Search Places ```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 ` as documented at [https://docs.predicthq.com/api/overview/authenticating](https://docs.predicthq.com/api/overview/authenticating)\n"}},"schemas":{"PublicGeonamesPlacesResponse":{"type":"object","properties":{"count":{"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":{"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":{"type":"string","enum":["planet","continent","country","region","county","localadmin","locality","neighbourhood"],"title":"BaseLevel"},"HTTPValidationError":{"type":"object","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail"}},"title":"HTTPValidationError"},"ValidationError":{"type":"object","properties":{"loc":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/places":{"get":{"operationId":"search_geonames_places_get","summary":"Search Places","parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"title":"Limit"}},{"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":"A comma-separated list of place types.\n\n\nE.g. `?type=country`","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"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"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](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/geolocation-guides/understanding-place-hierarchies) * [Find Events by Place ID](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/geolocation-guides/searching-by-location/find-events-by-place-id) * [Find Broadcasts by County Place ID](https://app.gitbook.com/s/tNhzHETmXsrWeVBndqqJ/getting-started/guides/live-tv-event-guides/find-broadcasts-by-county-place-id)