Credits & Quotas

Your quota is expressed in credits, not requests. Every endpoint has a weight reflecting its compute cost: a geocode debits 1 credit, a point-to-point route 2, an isochrone 10. You spend your credit envelope on whatever mix of endpoints you need.

Credit weights

Endpoint	Cost in credits
GET /v1/geocode	1 per call, limit has no effect
GET /v1/reverse	1 per call
GET /v1/autocomplete	1 per call, limit has no effect
GET /v1/nearest	1
GET /v1/route	2
GET /v1/elevation	2
GET /v1/isochrone	10
POST /v1/match	1, plus 1 per started block of 25 points beyond the first 25
POST /v1/matrix	1 per started block of 25 elements (sources × targets)
POST /v1/batch/geocode	1 per address, debited at submission; failed lines refunded

Per call, not per result

For the search endpoints (/v1/geocode, /v1/reverse, /v1/autocomplete), the weight is debited once per call, whatever limit you ask for. A limit=20 autocomplete costs exactly the same 1 credit as a limit=1: X-RateLimit-Monthly-Remaining goes down by 1 in both cases. Autocomplete queries several regional engines in parallel; that fan-out is not billed per region either.

Sizing consequence: over-sampling is free. If you filter, deduplicate or re-rank results on your side, ask for the largest limit that is useful and keep the ones you want; the credit cost does not move. Only the response body gets bigger. What drives consumption is the number of calls: on a search-as-you-type box, debounce the input and skip queries below three characters rather than lowering limit.

Only the endpoints below have a cost that grows with the request itself.

Size-dependent costs, worked out:

• Match: a GPS trace of up to 25 points costs 1 credit; 26 to 50 points cost 2; 51 to 75 cost 3... A 100-point trace costs 4 credits.
• Matrix: elements = sources × targets. A 2×3 matrix (6 elements) costs 1 credit; a 10×10 (100 elements) costs 4; a 25×25 (625 elements) costs 25.
• Batch: 1,000 addresses cost 1,000 credits at submission; if 40 lines fail, 40 credits come back when the job completes.

Map tiles are metered separately

Vector tiles (tiles.geocodeme.net) have their own per-plan counters (tiles per month) and do not consume credits; a map view loads dozens of tiles at once and would otherwise exhaust any credit envelope.

Quota windows

Paid plans get a monthly credit envelope. The Free plan is metered on a daily window instead:

Plan	Credit envelope	Window resets
Free	3,000 credits / day	Every midnight UTC
Startup	150,000 credits / month	1st of the month, 00:00 UTC
Growth	500,000 credits / month	1st of the month, 00:00 UTC
Pro	1,500,000 credits / month	1st of the month, 00:00 UTC

Quotas are counted per account: every API key of the same account draws from the same envelope. See current pricing for plan prices, and Rate Limiting for the per-second request limits (enforced independently of credits).

Plan capabilities

Beyond volume, plans gate which features are available:

Capability	Free	Startup	Growth	Pro
Routing profiles	car	car, bike, foot	all (+ truck, moto)	all (+ truck, moto)
Isochrone: max minutes	✗	30	60	120
Matrix: max size	✗	25×25	50×50	100×100
Elevation	✗	✓	✓	✓
Batch geocoding	✗	✗	✓	✓
Vector tiles	✗	✓	✓	✓

Profiles apply to /v1/route, /v1/match, /v1/nearest, /v1/matrix, and /v1/isochrone.

When credits are (and are not) debited

• Debited: every successfully served request, at its endpoint's weight.
• Never debited: requests the API refuses upfront: plan gates (403), request validation (400 on malformed parameters), rate limiting and quota refusals (429). A request we reject ourselves costs nothing.
• Debited: 400 errors raised by the routing engine after validation (for example, a coordinate that cannot be snapped to the road network); the computation did run.
• Automatically refunded: any server-side failure (5xx); the debit is reversed before the response leaves the API. Batch jobs additionally refund every failed line on completion.

Tracking your consumption

Every response carries the quota headers described in Rate Limiting:

X-RateLimit-Monthly-Limit: 150000
X-RateLimit-Monthly-Remaining: 148236
X-RateLimit-Monthly-Reset: 1754006400

note

The Monthly-* names describe the active window, whatever its length: on the Free plan they report today's daily window (limit 3,000, reset at next midnight UTC).

X-RateLimit-Monthly-Warning: true is added once 80% of the window is consumed (the header is absent below the threshold), a good trigger for an alert on your side (you also receive an email).

Quota and plan errors

403 PLAN_UPGRADE_REQUIRED

Returned when the request asks for a capability outside your plan (profile, feature flag, or a value above your cap). Nothing is debited.

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "Your plan allows up to 30 minutes. Upgrade to raise the limit.",
    "field": "minutes",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

429 QUOTA_EXCEEDED

Returned when the window cannot cover the request's cost. quota_reset is the Unix timestamp of the next window reset (next midnight UTC on Free, 1st of the month on paid plans).

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Quota exceeded. Upgrade your plan to continue.",
    "quota_reset": 1753056000,
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

tip

Requests with a size-dependent cost (match, matrix, batch) are refused whole if the remaining window cannot cover them; a batch of 1,000 addresses needs 1,000 available credits upfront. Submit large jobs early in your window, or split them.

For the full error reference, see Error Codes.