---
title: "Search Places"
method: GET
path: "/v1/places"
tags: ["Places"]
---

# Search Places

`GET /v1/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`.

## Query parameters

- `offset` integer
- `limit` integer
- `id` string[]
- `country` string[]
- `location` string
- `q` string
- `type` string[]

## Response `200`

Successful Response

- PublicGeonamesPlacesResponse
  - `count` integer, required — Total number of places matching the query
  - `next` string, nullable — URL to next page
  - `previous` string, nullable — URL to previous page
  - `results` PublicGeonamesPlaceResponse[], required — Array of place objects for the current page
    - `id` string, required — The unique identifier of the place. E.g. `5115985`
    - `type` 'planet' | 'continent' | 'country' | 'region' | 'county' | 'localadmin' | 'locality' | 'neighbourhood', required — Administrative level of a place in the Geonames hierarchy.
    - `name` string, required — The name of the place. E.g. `East New York`
    - `county` string — The name of the place's administrative level 2 place, or `null` if it does not apply. E.g. `Kings County`
    - `region` string — The name of the place's administrative level 1 place, or `null` if it does not apply. E.g. `East New York`
    - `country` string — The name of the place's administrative level 0 place, or `null` if it does not apply. E.g. `United States`
    - `country_alpha2` string — The ISO 3166-1 alpha-2 country code, or `null` if there is no country. E.g. `US`
    - `country_alpha3` string — The ISO 3166-1 alpha-3 country code, or `null` if there is no country. E.g. `USA`
    - `location` number[], required — A 2-tuple representing the centroid of the place. Note that the longitude/latitude coordinates use the [GeoJSON](http://geojson.org/) order `[lon, lat]`. E.g. `[-73.88236, 40.66677]`

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/predicthq/apis/predicthq-events-api.md) · [All operations](https://skmtc.net/predicthq/apis/predicthq-events-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/predicthq/predicthq-events-api/revisions/66cd8ff349dd/schema)