Places API

# Places API

Quickstart, parameters, layer selection, examples, and OpenAPI contract for the Open Places API.

Quickstart

## Search places near a coordinate.

Open Places API has one public search endpoint: `GET /v1/places`. Send the API key from your backend, include a location scope, and keep browser frontends away from the secret. Use `q` for text search, or use `category` to list places in a category in an area, up to the first 1,000 places per query area. 

cURL GET /v1/places 

```
curl -G "https://api.openplacesapi.com/v1/places" \
  --data-urlencode "q=coffee" \
  --data-urlencode "lat=40.7128" \
  --data-urlencode "lon=-74.0060" \
  --data-urlencode "radius_mi=25" \
  --data-urlencode "limit=10" \
  --data-urlencode "min_confidence=0.85" \
  -H "Authorization: Bearer $OPEN_PLACES_API_KEY"
```

cURL category browse 

```
curl -G "https://api.openplacesapi.com/v1/places" \
  --data-urlencode "category=cafe" \
  --data-urlencode "lat=40.7128" \
  --data-urlencode "lon=-74.0060" \
  --data-urlencode "radius_mi=25" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0" \
  -H "Authorization: Bearer $OPEN_PLACES_API_KEY"
```

Endpoint

## One route, scoped by radius.

GET `/v1/places` 

Returns Overture-backed place results, optionally merged with community and account-owned layers.

| Parameter       | Required | Use                                                                                                                                                                                          |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q               | Usually  | Search text. Required unless category is supplied. A q that names a kind of place, such as pharmacy, also searches that category; see [category words in q](/docs/reference#category-words). |
| category        | No       | Exact Overture category string such as cafe. When supplied, q becomes optional.                                                                                                              |
| lat, lon        | Yes      | Latitude and longitude for the search center.                                                                                                                                                |
| radius\_mi      | No       | Search radius in miles. Defaults to 25; maximum is 50.                                                                                                                                       |
| mode            | No       | Search mode: all, name, or address. Defaults to all. Use name to match place names literally, without reading category words in q.                                                           |
| limit           | No       | Number of results to return. Defaults to 10; text search max 20, category browse max 50.                                                                                                     |
| offset          | No       | Category-browse pagination offset. offset + limit can be at most 1000; follow meta.next\_offset until it is null. Each page counts as one search.                                            |
| min\_confidence | No       | Minimum Overture confidence score from 0 to 1. No default filter is applied.                                                                                                                 |
| sort            | No       | relevance (default) or distance, which returns the same matches nearest first.                                                                                                               |
| layers          | No       | Explicit ordered layer stack, for example base,open,account:client-a.                                                                                                                        |
| layer\_preset   | No       | Saved account preset. Mutually exclusive with layers.                                                                                                                                        |

Server examples

## Keep API keys on your backend.

```
const apiKey = process.env.OPEN_PLACES_API_KEY;

if (!apiKey) throw new Error("OPEN_PLACES_API_KEY is required");

const url = new URL("https://api.openplacesapi.com/v1/places");
url.search = new URLSearchParams({
  q: "ramen",
  lat: "35.6762",
  lon: "139.6503",
  radius_mi: "25",
  mode: "all",
  min_confidence: "0.85",
}).toString();

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await response.json();
```

```
import os
import requests

response = requests.get(
    "https://api.openplacesapi.com/v1/places",
    params={
        "q": "coffee",
        "lat": 40.7128,
        "lon": -74.0060,
        "radius_mi": 25,
        "limit": 10,
        "min_confidence": 0.85,
    },
    headers={"Authorization": f"Bearer {os.environ['OPEN_PLACES_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
data = response.json()
```

Next steps

## Choose the detail you need.

[ **Layer selection** Control base, community, and account-owned records. ](/docs/layers) [ **Errors and quota** Handle validation, auth, quota, coverage, and rate limits. ](/docs/errors) [ **API reference** Review parameters, responses, headers, and the OpenAPI contract. ](/docs/reference) [ **Data quality** Understand confidence scores, filtering, missing fields, and coordinate caveats. ](/data-quality-confidence) [ **Data rights** Review cache, storage, redistribution, and open-license positioning. ](/data-rights)