My Geocode

Authentication

There are three ways to call the API: with nothing, from a whitelisted IP address, or with an API key. They differ in who gets counted and billed, not in what you can do. Every endpoint, every field and every drop-in host is available on all three.

No key: the free tier

Send a request with no key from any address and it is counted against that address. Each IPv4 address gets 2,500 requests a day across all endpoints and hosts; the counter resets at 00:00 UTC. IPv6 traffic is counted per /40 block, for reasons explained on the rate limits page.

When the allowance is used up, further requests that day return 429 with the code quota_exceeded and X-Quota-Reset tells you when it comes back. Nothing is ever billed to an anonymous caller.

$ curl -i "https://api.mygeocode.com/v1/ipv4"
HTTP/2 200
x-quota-limit: 2500
x-quota-used: 41
x-quota-reset: 1756339200

Creating an account

An account needs an email address. That is the whole form: no name, no company, no card. You can whitelist addresses and create keys straight away, and your account gets the same 2,500 free requests a day. Add credits when you want to go past that, by card or in crypto, or subscribe to the Unlimited plan. Nothing is charged until you choose to.

IP whitelist

In the dashboard, add the public IP addresses your servers make requests from: individual IPv4 addresses, or IPv6 addresses and blocks down to a /64. From then on, requests from those addresses with no key are attributed to your account: the first 2,500 a day across the whole account are free, then paid from your credit balance or covered by the Unlimited plan.

This is the recommended way for servers because there is no secret in your code and, with credits, no limit on the number of servers. On the Unlimited plan, whitelisted addresses count toward that plan's two addresses per 24 hours. It is also the only way to attach usage from clients that cannot send a custom header or parameter, such as some Nominatim client libraries used with the osm.mygeocode.com host.

Whitelist changes take effect within a minute. An address can be on one account's whitelist at a time.

API keys

Create keys in the dashboard. Send one either as a header or as a query parameter:

$ curl -H "X-API-Key: mg_live_7Qk3...e9Xa" "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12"

$ curl "https://api.mygeocode.com/v1/reverse?lat=51.5&lon=-0.12&key=mg_live_7Qk3...e9Xa"

Prefer the header. Query strings are written to web server logs, browser histories and proxies.

On the drop-in hosts, the key goes wherever the original provider's key went: key for Google and Bing, apiKey for HERE and Geoapify, access_token for Mapbox, token for ipinfo, and so on. The X-API-Key header works on every host as well.

The two IP rule

A key can be used from at most two distinct IP addresses in any rolling 24 hour period. The first two addresses to use the key are recorded. A request with that key from a third address is refused with 403 and the code key_ip_limit until one of the recorded addresses has not been seen for 24 hours, at which point its slot frees up.

The rule exists because keys leak. They end up in public repositories, in client bundles and in screenshots. With this rule a leaked key is worth very little to whoever finds it, and it cannot run up your bill from a botnet. It also means keys are for servers, not for fleets or for browsers:

The refused requests are not counted and not billed. The dashboard shows which addresses are currently holding a key's two slots.

Keys and browsers

Do not put an account key in JavaScript or in a mobile app. Every visitor is a new IP address, so the third visitor would be refused, and anyone can read the key out of the page. Instead:

Revoking and rotating

Revoke a key in the dashboard and it stops working within a minute. Create the new key first, deploy it, then revoke the old one; both work in the meantime. Keys never expire on their own.

Which one is counted?

If a request carries a valid key, the key's account is counted, regardless of the source address. If there is no key and the source address is on a whitelist, that account is counted. Otherwise the source address is counted anonymously. A request with an invalid or revoked key is refused with 401 rather than falling back to anonymous, so a misconfiguration is visible rather than silent.

Plans and authentication

Credits and Unlimited use the same keys and whitelists. What changes is what happens after 2,500 requests in a day: on credits, one credit per request; on Unlimited, nothing. The other difference is the address limit. On Unlimited, the whole account may be used from at most two IP addresses in any 24 hour period, by key or whitelist, and a request from a third address is refused with 403 account_ip_limit. If you need more addresses than that, credits are the plan for you.