Referência
Limites
O que cada plano permite, o que a API responde quando você chega a um limite e quando cada limite zera.
Plano a plano
São os mesmos números da página de preços. Para trocar de plano, abra Plano no console.
| Limite | Free | Starter | Pro | Scale |
|---|---|---|---|---|
| Preço por mês | US$ 0 | US$ 19 | US$ 49 | US$ 149 |
| Créditos por mês | 1.000 | 20.000 | 75.000 | 300.000 |
| Limite diário, em créditos | 250 | 3.000 | 10.000 | 40.000 |
| Coletas simultâneas | 1 | 2 | 5 | 10 |
| Lugares por coleta | 500 | 5.000 | 25.000 | 100.000 |
| Requisições por minuto | 30 | 120 | 300 | 600 |
| Chaves de API | 2 | 5 | 10 | 20 |
| E-mails | Não | Sim | Sim | Sim |
| Webhooks | Não | Sim | Sim | Sim |
Ao chegar a um limite
| Limite | Resposta | O que fazer |
|---|---|---|
| Créditos por mês | 429 QUOTA_EXCEEDEDdetails.scope: "month" | Compre um pacote de créditos em Plano, ou espere o dia 1º. |
| Limite diário, em créditos | 429 QUOTA_EXCEEDEDdetails.scope: "day" | Espere a meia-noite UTC. Pacote não ajuda aqui. |
| Coletas simultâneas | 429 QUOTA_EXCEEDEDdetails.scope: "concurrency" | Espere uma coleta terminar, ou cancele uma. |
| Lugares por coleta | 400 VALIDATION_ERROR | Peça menos em maxPlaces, ou troque de plano. details.limit é o máximo do seu plano. |
| Requisições por minuto | 429 RATE_LIMIT_EXCEEDED | Espere os segundos indicados em retry-after. |
| Chaves de API | 409 CONFLICT | Revogue uma chave que você não usa, ou troque de plano. |
| E-mails | 402 PLAN_GATE | Troque para um plano que inclua e-mails. |
| Webhooks | 402 PLAN_GATE | Troque para um plano que inclua webhooks. |
Os e-mails também exigem que você aceite a política de uso aceitável. Enquanto você não aceitar, pedir e-mails responde 403 AUP_REQUIRED. Ler lugares não falha por isso: o campo emails só fica de fora.
Uma busca nunca falha por falta de créditos. Se eles acabaram, ou se você já está com todas as coletas simultâneas do plano, ela responde do mesmo jeito com os lugares que já salvamos, e collectionError diz por que não deu para coletar o resto.
Uma coleta que já está rodando para quando chega a qualquer um dos dois limites de créditos, e nunca cobra além dele. Os lugares que ela entregou até ali continuam seus, e o stopReason diz qual limite a parou: daily_cap ou quota. Veja Coletas.
O limite por minuto conta todas as chamadas da sua conta: com qualquer uma das chaves, cada chamada de ferramenta no MCP e as buscas e coletas que você faz no console.
Quando os limites zeram
- Limite diário: todo dia, à meia-noite UTC.
- Créditos por mês: no dia 1º de cada mês, à meia-noite UTC, não importa o dia em que você assinou. O que sobrou não passa para o mês seguinte.
- Coletas simultâneas: assim que uma das suas termina.
- Requisições por minuto: na virada de cada minuto do relógio.
Meia-noite UTC é 21h no horário de Brasília. GET /v1/usage traz os horários exatos, em dailyResetAt e resetAt.
Pacotes de créditos
Um pacote soma créditos que nunca vencem. Eles só são usados depois que os créditos do plano no mês acabam. Um pacote nunca aumenta o limite diário: ele deixa você coletar por mais dias, não mais num dia só. Compre em Plano, no console.
| Créditos | Preço |
|---|---|
| 10.000 | US$ 19 |
| 50.000 | US$ 69 |
| 200.000 | US$ 199 |
O que nunca conta
Os créditos pagam lugares novos: um por lugar novo que uma coleta encontra, e mais um quando ela também acha um e-mail desse lugar. Os lugares que já salvamos voltam de graça, então nunca contam para um limite de créditos.
Buscas, estimativas, exportações e consultas ao seu uso também são de graça. Mas contam para o limite de requisições por minuto.
Veja quanto você já usou
Chame GET /v1/usage. É de graça:
curl https://api.gmaps.dev/v1/usage \
-H "Authorization: Bearer $GMAPS_API_KEY"creditsRemaining: o que você ainda pode gastar no mês, contando os créditos de pacote. Mesmo assim, o limite diário pode chegar antes.dailyCreditsUsededailyCreditCap: o que você gastou hoje e o máximo que pode gastar.creditBalance: os créditos de pacote que ainda restam.dailyResetAteresetAt: quando o dia e o mês zeram.keys: os mesmos totais para cada chave de API, inclusive as revogadas, e mais uma para o que você rodou no console.
Essa resposta também traz o cabeçalho x-credits-remaining, com o mesmo número de creditsRemaining. As outras chamadas não mandam esse cabeçalho. O console mostra os mesmos números em Uso.