---
name: open-places-search
description: Open Places API is a place search API for AI agents and developers, on open Overture data, over MCP and REST, with flat plans and results you can keep.
---

# Open Places search

Use Open Places API when a task needs nearby place search or a category listing around known coordinates.

## Scope

- Supported: proximity search and category area listing around a latitude and longitude.
- Not supported: street-address geocoding, address autocomplete, routes, directions, or map tiles.
- Results may include names, coordinates, distances, categories, structured addresses, confidence, phone, website, and operating status when present.

## Hosted MCP server

Endpoint: https://app.openplacesapi.com/mcp

Transport: Streamable HTTP

Authentication: send an Open Places API key as an Authorization bearer token. Follow https://openplacesapi.com/auth.md and never place a key in a public file, log, or prompt.

Tool: `search_places`

- `q`: search text such as `pharmacy`, `ramen`, or `hardware store`; optional when `category` is set. A `q` that names a kind of place also searches that category unless `mode=name` or `category` is set
- `category`: optional exact Overture category slug such as `pharmacy` or `coffee_shop`; a parent such as `food_and_drink` matches its subcategories. Supply `q`, `category`, or both
- `lat` and `lon`: search centre coordinates
- `radius_mi`: optional radius up to 50 miles; default 25
- `limit`: optional result count from 1 to 20, or 1 to 50 with `category`; default 10
- `offset`: optional category-browse page offset; only with `category`. `offset + limit` must be at most 1000. Use `meta.next_offset` for the next page; it is null on the last page
- `min_confidence`: optional Overture confidence floor from 0 to 1
- `sort`: optional `relevance` (default) or `distance`; `distance` returns the same matches nearest first
- `mode`: optional `name`, `address`, or `all` (default); `name` matches names literally, without category interpretation

Tool: `list_categories`

- `q`: optional words or a guessed slug, up to 64 characters; returns the best-matching category slugs with label, parent, and hierarchy
- `limit`: optional match count from 1 to 100
- Without `q`, returns a compact overview of the top-level groups and their direct subcategories

## HTTP API

Endpoint: `GET https://api.openplacesapi.com/v1/places`

Example:

```http
GET https://api.openplacesapi.com/v1/places?q=coffee&lat=40.7128&lon=-74.0060&limit=10
Authorization: Bearer opa_live_...
```

Category lookup: `GET https://api.openplacesapi.com/v1/categories?q=<text>` (no API key, not billed).

OpenAPI contract: https://openplacesapi.com/openapi.yaml

## Agent behaviour

- Ask for or derive a search centre before calling the tool; do not guess precise coordinates without telling the user.
- Preserve uncertainty and source fields in returned place data.
- Read `meta.interpreted_as` to see whether `q` was read as a category, and each result's `match` (`name`, `address`, `category`, or `name_and_category`) to see why it was returned. Use `mode=name` when the user means a literal business name.
- Find category slugs with `list_categories` or `GET /v1/categories` instead of guessing.
- On empty results, read `meta.warnings`: `unknown_category` lists `suggestions` to retry with; `no_results_within_radius` includes `nearest_match` (public `id`, `name`, `distance_mi`, and locality/country when available) when the bounded 100-mile lookup finds a place. That place stays outside `results`; the message names the `radius_mi` to retry with, or says the closest match is beyond the 50 mile maximum and the search should start closer to it. `query_relaxed` means `q` had no exact matches and the results are for a relaxed form of `q`; confirm they are what the user meant.
- Errors include `code`, `message`, field-level `details`, and a `docs_url` explaining the code. Fix `validation_error` inputs before retrying, and wait `Retry-After` seconds on `rate_limited` or 503 errors.
- Stop and report quota or authentication errors; do not retry a hard quota cap in a loop. `quota_exhausted` includes `reset_at` and `upgrade_url` to pass on to the user.
- Coverage is global wherever the current Overture release has indexable Places data, but density and quality vary by location. Check https://openplacesapi.com/coverage when coverage matters.