# Overture Places API — Query POIs by Category, Brand, Country & Location

Source: https://www.overturemapsapi.com/docs/api-endpoints/places

> Query Overture Maps places (POIs) via a REST API. Filter by category, taxonomy, brand, country or lat/long radius, get contact details, and paginate whole countries.

# GET ./places

Allows you to get all the Places in the Overture Maps Database. You can filter by Lat/Long, Brand, Country and Categories.


## Query Parameters

Consult the [Open API documentation](/reference) for the full list of query parameters that can be used to filter the results. Here are some examples

### By Latitude / Longitude / Radius

Query params:
`lat`, `lng`, `radius`

Example Request to GET all the 'categories=cafe' within 2000m of Bondi Beach:


```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places?lat=-33.8910&lng=151.2769&radius=2000&categories=cafe' 
```

### Categories

e.g. `categories=water_park` - Comma separated string of Categories to filter

Example Request to GET all the Water Parks within 25km of Sydney

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=-33.8688' -d 'lng=151.2093' -d 'radius=25000' -d 'categories=water_park'
```

:::info Overture is retiring `categories` in September 2026
Overture replaces the places `categories` property with `basic_category` + `taxonomy` upstream in September 2026. **Nothing breaks in this API**: the `categories` response field and filter are staying (derived from the taxonomy once the upstream column is gone), and the `categories` filter already matches values from both vocabularies. Note the *values* inside `categories` will shift to the new taxonomy vocabulary at that point. If you match on specific category strings, we recommend the `taxonomy` filter below.
:::

### Taxonomy (hierarchy-aware)

`taxonomy` — comma-separated Overture taxonomy categories. Matches the primary category **or any ancestor in the taxonomy hierarchy**, so one value covers every descendant: `taxonomy=food_and_drink` matches every restaurant, café, bar and bakery.

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=40.7128' -d 'lng=-74.0060' -d 'radius=1500' -d 'taxonomy=food_and_drink'
```

Every place also returns its full taxonomy in the response:

```json
"taxonomy": {
  "primary": "coffee_shop",
  "hierarchy": ["food_and_drink", "non_alcoholic_beverage_venue", "coffee_shop"],
  "alternates": []
},
"basic_category": "coffee_shop"
```

### Operating Status

`operating_status` — filter by operating status, e.g. `open` or `permanently_closed`. Places without signals have a null status and are excluded when this filter is used. The field is also present on every place response.

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=51.5074' -d 'lng=-0.1278' -d 'radius=1000' -d 'operating_status=open'
```

### Brand Details (logos, websites) via Wikidata

`enrichment_fields=brand` — adds an `ext_brand` object to branded places with the brand's logo URL, official website, industry and parent organisation, sourced from Wikidata (CC0):

```json
"ext_brand": {
  "label": "Bank of America",
  "logo_url": "http://commons.wikimedia.org/wiki/Special:FilePath/Bank%20of%20America%20logo.svg",
  "website": "https://www.bankofamerica.com/",
  "industry": "financial sector"
}
```

Logo URLs are Wikimedia Commons links — append `?width=200` for a resized image. Present where Overture links the place's brand to a Wikidata QID (~1.5M places across ~3,000 chains).

### Contact details (websites, phones, emails, socials)

Every place returns its contact details **by default** — no special parameter is required:

```json
"websites": ["https://www.example-cafe.co.uk"],
"phones": ["+441234567890"],
"emails": ["hello@example-cafe.co.uk"],
"socials": ["https://www.facebook.com/examplecafe"]
```

:::tip These are returned by default
You do **not** need `enrichment_fields` for websites or phones. `enrichment_fields=brand` is only for the Wikidata brand layer (logos, industry, parent). The four contact arrays above are always in the response when Overture has them.
:::

Coverage varies by country and category. In well-mapped markets, websites and phones are populated for the large majority of businesses; emails and socials are sparser.

#### Filter to places that have contact details — `has_contact`

`has_contact` returns **only** places that already have at least one of the listed contact fields. It's comma-separated and matched with **OR**, which is ideal when you only want businesses you can actually reach or verify:

```bash
# only places with a website
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=51.5074' -d 'lng=-0.1278' -d 'radius=2000' -d 'categories=restaurant' -d 'has_contact=website'

# places with a website OR a social link (catches businesses that use a Facebook page instead of a site)
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=51.5074' -d 'lng=-0.1278' -d 'radius=2000' -d 'categories=restaurant' -d 'has_contact=website,social'
```

Allowed values: `website`, `phone`, `email`, `social`. The `Pagination-Count` header reflects the **filtered** total, so you can see how many places match before paging through them.

### Brands / Retail Chain

e.g. `brand_name=H&M` - The name of the Brand to filter by e.g. `Uniqlo`, `McDonalds`

Example Request to GET Uniqlo stores within 10km of New York City

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=40.7128' -d 'lng=-74.0060' -d 'radius=10000' -d 'brand_name=Uniqlo'
```

Example of a response for a 7-Eleven store near New York City:

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places'  \
-d 'lat=40.7128' -d 'lng=-74.0060' -d 'radius=10000' -d 'limit=1' -d 'brand_name=7-Eleven'
```

### By Name

`name` filters to places whose own name matches — an additional filter on top of your lat/lng/radius (or country) search, not a standalone text search. It's a case-insensitive exact match against the place's primary name (and any localized common name, where Overture has one):

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=40.785091' -d 'lng=-73.968285' -d 'radius=3000' -d 'name=Central Park'
```

Combine it with other filters as needed, e.g. `brand_name` to pin a chain down to one specific location by name.

### By Partial Name (type-ahead)

`name_prefix` finds places whose name starts with what someone has typed so far, or has a word that does. `blue bo` and `bottle` both match "Blue Bottle Coffee". It's case-insensitive and needs at least 2 characters.

With `lat`/`lng`, results come back nearest first, so a small `limit` gives you the closest few matches for a suggestions dropdown:

```bash
curl -H "x-api-key: DEMO-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places' \
-d 'lat=40.7128' -d 'lng=-74.0060' -d 'radius=5000' -d 'name_prefix=blue bo' -d 'limit=5'
```

Each call is a normal request and counts towards your monthly allowance, so debounce keystrokes (around 300 ms) and wait for 2 or 3 characters before searching. Responses typically take a second or two, so show a loading state.

### By Country

e.g. `?country=US` - The ISO 3166-1 alpha-2 country code to filter by. e.g. `US`, `GB`, `FR` (UK is GB).

Country-level queries (a `country` with no `lat`/`lng`) are available on [paid plans](/pricing) and must include a narrowing filter such as `categories`, `taxonomy`, `brand_name` or `name`. On the Free plan and with the demo key, search by `lat`, `lng` and `radius` (up to 25 km) instead; you can still add `country` alongside them as an extra filter. A Free key sending a country-level query gets a `403` explaining this. See [Usage limits](../limits).

Example Request to GET 10 restaurants in the US (paid plan):

```bash
curl -H "x-api-key: YOUR-API-KEY" -X GET -G 'https://api.overturemapsapi.com/places'  \
-d 'country=US' -d 'categories=restaurant' -d 'limit=10'
```

### Pagination

`limit` (page size) + `page` (0-indexed). Totals come back in the `Pagination-Count` / `Pagination-Page` / `Pagination-Limit` response headers.

[Find out more - Pagination](../pagination)

### Enriched Responses

e.g. Conflating with the OpenStreetMap equivalent

[Find out more - Enriched Data Options](../enriched-data)


## Parameter reference

Generated from the [OpenAPI spec](https://api.overturemapsapi.com/api-docs.json) (operation `searchPlaces`). Find points of interest near a point, or across a country on paid plans. Best query: `lat` + `lng` + `radius` (metres) with optional `categories`, `taxonomy`, `brand_name` or `name_prefix`. Country-level searches (`country` with no lat/lng) need a paid plan and a narrowing filter. Get valid category values from `GET /places/categories`. Page with `limit` and `page` and read the total from the `Pagination-Count` header. `enrichment_fields=brand` adds Wikidata brand details. The demo key is limited to small lat/lng searches.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `lat` | number |  | Latitude coordinate. Required if country code is not provided. |
| `lng` | number |  | Longitude coordinate. Required if country code is not provided. |
| `radius` | integer | `1000` | Search radius in meters, defaulting to 1000 meters if not provided. |
| `limit` | integer | `100` | Limit on the number of results returned, defaulting to 100 if not provided. Use `page` to paginate for more. |
| `page` | integer | `0` | Page number for pagination (0-indexed), used together with `limit` as the page size. Responses include Pagination-Count (total matching results), Pagination-Page and Pagination-Limit headers. Defaults to 0. |
| `format` | `json`, `csv`, `geojson` | `json` | Response format, defaulting to JSON. Options are "json", "csv", or "geojson". |
| `includes` | string |  | Array of fields to include in the properties field of the response, provided as a comma-separated string. Any fields not in the list will be excluded from the properties object. This is used to make the response lighter so your application is faster. |
| `country` | string |  | ISO 3166 country code consisting of 2 characters. Required if lat/lng are not provided. |
| `source` | string |  | Filter places to only those with a source dataset matching this value. |
| `brand_wikidata` | string |  | Wikidata brand ID associated with the place. |
| `brand_name` | string |  | Brand name associated with the place. |
| `name` | string |  | Filter by the place's own name — an additional filter on top of lat/lng/radius (or country) search, not a standalone text search. Case-insensitive exact match against names.primary or any localized value in names.common. |
| `name_prefix` | string |  | Partial-name search for type-ahead: matches places whose primary name starts with this text, or has a word that does (so "blue bo" and "bottle" both match "Blue Bottle Coffee"). Case-insensitive, at least 2 characters. Combine with lat/lng/radius and a small limit: results come nearest first. |
| `min_confidence` | number | `0.5` | Minimum confidence score for the places to be returned, defaulting to 0.5 if not provided. |
| `categories` | string |  | Array of category names, provided as a comma-separated string. Matches the legacy Overture categories vocabulary and the newer taxonomy/basic_category vocabulary. |
| `taxonomy` | string |  | Array of Overture taxonomy categories, provided as a comma-separated string. Matches the primary category or any ancestor in the taxonomy hierarchy, so e.g. "food_and_drink" matches every descendant category. |
| `operating_status` | string |  | Filter by operating status, e.g. "open" or "permanently_closed". Places without signals have a null operating status and are excluded when this filter is used. |
| `enrichment_fields` | string |  | Comma-separated list of enrichment fields to include. Use "brand" for Wikidata-sourced brand details (logo, website, industry, parent) on branded places. |
| `has_contact` | string |  | Return only places that already have at least one of the listed contact fields. Comma-separated, matched with OR: e.g. "website" returns places with a website; "website,social" returns places with a website OR a social link. Useful for filtering to businesses you can verify. Allowed values: website, phone, email, social. |

## Python example

```python
import requests

resp = requests.get(
    "https://api.overturemapsapi.com/places",
    headers={"x-api-key": "DEMO-API-KEY"},  # use your own key outside the demo cities
    params={
        "lat": 51.5138,
        "lng": -0.0984,
        "radius": 500,
        "categories": "cafe",
        "limit": 10,
    },
    timeout=30,
)
if resp.status_code == 429:
    raise SystemExit(f"Rate limited, retry in {resp.headers['Retry-After']}s")
resp.raise_for_status()  # 4xx bodies are {"statusCode", "message"}; the message says how to fix the request

results = resp.json()
print(resp.headers.get("Pagination-Count"), "results in total")
for place in results:
    print(place["properties"]["names"]["primary"], place["properties"].get("categories", {}).get("primary"))
```

Results are paginated: pass `page` (0-indexed) and `limit`, and read the total from the `Pagination-Count` header. See [Pagination](/docs/pagination) and [Usage limits](/docs/limits).