API DOCUMENTATION / PLACES CONNECTOR
Places connector
Find shops, restaurants and other places in the 20 largest U.S. cities.
What it is
Find shops, restaurants, cafes, pharmacies, libraries and other places in the 20 largest U.S. cities by name, brand or category, see their hours and whether they are open now or at a given time, and NYC restaurant health grades. Unknown hours are reported as unknown, never as closed. Data © OpenStreetMap contributors (ODbL) plus Overture Maps, All the Places, Foursquare Open Source Places and city open data. Preview data: coverage is partial and fields may change. Every record links to its sources; check anything important at the source.
Connect
Endpoint: https://places-mcp.headcountlabs.com/mcp/public/places. It uses Streamable HTTP, is stateless and takes POST requests only. No account or key is needed. The data is read-only and U.S. only.
Example prompts
- Boba places open now near Union Square, San Francisco.
- Is the Chicago Public Library on State St open Sunday at 2pm?
- Every Starbucks within 2 km of Times Square.
- Pharmacies open now near Union Square, NYC.
- Find Joe's Pizza near Times Square.
Tools
These are the tools the endpoint returns from tools/list. A * marks a required input.
| Tool | What it does | Inputs |
|---|---|---|
find_places | Find shops, restaurants, cafes, libraries, pharmacies and other places near a point, nearest first. | lat*, lon*, radius_m, walk_minutes, q, brand, category, open_now, at, health_grade, include_registry, limit, cursor, fields |
get_place | One shop, restaurant, cafe or other place by its UUID (from find_places): name, brand, category, address, phone, website, weekly hours, whether it is open now (null when hours are unknown) and the NYC inspection grade. | id*, at, fields |
brand_counts | Count branded places (chains like Starbucks, CVS, McDonald's) near a point, optionally in one category: top 25 brands with their number of locations, plus how many places in range have no brand (independents). | lat*, lon*, radius_m, walk_minutes, category, include_registry |
get_place_record | The full stored record of one place by its UUID (the id returned by find_places or get_place): every field with the source it came from. | id* |
Every tool only reads public records and changes nothing. Pages hold at most 100 items, 20 by default. fields trims each item. Record IDs are for follow-up calls only.
Limits
Rate limits: 20 tool calls per minute per conversation (ChatGPT openai/session or the Mcp-Session-Id issued at initialize) and 600 requests per minute per network; over the limit, a tool call returns isError with the wait time and HTTP requests get 429 with Retry-After.
Responses are capped at 60,000 characters (items trimmed from the end, meta.truncated set).
Errors
A failed call returns an MCP tool result with isError: true and the API error JSON (invalid_parameter 400 naming the parameter, not_found 404, invalid_cursor 400, query_timeout 503 asking for a narrower search, read_only 503). Unknown tools and record paths outside this index are refused with a message. JSON-RPC errors: -32700 parse error, -32601 unknown method. HTTP 405 for GET/DELETE, 413 over 256 KB.