# gmaps.dev

> Business leads for AI agents. gmaps.dev finds businesses on the map, such as bakeries in Curitiba or dentists near a point. Each one is a "place". gmaps.dev is not affiliated with Google or Alphabet.

- Base URL: `https://api.gmaps.dev/v1`
- Auth: `Authorization: Bearer gm_…`, with a key from https://console.gmaps.dev/keys
- TypeScript and JavaScript: `npm i gmaps-sdk`
- MCP over Streamable HTTP: `https://api.gmaps.dev/mcp`, with the same key

## How the calls fit together

1. Start with search_places: keywords and one area. It answers at once, for free, with the places we saved from earlier searches. If they do not fill `limit` (up to 120), it also starts a collection to find the rest. Each new place costs 1 credit, so a search never costs more than `limit` credits.
2. A collection takes minutes. Check it with get_collection, then run the same search_places again: the new places come back, and now they are free.
3. For a whole city, run quote_collection first. It is free and says the most it can cost. Then create_collection with maxPlaces.
4. To give places to a person, use create_export and share its link. It opens a csv, json or xlsx file (xlsx up to 50,000 places) for 24 hours. Do not page through a large result in your context.
5. get_place reads one saved place, by our id, Google's cid, Google's place ID or a Google Maps link. It never searches.
6. get_usage shows the credits left today and this month. create_webhook tells your server when a collection ends, so you do not have to keep checking.

Every error says what to do next. A 401 means the call has no working API key: reconnect through the AI app, or create a key at https://console.gmaps.dev/keys. 429 QUOTA_EXCEEDED carries details.scope (day, month or concurrency): wait, or ask the person you work for to change plans. 402 PLAN_GATE means the plan does not include that feature, and details.upgradeTo names the plan that does. A collection that ends early says why in stopReason.

Email addresses come only on paid plans, after the account accepts the acceptable use policy. A place is not permission to contact anyone.

## Operations

- [List the open-source projects we build on](https://gmaps.dev/docs/reference/get_attributions.md): List the projects credited by gmaps.dev, with their licenses and notices. No API key needed. Costs no credits.
- [Search for places](https://gmaps.dev/docs/reference/search_places.md): Find places by what they are and where they are, such as bakeries in Curitiba. Places we saved from earlier searches come back at once, for free. If they do not fill `limit`, a collection starts to find the rest and the answer includes it: each new place costs one credit as it arrives, and it stops at `limit`, so a search never costs more than `limit` credits. Search again later, or read the collection, to get the new ones; with `wait`, the answer waits up to 60 seconds for them. Needs an API key.
- [Look up a place](https://gmaps.dev/docs/reference/get_place.md): Read one saved place, by our id, Google's cid, Google's place ID, or a Google Maps link to it. It never searches: a place we have not saved answers 404, and searching its area with search_places brings it in. Needs an API key. Costs no credits.
- [Start a collection](https://gmaps.dev/docs/reference/create_collection.md): Search a whole area, square by square, and collect up to maxPlaces of the places in it. Answers straight away with the collection, then works through the area in the background. Read the collection again to see how far it has got. Starting one costs nothing: each new place costs one credit as it arrives, and saved places cost nothing. Needs an API key.
- [List your collections](https://gmaps.dev/docs/reference/list_collections.md): Your collections, newest first, with the total so you know how many more there are. Filter by status to find the ones still running. Needs an API key. Costs no credits.
- [Read a collection](https://gmaps.dev/docs/reference/get_collection.md): See where a collection has got to: how much of the area is searched, how many places have arrived, and what it has cost so far. Read it again whenever you want an update. Needs an API key. Costs no credits.
- [Cancel a collection](https://gmaps.dev/docs/reference/cancel_collection.md): Stop a collection you no longer want. One that has not started yet stops at once and costs nothing. One already running keeps the places that have arrived and the credits they cost; the search in flight finishes, and nothing new starts. A collection that has already ended cannot be cancelled. Needs an API key. Costs no credits.
- [List a collection's places](https://gmaps.dev/docs/reference/list_collection_places.md): The places a collection has found, oldest first, so a page you have already read stays the same as more arrive. Each place says whether we already had it, which is how you check what you were charged. A page can come back short when a business asked to be left out, so keep reading until you pass the total rather than stopping at a short page. The collection's counts still include those places, which is the record of what you were charged. Needs an API key. Costs no credits.
- [Quote a collection](https://gmaps.dev/docs/reference/quote_collection.md): See what collecting an area would cost before you start it: how much of it we have searched recently, how many places we have saved there (those cost nothing), how many searches are left to run, and the most it can cost in credits. Needs an API key. Costs no credits and starts nothing.
- [Export a collection](https://gmaps.dev/docs/reference/create_export.md): Get a link to a collection's places as one file: csv, json or xlsx. The file has the places the collection holds now, even if it is still running. The link opens without an API key for 24 hours, so share it only with people who should see the file. Needs an API key. Costs no credits.
- [Read an export](https://gmaps.dev/docs/reference/get_export.md): Read an export you made, with its download link, while the link still works. After 24 hours, or once the collection's places are deleted, it answers 404: make a new export from the collection. Needs an API key. Costs no credits.
- [Check an area's coverage](https://gmaps.dev/docs/reference/get_coverage.md): See how much of an area we have already searched for a term, when we last searched it, and how many places we have saved there. Use it to decide whether to collect again or just read the saved places. Needs an API key. Costs no credits and starts nothing.
- [Get credit usage](https://gmaps.dev/docs/reference/get_usage.md): See this month's credits: what your plan includes, what you have used, what is left today and this month, and the same totals for each API key. Needs an API key. Costs no credits.
- [Add a webhook endpoint](https://gmaps.dev/docs/reference/create_webhook.md): Tell us where to POST when a collection ends, instead of asking us every few seconds whether it is done. The answer shows the signing secret once and never again. Store it, then check every request against it. The body carries counts and a link to the places, never the places themselves. Needs an API key and a paid plan. Costs no credits.
- [List your webhook endpoints](https://gmaps.dev/docs/reference/list_webhooks.md): Every endpoint you have added, newest first, with whether it is still receiving events and why we stopped if it is not. Secrets are not shown again after the endpoint is created. Needs an API key and a paid plan. Costs no credits.
- [Change a webhook endpoint](https://gmaps.dev/docs/reference/update_webhook.md): Change which events an endpoint receives, rename it, or switch it off and on. This is how an endpoint comes back after we stopped sending to it: fix your server, then set enabled to true. The failure count starts again from zero. Whatever you leave out stays as it was. Needs an API key and a paid plan. Costs no credits.
- [Delete a webhook endpoint](https://gmaps.dev/docs/reference/delete_webhook.md): Stop sending to an endpoint and forget it, along with the record of what we sent there. To pause one instead, set enabled to false. That keeps the secret, so you do not have to change your code to turn it back on. Needs an API key and a paid plan. Costs no credits.
- [Send a test event](https://gmaps.dev/docs/reference/test_webhook.md): Send a "ping" to one of your endpoints now, so you can check your code reads it and the signature checks out before a real collection depends on it. Answers straight away with the delivery; read the deliveries list a moment later to see what your server said. Needs an API key and a paid plan. Costs no credits.
- [List an endpoint's deliveries](https://gmaps.dev/docs/reference/list_webhook_deliveries.md): What we sent to one endpoint, newest first: which event, whether it arrived, how many tries it took, and what your server answered. This is where to look when an event never showed up. Kept for 7 days. Needs an API key and a paid plan. Costs no credits.

## Guides

- [Quickstart](https://gmaps.dev/docs/en/): Get a key, run one search and read the answer.
- [Authentication](https://gmaps.dev/docs/en/authentication): Every call sends your API key in the Authorization header. Create and revoke keys in the console, and keep them on your server.
- [Search](https://gmaps.dev/docs/en/search): Find places by what they are and where they are. A search answers at once with the places we've saved, and collects the rest when they aren't enough.
- [Places](https://gmaps.dev/docs/en/places): Look up one place we've saved, by any id or Maps link you have for it, and see what each field of a place means.
- [Coverage](https://gmaps.dev/docs/en/coverage): See how much of an area we've already searched for a term, and when. It's free, and it tells you whether there's anything left to collect.
- [Collections](https://gmaps.dev/docs/en/collections): A collection searches a whole area, not just one page of results. Get a free quote, start it, then read the places as they arrive.
- [Live progress](https://gmaps.dev/docs/en/streaming): Watch a collection fill up over one open connection: places as they arrive, how far it got, and the final counts.
- [Exports](https://gmaps.dev/docs/en/exports): Turn a collection's places into one csv, json or xlsx file, with a download link that works without a key.
- [Emails](https://gmaps.dev/docs/en/emails): Ask a collection to look for email addresses on each business's own website. You need a paid plan, and you must accept our acceptable use policy.
- [TypeScript SDK](https://gmaps.dev/docs/en/sdk): Call the API from TypeScript or JavaScript: one typed method per call, plus helpers to watch a collection and check a webhook.
- [MCP for agents](https://gmaps.dev/docs/en/mcp): Connect your AI app to search for places, collect an area and create exports. Calls use your account credits and limits.
- [Webhooks](https://gmaps.dev/docs/en/webhooks): We send a POST to your server when a collection ends, so your code doesn't have to keep asking whether it's done.
- [Chrome extension](https://gmaps.dev/docs/en/extension): A free Chrome extension that saves the places Google Maps shows you to a list in your browser. Its file has the same columns as an export, so code that reads one reads the other.
- [API reference](https://gmaps.dev/docs/en/api): Every call, with its fields, answers and errors, read from the document the API serves at /openapi.json. You can try a call from here with your key.
- [Errors](https://gmaps.dev/docs/en/errors): When a call fails, the answer says what went wrong and what to do next. Here is every error code, and how to handle each one.
- [Limits](https://gmaps.dev/docs/en/limits): What each plan allows, what the API answers when you reach a limit, and when each limit starts over.
- [Data and privacy](https://gmaps.dev/docs/en/data): Where places come from, what we keep and for how long, and how anyone can have something removed.

## Optional

- [OpenAPI](https://api.gmaps.dev/openapi.json): the same operations, machine-readable
- [Everything on one page](https://gmaps.dev/docs/llms-full.txt): every operation, the credits and the errors