Início rápido

Crie uma conta. É de graça, com 1.000 créditos por mês, e não pedimos cartão. Depois crie uma chave em Chaves de API, no console. Ela começa com gm_ e só aparece uma vez: não guardamos a chave em si, então, se perder, crie outra.

Deixe a chave fora do código. Os exemplos daqui leem a chave de uma variável de ambiente:

export GMAPS_API_KEY=gm_…

Diga o que você procura e onde. Esta busca pede padarias em Curitiba:

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

A resposta vem em data. Aqui ela está reduzida a um lugar e a poucos campos:

{
  "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: até limit lugares. São 20 se você não pedir outro número, e no máximo 120. Lugares explica cada campo.
• coverage: quanto da região já tínhamos buscado recentemente. fresh é tudo, partial é uma parte e new é nada. Cobertura explica como acompanhamos isso.
• placesKnown: quantos lugares já tínhamos salvado ali. Todos saem de graça.
• meta.cached, em cada lugar: true quando já tínhamos o lugar salvo, então ele não custou nada.
• collection: quando o que tínhamos salvado não chega ao limit e parte da região ainda precisa ser buscada, esta é a coleta que está buscando o resto. Se não, vem null.
• collectionError: por que não deu para começar uma coleta, por exemplo porque os créditos de hoje acabaram. Os lugares que já tínhamos voltam do mesmo jeito.

Buscar é de graça. Você paga 1 crédito por lugar novo que uma coleta encontra, e uma busca nunca custa mais que limit créditos:

• 0Um lugar que já salvamos volta na mesma resposta, marcado com cached: true.
• 1Um lugar novo que uma coleta encontra para você.
• 1E-mails de um lugar novo, nos planos pagos: 1 crédito por lugar, só quando encontramos pelo menos um.
• 0Buscas, estimativas, exportações e consultas ao seu consumo.
• 0Uma coleta que não encontra nada.

Para ver quantos créditos ainda restam, chame GET /v1/usage. Também é de graça. Os números de cada plano estão em Limites.

Uma coleta leva alguns minutos. Enquanto ela roda, você pode:

• fazer a mesma busca de novo mais tarde. Os lugares novos voltam junto com os outros, e dessa vez de graça.
• mandar "wait": 60 para a resposta esperar até 60 segundos enquanto os lugares novos chegam.
• ler a coleta em GET /v1/collections/{id}, com o id que veio nela. Coletas explica o que ela traz.

• Busca: todos os campos de uma busca, as quatro formas de dizer onde e o que cada resposta significa.
• Coletas: busque numa cidade inteira, não só numa página de resultados.
• Progresso ao vivo: veja os lugares novos chegando, um por um.
• Exportações: baixe uma coleta em CSV, JSON ou planilha do Excel.
• SDK para TypeScript: um método tipado para cada chamada.
• MCP para agentes: deixe um agente de IA buscar lugares com a sua chave.
• Erros: todos os códigos de erro e o que fazer em cada um.