Allowances, credit and limits

Every account gets a free daily allowance, shared by all of its keys. Past it, requests draw on prepaid credit or are covered by an Unlimited package. Every response tells you where you stand in its headers.

The daily allowance

The keyed allowance is per account, not per key: all of an account's pay-as-you-go keys draw on one 2,500 a day, so a second key adds no free requests. The keyless allowance is per address, and addresses in the same network (the same IPv4 /24 or IPv6 /48) share it. A network and the keys used from it draw on one allowance: requests without a key reduce what a key used from the same network gets that day, and the other way round, so the free 2,500 cannot be taken twice from one place. Credit is per account too and is used once the account's free allowance is gone. The day is the UTC calendar day; X-Quota-Reset carries the exact Unix time of the next reset. Calls without a key count per network wherever they come from, scripts on web pages included; to have a website's calls counted on your account instead, use a browser key for it. Any key can also have a daily spending limit set by its owner; past it, paid requests on that key get 429 key_daily_cap until the reset.

What counts as a request

• Every successful call (200) to any endpoint counts as one, whether or not it found anything.
• Each item in a bulk call counts as one request: every address in an IP batch, every point in a multi-point elevation or time zone call, every entry on the batch endpoints of the drop-in hosts. That is how the original providers count them too. A batch larger than what is left of the allowance is refused whole, before any work, with the provider’s own limit error rather than partly answered. Each host takes as many items per call as its original provider does (100 for ip-api and MapQuest, 50 for ipstack, 512 for Google elevation, 1,000 for ipinfo, Mapbox and Geoapify, 1,024 for Bing and Open-Elevation, 10,000 for Geocodio and TomTom’s asynchronous batch; 100 on the native endpoints). Fetching a stored asynchronous result counts nothing.
• Calls refused with 400, 401, 402, 403, 404 or 429 do not count and cost nothing.
• Calls that fail with 500 or 503 do not count and cost nothing.
• Loading the JavaScript drop-in libraries does not count. Their maps use OpenStreetMap tiles, which do not come from us.

IP slots

A key works from two IP addresses at a time (three for an Unlimited key). Each address holds its slot for 24 hours from its first request and then frees it. A request from a further address while all slots are held gets 403 key_ip_limit with the time the next slot frees. Details and examples are on the authentication page.

Bursts

There is no fixed requests-per-second limit today, with or without a key, apart from the 60 requests a minute per visitor on a browser key. Traffic that looks like a runaway loop or an attack may be slowed, and we will tell you if that happens to one of your keys. If you have a large job, use the batch forms (ips, locations) rather than thousands of single calls.

Reading the headers

x-quota-limit: 2500          # free per day for this account; -1 on an Unlimited key
x-quota-used: 2431           # counted today on this key, including this request
x-quota-free-remaining: 69   # free requests left today for the account
x-credits-remaining: 148200  # requests the account's credit still covers
x-key-ips-used: 1            # IP slots currently held on this key
x-key-ips-limit: 2           # slots on this key
x-quota-reset: 1789948800    # Unix time of the next 00:00 UTC
x-request-id: 2726386e38428697

Without a key, the answer carries X-Quota-Limit, X-Quota-Used (requests made today from your network without a key, including this one), X-Quota-Free-Remaining, X-Quota-Reset and X-Request-Id. X-Quota-Network-Used is added when the same network has also used free requests the other way today (with a key when you sent none, without one when you sent a key). A browser key gets no X-Key-IPs-* headers. X-Key-Grace-Until (Unix time) appears when an Unlimited package has expired and its key is in the grace period. A 429 also carries Retry-After in seconds.

Handling 402 and 403

{ "status": "error", "error": { "code": "no_credits", "message": "The account's free allowance of 2500 requests for today (shared by all its keys) is used and the account balance (€0.0000, 0 requests) does not cover this call, which needs 1 (one per item) and is refused whole. Add credit at https://www.mygeocode.com/dashboard or wait for the reset at 00:00 UTC." } }

Do not retry in a loop; the answer will be the same until credit is added or the day resets. Read X-Quota-Reset and either wait, fail the operation and tell the user, or top up. The dashboard emails you when credit runs low.

{ "status": "error", "error": { "code": "key_ip_limit", "message": "This key is already in use from 2 IP addresses in the last 24 hours (limit 2). The next slot frees at 2026-09-21 23:06 UTC. Use another key or an additional Unlimited package for more addresses." } }

This means a machine that is not one of the key's current slot holders tried to use it. Usually that is a new server or a redeploy with a new address; give that machine its own key.

Reducing requests

You may cache results indefinitely, and we recommend it. Addresses do not move; the same forward geocode tomorrow is the same answer. IP blocks change slowly; a day is a safe cache time. Timezone rules for a point change rarely and the IANA name essentially never. For autocomplete, debounce input to about 150 ms and stop sending once the user has picked a suggestion.