Reference
Limits
What each plan allows, what the API answers when you reach a limit, and when each limit starts over.
Plan by plan
These are the same numbers as on the pricing page. To change plans, open Plan in the console.
| Limit | Free | Starter | Pro | Scale |
|---|---|---|---|---|
| Price a month | $0 | $19 | $49 | $149 |
| Credits a month | 1,000 | 20,000 | 75,000 | 300,000 |
| Daily limit, in credits | 250 | 3,000 | 10,000 | 40,000 |
| Collections at once | 1 | 2 | 5 | 10 |
| Places per collection | 500 | 5,000 | 25,000 | 100,000 |
| Requests a minute | 30 | 120 | 300 | 600 |
| API keys | 2 | 5 | 10 | 20 |
| Email addresses | No | Yes | Yes | Yes |
| Webhooks | No | Yes | Yes | Yes |
When you reach one
| Limit | Answer | What to do |
|---|---|---|
| Credits a month | 429 QUOTA_EXCEEDEDdetails.scope: "month" | Buy a credit pack under Plan, or wait for the 1st. |
| Daily limit, in credits | 429 QUOTA_EXCEEDEDdetails.scope: "day" | Wait for midnight UTC. A pack won't help here. |
| Collections at once | 429 QUOTA_EXCEEDEDdetails.scope: "concurrency" | Wait for a collection to end, or cancel one. |
| Places per collection | 400 VALIDATION_ERROR | Ask for fewer with maxPlaces, or change plans. details.limit is your plan's most. |
| Requests a minute | 429 RATE_LIMIT_EXCEEDED | Wait the number of seconds in retry-after. |
| API keys | 409 CONFLICT | Revoke a key you don't use, or change plans. |
| Email addresses | 402 PLAN_GATE | Change to a plan that includes email addresses. |
| Webhooks | 402 PLAN_GATE | Change to a plan that includes webhooks. |
Email addresses also need you to accept the acceptable use policy. Until you do, asking for them answers 403 AUP_REQUIRED. Reading places doesn't fail without it: the emails field is just left out.
A search never fails for lack of credits. When you're out, or already running as many collections as your plan allows, it still answers with the places we saved, and collectionError says why it couldn't collect the rest.
A collection that's already running stops when it reaches either credit limit, and never charges past it. The places it delivered before that stay yours, and its stopReason says which limit stopped it: daily_cap or quota. See Collections.
The per-minute limit counts every call your account makes: with any of its keys, each MCP tool call, and the searches and collections you run in the console.
When limits start over
- Daily limit: every day at midnight UTC.
- Credits a month: on the 1st of each month at midnight UTC, whatever day you subscribed. Credits you didn't use don't carry over.
- Collections at once: the moment one of yours ends.
- Requests a minute: at the start of each minute on the clock.
GET /v1/usage gives the exact times, in dailyResetAt and resetAt.
Credit packs
A pack adds credits that never expire. They're spent only after your plan's credits for the month run out. A pack never raises the daily limit, so it lets you collect on more days, not more in one day. Buy one under Plan in the console.
| Credits | Price |
|---|---|
| 10,000 | $19 |
| 50,000 | $69 |
| 200,000 | $199 |
What never counts
Credits pay for new places: one for each new place a collection finds, and one more when it also finds an email address for that place. Places we already saved come back free, so they never count toward a credit limit.
Searching, quotes, exports and checking your usage are free too. They still count toward your requests a minute.
See where you stand
Call GET /v1/usage. It's free:
curl https://api.gmaps.dev/v1/usage \
-H "Authorization: Bearer $GMAPS_API_KEY"creditsRemaining: what you can still spend this month, pack credits included. The daily limit can stop you sooner.dailyCreditsUsedanddailyCreditCap: what you spent today, and the most you can.creditBalance: the pack credits you have left.dailyResetAtandresetAt: when the day and the month start over.keys: the same totals for each API key, revoked ones included, plus one for what you ran in the console.
That answer also carries an x-credits-remaining header, with the same number as creditsRemaining. Other calls don't send it. The console shows the same numbers under Usage.