Referencia
Límites
Qué permite cada plan, qué responde la API cuando llegas a un límite y cuándo se reinicia cada uno.
Plan por plan
Son los mismos números de la página de precios. Para cambiar de plan, abre Plan en la consola.
| Límite | Free | Starter | Pro | Scale |
|---|---|---|---|---|
| Precio por mes en BRL | 0 BRL | 99 BRL | 299 BRL | 1090 BRL |
| Precio por mes en USD | 0 USD | 24 USD | 69 USD | 269 USD |
| Precio por mes en EUR | 0 € | 22 € | 64 € | 249 € |
| Créditos por mes | 1000 | 20.000 | 75.000 | 300.000 |
| Límite diario, en créditos | 250 | 3000 | 10.000 | 40.000 |
| Recopilaciones simultáneas | 1 | 2 | 5 | 10 |
| Lugares por recopilación | 500 | 5000 | 25.000 | 100.000 |
| Solicitudes por minuto | 30 | 120 | 300 | 600 |
| Claves de API | 2 | 5 | 10 | 20 |
| Correos electrónicos | No | Sí | Sí | Sí |
| Webhooks | No | Sí | Sí | Sí |
Cuando llegas a uno
| Límite | Respuesta | Qué hacer |
|---|---|---|
| Créditos por mes | 429 QUOTA_EXCEEDEDdetails.scope: "month" | Compra un paquete de créditos en Plan, o espera hasta el día 1. |
| Límite diario, en créditos | 429 QUOTA_EXCEEDEDdetails.scope: "day" | Espera hasta la medianoche UTC. Un paquete no ayuda aquí. |
| Recopilaciones simultáneas | 429 QUOTA_EXCEEDEDdetails.scope: "concurrency" | Espera a que termine una recopilación, o cancela una. |
| Lugares por recopilación | 400 VALIDATION_ERROR | Pide menos con maxPlaces, o cambia de plan. details.limit es el máximo de tu plan. |
| Solicitudes por minuto | 429 RATE_LIMIT_EXCEEDED | Espera los segundos que indica retry-after. |
| Claves de API | 409 CONFLICT | Revoca una clave que no uses, o cambia de plan. |
| Correos electrónicos | 402 PLAN_GATE | Cambia a un plan que incluya correos electrónicos. |
| Webhooks | 402 PLAN_GATE | Cambia a un plan que incluya webhooks. |
Los correos electrónicos también requieren que aceptes la política de uso aceptable. Mientras no la aceptes, pedirlos responde 403 AUP_REQUIRED. Leer lugares no falla por eso: el campo emails simplemente no aparece.
Una búsqueda nunca falla por falta de créditos. Cuando se te acaban, o ya tienes tantas recopilaciones en curso como permite tu plan, igual responde con los lugares que guardamos, y collectionError explica por qué no pudo recopilar el resto.
Una recopilación que ya está en curso se detiene cuando llega a cualquiera de los dos límites de créditos, y nunca cobra más allá. Los lugares que entregó antes siguen siendo tuyos, y su stopReason dice qué límite la detuvo: daily_cap o quota. Consulta Recopilaciones.
El límite por minuto cuenta todas las llamadas de tu cuenta: con cualquiera de sus claves, cada llamada a una herramienta de MCP, y las búsquedas y recopilaciones que haces en la consola.
Cuándo se reinician los límites
- Límite diario: todos los días a la medianoche UTC.
- Créditos por mes: el día 1 de cada mes a la medianoche UTC, sin importar qué día te suscribiste. Los créditos que no usaste no pasan al mes siguiente.
- Recopilaciones simultáneas: en cuanto termina una de las tuyas.
- Solicitudes por minuto: al comenzar cada minuto del reloj.
GET /v1/usage da las horas exactas, en dailyResetAt y resetAt.
Paquetes de créditos
Un paquete suma créditos que nunca vencen. Se gastan solo cuando se acaban los créditos del mes de tu plan. Un paquete nunca sube el límite diario: te deja recopilar más días, no más en un solo día. Cómpralo en Plan, en la consola.
| Créditos | Precio en BRL | Precio en USD | Precio en EUR |
|---|---|---|---|
| 10.000 | 69 BRL | 19 USD | 17 € |
| 50.000 | 269 BRL | 69 USD | 63 € |
| 200.000 | 999 BRL | 249 USD | 229 € |
Lo que nunca cuenta
Los créditos pagan lugares nuevos: uno por cada lugar nuevo que encuentra una recopilación, y uno más cuando además encuentra un correo electrónico de ese lugar. Los lugares que ya guardamos llegan gratis, así que nunca cuentan para un límite de créditos.
Buscar, pedir una estimación, exportar y consultar tu uso también es gratis. Todo eso sí cuenta para tus solicitudes por minuto.
Consulta cuánto has usado
Llama a GET /v1/usage. Es gratis:
curl https://api.gmaps.dev/v1/usage \
-H "Authorization: Bearer $GMAPS_API_KEY"creditsRemaining: lo que aún puedes gastar este mes, con los créditos de paquete incluidos. El límite diario puede detenerte antes.dailyCreditsUsedydailyCreditCap: lo que gastaste hoy y lo máximo que puedes gastar.creditBalance: los créditos de paquete que te quedan.dailyResetAtyresetAt: cuándo se reinician el día y el mes.keys: los mismos totales para cada clave de API, incluidas las revocadas, más uno para lo que ejecutaste en la consola.
Esa respuesta también trae un encabezado x-credits-remaining, con el mismo número que creditsRemaining. Las demás llamadas no lo envían. La consola muestra los mismos números en Uso.