Quickstart

Create an account. It's free, with 1,000 credits a month and no card. Then create a key under API keys in the console. It starts with gm_, and you see it only once: we don't keep the key itself, so if you lose it, make a new one.

Keep the key out of your code. The examples here read it from an environment variable:

export GMAPS_API_KEY=gm_…

Say what you're looking for and where. This asks for bakeries in Curitiba:

curl -X POST https://api.gmaps.dev/v1/places/search \
  -H "Authorization: Bearer $GMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["bakery"], "geo": { "location": "Curitiba, PR" } }'

The answer comes back under data. Here it's cut down to one place and a few fields:

{
  "data": {
    "places": [
      {
        "id": "5b0c8e0a-2f4d-4c1e-9a57-3d2b8f6e1c90",
        "identity": {
          "cid": "12345678901234567890",
          "name": "Padaria Estrela do Centro",
          "category": "Padaria",
          "mapsUrl": "https://maps.google.com/?cid=12345678901234567890"
        },
        "contact": { "phones": ["+55 41 0000-0000"], "website": null },
        "location": {
          "city": "Curitiba",
          "state": "PR",
          "lat": -25.4296,
          "lng": -49.2713
        },
        "ratings": { "rating": 4.6, "reviewCount": 212 },
        "meta": { "cached": true }
      }
    ],
    "coverage": "partial",
    "placesKnown": 14,
    "collection": {
      "id": "8c1f5e2a-7b3d-4f60-9e14-2a6d0b9c7f31",
      "status": "queued"
    },
    "collectionError": null
  }
}

• places: up to limit places. That's 20 unless you ask for more, up to 120. Places explains every field.
• coverage: how much of the area we'd searched recently. fresh is all of it, partial is some, and new is none. Coverage explains how we keep track.
• placesKnown: how many places we'd already saved there. They're all free.
• meta.cached, on each place: true when we'd already saved it, so it cost nothing.
• collection: when what we'd saved can't fill limit and part of the area still needs searching, this is the collection finding the rest. Otherwise it's null.
• collectionError: why we couldn't start a collection, such as no credits left today. You still get the places we had.

Searching is free. You pay 1 credit for each new place a collection finds for you, and a search never costs more than limit credits:

• 0A place we already saved comes back in the same answer, marked cached: true.
• 1A new place that a collection finds for you.
• 1Emails for a new place, on paid plans: 1 credit per place, only when we find at least one.
• 0Searching, quotes, exports and checking your usage.
• 0A collection that finds nothing.

To see how many credits you have left, call GET /v1/usage. That's free too. Limits has each plan's numbers.

A collection takes a few minutes. While it runs, you can:

• run the same search again later. The new places come back with the rest, and this time they're free.
• add "wait": 60, and the answer holds for up to 60 seconds while new places arrive.
• read the collection at GET /v1/collections/{id}, with the id it came with. Collections explains what it holds.

• Search: every field a search takes, the four ways to say where, and what each answer means.
• Collections: search a whole city, not just one page of results.
• Live progress: watch new places arrive one by one.
• Exports: download a collection as a CSV, JSON or Excel file.
• TypeScript SDK: one typed method for each call.
• MCP for agents: let an AI agent search for places with your key.
• Errors: every error code, and what to do about each one.