# Hand this _to your agent._

Paste the setup prompt into Claude Code, Cursor or Codex. It asks you for a key, then connects over MCP or calls the REST API from your server code.

[Get a key](https://app.openplacesapi.com/signup)

MCP server**app.openplacesapi.com/mcp**

REST endpoint**api.openplacesapi.com/v1/places**

Auth**One server-side bearer key**

Free plan**10,000 searches a month, no card**

Results**Yours to cache, store and keep**

**setup-prompt.md** 

Set up Open Places API in this project. It is place search
(businesses, landmarks, venues) near a point, on open
Overture data, over MCP or REST.

1. Ask me for an API key. I create one at
   https://app.openplacesapi.com (Google or GitHub sign-in,
   10,000 free searches a month). Don't sign up yourself.
2. Store it as OPA_KEY in server-side config only. Never put it
   in browser code, a public repo, logs or a prompt.
3. If you support MCP, add the hosted server:
   claude mcp add --transport http openplacesapi \
     https://app.openplacesapi.com/mcp \
     --header "Authorization: Bearer $OPA_KEY"
   Tools: search_places, list_categories.
4. Otherwise call REST from server code:
   GET https://api.openplacesapi.com/v1/places
       ?q=coffee&lat=40.7411&lon=-73.9897
   Authorization: Bearer $OPA_KEY
   Contract: https://openplacesapi.com/openapi.yaml
5. Find category slugs with list_categories (or
   GET /v1/categories) instead of guessing. It's free.
6. You may cache and store results, subject to the open-data
   licenses: https://openplacesapi.com/data-rights
7. On 402 quota_exhausted, stop and tell me. On 429 or 503,
   wait Retry-After seconds, then retry.

Everything else: https://openplacesapi.com/llms.txt

## Every answer _is a plain file._

Agents read these directly. They share the site's source data and documentation.

| File                                                    | What it answers                                                               |
| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
| </coverage.md>                                          | Places per country and per city, with density and confidence.                 |
| </coverage.json>                                        | The same coverage facts and per-category counts, as structured data.          |
| </llms.txt>                                             | What Open Places is, what it isn't, and where everything else lives.          |
| </openapi.yaml>                                         | The REST contract: parameters, response fields, errors.                       |
| </pricing.md>                                           | Plans, limits and what happens at the cap, as a table.                        |
| </agents.md>                                            | This guide, including tool arguments and responses.                           |
| </setup-prompt.md>                                      | The setup prompt, ready to paste into a coding agent.                         |
| </docs.md>                                              | The quickstart. Add .md to any docs page URL, for example /docs/reference.md. |
| </.well-known/agent-skills/open-places-search/SKILL.md> | A skill file coding agents can load to search places well.                    |
| </auth.md>                                              | How keys work, and why an agent can't sign up on its own.                     |
| </.well-known/mcp/server-card.json>                     | The MCP server's address, transport and tools.                                |

## Two tools. _Plain arguments._

### search\_places

Places near a point, by text, category or both. One search against your quota.

`lat, lon`Required. The search center.

`q`Free text: "ramen", "Blue Bottle", "pharmacy". Required unless category is supplied. At least 3 searchable characters, or 2 contiguous CJK characters.

`category`An exact slug, like coffee\_shop or food\_and\_drink. Use list\_categories to find it.

`radius_mi`Up to 50\. Default 25.

`limit`Up to 20 for text, 50 with a category. Default 10.

`offset`Category browse only. offset + limit ≤ 1000\. Follow meta.next\_offset.

`min_confidence`Source confidence from 0 to 1; no default threshold.

`sort`relevance (default) or distance.

`mode`all (default), name or address. Address mode needs at least 4 searchable characters.

### list\_categories

The right slug for "ev charging" or "hardware store". Free; no key, no quota.

`q`Words describing the kind of place. Omit to list every category.

`limit`Up to 100 matches. Default 20\. Ignored without q.

### Responses to handle

`402`quota\_exhausted: stop and tell the user. Upgrade or buy a top-up; never retry in a loop.

`429`rate\_limited: 120 a minute, 8 in flight per account. Wait Retry-After.

`503`coverage\_not\_ready: wait Retry-After, then retry.

`Warnings`Read meta.warnings for unknown\_category suggestions, relaxed or inferred queries, nearby matches outside the radius and pagination limits. See /docs/errors.

## Prices an agent _can read._

So "which plan do I need for 50,000 searches a month?" gets a right answer without a screenshot.

# Open Places pricing
Checked 2026-11-10 · Currency: USD · Billing: monthly or yearly

| Plan | Searches/month | Monthly | Yearly | Layer entries |
|---|---:|---:|---:|---:|
| Free | 10,000 | $0 | — | 250 |
| Indie | 30,000 | $19 | $190 | 1,000 |
| Startup | 100,000 | $49 | $490 | 5,000 |
| Business | 1,000,000 | $249 | $2,490 | 50,000 |
| Scale | Over 1,000,000 | Custom | Custom | Custom |

## At the cap
No overages. Requests past the quota return HTTP 402 quota_exhausted.
Top-ups are one-time, current period only. Unused calls move with a mid-month upgrade.

| Top-up | Calls | Price | Plans |
|---|---:|---:|---|
| 30k | 30,000 | $29 | Free, Indie |
| 100k | 100,000 | $30 | Startup, Business |
| 1M | 1,000,000 | $150 | Startup, Business |

All plans include MCP and REST, global Overture coverage and results you may store under the source licenses.
Free needs no card. Sign up with Google or GitHub at https://app.openplacesapi.com/signup.
Full plan terms: https://openplacesapi.com/pricing
Data rights: https://openplacesapi.com/data-rights