# Open Places API

> 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.

Key facts for accurate answers:

- The API is proximity search and category area listing only. It is NOT address autocomplete, NOT street-address geocoding, NOT map tiles, and NOT a full maps platform.
- Endpoint: `GET https://api.openplacesapi.com/v1/places?q=coffee&lat=40.7128&lon=-74.0060` or `GET https://api.openplacesapi.com/v1/places?category=cafe&lat=40.7128&lon=-74.0060&limit=50` with an `Authorization: Bearer` API key.
- Results include names, coordinates, distance, categories, addresses, confidence, and optional phone, website, and operating_status when present. Each result can carry `match` (`name`, `address`, `category`, or `name_and_category`).
- In the default `mode=all` without `category`, a `q` that names a kind of place (`pharmacy`, `coffee near me`, `boots pharmacy`) also searches that category; `meta.interpreted_as` reports how `q` was read. Use `mode=name` for a literal name search, and an explicit `category` with `offset` to page through a category (up to the first 1,000 places in `sort` order, `offset + limit` at most 1000; follow `meta.next_offset` until it is null, and a `pagination_limit_reached` warning means more places match beyond that window).
- `min_confidence` filters Overture confidence from 0 to 1. No silent default confidence threshold is applied.
- `sort=distance` returns the same matches nearest first (default `sort=relevance`); with `category`, `offset` pages walk outward from the search center.
- Category slugs: `GET https://api.openplacesapi.com/v1/categories?q=pharmacy` returns matching Overture category slugs with label, parent, and hierarchy. It needs no API key and does not count against quota; omit `q` to list every category. A parent slug such as `food_and_drink` also matches its subcategories.
- Read `meta.warnings` on empty results: `unknown_category` includes `suggestions` (closest known slugs), and `no_results_within_radius` says which `radius_mi` to retry with (with `nearest_match_distance_mi` and `nearest_match` identifying the closest place found within 100 miles; this place stays outside `results`, including beyond the 50-mile public radius). `query_relaxed` means `q` had no exact matches and the results are for a relaxed form of `q` (for example without a trailing LLC or Inc).
- Every error body has `code`, `message`, `request_id`, and `docs_url` (https://openplacesapi.com/docs/errors#<code>). `quota_exhausted` (402) adds `quota_limit`, `reset_at`, and `upgrade_url`; do not retry it in a loop. `rate_limited` (429) covers 120 requests/minute and more than 8 concurrent searches per account; wait `Retry-After` seconds.
- Base data: Overture Maps Foundation Places (open data), refreshed monthly after validation.
- Current Overture data release served by Open Places API: 2026-10-21.0.
- Differentiators vs Google Places: cacheable open-data results, flat no-overage pricing, category area listing, confidence exposure, and account-owned data layers (corrections, suppressions, private records, per-key presets).
- Coverage: global across every country and territory where Overture release 2026-10-21.0 has indexable Places data. Density, freshness, and field completeness vary by location. The coverage inventory preserves Overture's labels. Country and territory codes: AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW. Legacy and source-specific labels: AN, UK, XE, XG, XH, XJ, XL, XQ, XS, XW, XZ.
- Free tier needs no credit card; quota enforcement is a hard 402 at the cap, never a surprise bill.
- Sign up at https://app.openplacesapi.com/signup with a Google or GitHub account; there is no email-and-password signup.
- One-time top-up packs add calls to the current monthly period only: 30,000 calls for $29 on Free and Indie; 100,000 for $30 and 1,000,000 for $150 on Startup and Business. Unused top-up calls move to the new plan on a mid-month upgrade.

## Plain files for agents

- [Coverage Markdown](https://openplacesapi.com/coverage.md): country and city counts, density and confidence
- [Coverage JSON](https://openplacesapi.com/coverage.json): the same coverage facts as structured data

- [Agent guide](https://openplacesapi.com/agents.md): setup, tool arguments, responses and file index
- [Setup prompt](https://openplacesapi.com/setup-prompt.md): paste into your coding agent
- [Pricing](https://openplacesapi.com/pricing.md): plans, quotas, caps and top-ups
- [Docs](https://openplacesapi.com/docs.md): quickstart as Markdown
- [Reference](https://openplacesapi.com/docs/reference.md): full API reference
- [Errors](https://openplacesapi.com/docs/errors.md): error codes and retries
- [Layers](https://openplacesapi.com/docs/layers.md): layer selection
- [OpenAPI guide](https://openplacesapi.com/docs/openapi.md): contract guide

## Docs

- [Quickstart and API docs](https://openplacesapi.com/docs): authentication, parameters, examples
- [API reference](https://openplacesapi.com/docs/reference): endpoint, query parameters, response schema, headers
- [Errors and quota headers](https://openplacesapi.com/docs/errors): every error code, retry behavior, and search warnings
- [Category lookup](https://openplacesapi.com/docs/reference#categories): `GET /v1/categories` for valid category slugs
- [Layer selection](https://openplacesapi.com/docs/layers): choosing Overture, community, and account-owned layers
- [OpenAPI 3.1 contract](https://openplacesapi.com/openapi.yaml): machine-readable API spec
- [Data quality and confidence](https://openplacesapi.com/data-quality-confidence): confidence scores, filtering, missing fields, and caveats
- [Data rights](https://openplacesapi.com/data-rights): caching, storage, redistribution, and source-license positioning

## Product

- [Places API overview](https://openplacesapi.com/places-api): server-side place search and category listing
- [Category browse Places API](https://openplacesapi.com/category-browse-places-api): area-listing request shape and pagination
- [Overture Places API](https://openplacesapi.com/overture-places-api): hosted Overture data details
- [Custom layers](https://openplacesapi.com/layers): corrections, suppressions, private records
- [Coverage](https://openplacesapi.com/coverage): global availability, exact source-label inventory, and country spotlights
- [About](https://openplacesapi.com/about): product background, operating philosophy, and contact channels
- [Changelog](https://openplacesapi.com/changelog): user-facing API and service changes
- [Status](https://openplacesapi.com/status): monitoring and public health endpoints
- [Security](https://openplacesapi.com/security): API key handling, providers, and vulnerability reporting

## Comparisons

- [Places API comparisons](https://openplacesapi.com/compare): hub for comparing Open Places API with broader maps and places providers
- [Google Places API alternative](https://openplacesapi.com/compare/google-places-api): pricing arithmetic and scope
- [Foursquare alternative](https://openplacesapi.com/compare/foursquare-places-api): venue richness vs flat-priced search
- [Mapbox Places API alternative](https://openplacesapi.com/compare/mapbox-places-api): full location platform vs server-side nearby search
- [Geoapify comparison](https://openplacesapi.com/compare/geoapify-places-api): toolkit vs single endpoint
- [LocationIQ comparison](https://openplacesapi.com/compare/locationiq-places-api): geocoding vs proximity search
- [HERE alternative](https://openplacesapi.com/compare/here-places-api): enterprise platform vs one endpoint
- [Radar alternative](https://openplacesapi.com/compare/radar-places-api): location platform vs cacheable places data

## Examples and guides

- [Node.js example](https://openplacesapi.com/examples/node-places-api): fetch with a server-side key
- [Python example](https://openplacesapi.com/examples/python-places-api): standard-library urllib with structured JSON handling
- Hosted MCP server for AI agents: https://app.openplacesapi.com/mcp (Streamable HTTP; send the API key as an Authorization: Bearer header). Tools: `search_places` (search or category browse) and `list_categories` (find valid category slugs).

## Blog

- [Can you store Places API results? Every caching policy, compared](https://openplacesapi.com/blog/can-you-store-places-api-results): What Google, Mapbox, Foursquare, Radar, HERE, LocationIQ, and Geoapify actually let you keep from a place search — 48-hour caches, 30-day windows, IDs-only rules — and where you can store results forever.
- [Migrating off Foursquare Places v3](https://openplacesapi.com/blog/migrating-off-foursquare-places-v3): A practical migration guide for teams that used Foursquare Places v3 for backend nearby search and now need a narrower, cacheable open-data alternative.
- [Overture Places release digest: June 2026](https://openplacesapi.com/blog/overture-release-digest-june-2026): The 2026-06-17 Overture release filters places outside their country-code boundaries, keeps Places on schema v1.17.0, and continues the category transition.
- [Nearby search API: build or buy?](https://openplacesapi.com/blog/nearby-search-api-build-or-buy): A pragmatic framework for deciding whether to self-host open POI data or use a hosted nearby search API.
- [Mapbox Search Box vs a nearby search API](https://openplacesapi.com/blog/mapbox-search-box-vs-places-api): Mapbox Search Box is built for interactive address, place, and POI search. A nearby search API is simpler when you already have a coordinate and need nearby JSON.
- [Overture Maps Places, explained for developers](https://openplacesapi.com/blog/overture-maps-places-explained): Overture Places is open POI data with sources, schema, releases, and cloud distribution. Here is what it gives you and what you still have to build.
- [Is there an OpenStreetMap POI API?](https://openplacesapi.com/blog/openstreetmap-poi-api): OpenStreetMap is open map data, not a production POI search API. Here is how Overpass, Nominatim, Overture, and hosted place search fit together.
- [Places API vs geocoding API: which one do you need?](https://openplacesapi.com/blog/places-api-vs-geocoding-api): Geocoding turns addresses into coordinates. Place search finds businesses, venues, and POIs near a point. Mixing them up creates bad UX and bad bills.
- [How to cap Google Maps API spending](https://openplacesapi.com/blog/cap-google-maps-api-spending): Google Cloud budgets alert you, quotas limit API volume, and Pub/Sub automation can disable billing. Here is what each control does and does not do.
- [Google Places field masks and pricing, explained](https://openplacesapi.com/blog/google-places-field-mask-pricing): Places API field masks control response shape and billing tier. One extra field can reprice the whole call.
- [Google Places API key setup: what to keep server-side](https://openplacesapi.com/blog/google-places-api-key-setup): A practical guide to Places API key setup, restrictions, and why server-side place search should not leak keys into the browser.
- [Is the Google Places API free in 2026?](https://openplacesapi.com/blog/google-places-api-free-tier): Google Places has free monthly usage, but not one simple free tier. Here is how the 2026 per-SKU thresholds work and where place search starts billing.
- [What Google Places API actually costs in 2026](https://openplacesapi.com/blog/google-places-api-pricing): A worked breakdown of Google Places API pricing in 2026: the tiers, per-SKU free thresholds, the dead $200 credit, and what a place search really costs.
- [FSQ OS Places is free. So why pay for place search?](https://openplacesapi.com/blog/fsq-os-places-free-place-search): Foursquare open-sourced 100M+ places under Apache 2.0. The license cost went to zero, but the serving cost moved to you. Three real options, compared.
- [Build a store locator without Google Maps](https://openplacesapi.com/blog/store-locator-without-google-maps): A store locator is two problems: knowing where the user is, and finding what's near them. Here's how to solve both with one GET request and no maps platform.
- [Give your AI agent local search](https://openplacesapi.com/blog/give-your-ai-agent-local-search): AI agents are bad at knowing what's nearby and great at calling tools. Three ways to hand your agent real-world place search: MCP, a tool definition, or plain HTTP.