Rate Limits

All Geocode Earth APIs are behind rate limiting infrastructure.
Geocode Earth has several types of rate limits:

Per-second rate limits (hard) #

Per-second rate limits are designed to protect our servers from momentary spikes in requests. These rate limits are strictly enforced and are not averaged over multiple seconds.

In the event that you send more requests than your rate limits allow, we will return an HTTP 429 status code. You will almost certainly want to ensure that your code gracefully handles these responses (see Handling 429s below).

Don’t worry about sending excessive requests that result in 429s. Trust us, our rate limiting infrastructure can handle it.

Per-day rate limits (hard, trial only) #

Trial plans have per-day rate limits that are also strictly enforced. We hope that if you are regularly hitting these per-day limits that you will find one of our paid plans to be of value.

Per-day rate limits reset at 00:00 GMT.

Per-month rate limits (soft) #

All Geocode Earth plans include a monthly limit on requests. These are soft limits, in that you will not immediately be cut off when you reach the limit.

Here’s our policy on going over your monthly limit:

  • 80% usage: You'll receive a usage status email.
  • 100% usage: You'll receive a usage status email. If you routinely exceed 100% usage we may reach out to you about moving to a larger plan.
  • 110% usage: You'll receive a usage status email, and the per-second request limits on your account will be reduced by 50%.
  • 120% usage: You'll receive a usage status email, and you will no longer be able to send requests to our service.

Requests sent after you’ve exceeded your soft limit will return HTTP 403 status codes.

Monthly limits are counted over each billing cycle, so it will reset on the same day every month. You can view your billing cycle start date on the billing page of the Geocode Earth dashboard.

See your per-second rate limits in responses #

Per-second and per-day rate limits are included in the headers of all responses from Geocode Earth.

Shell Ruby Node.js Python
curl -s -I "https://api.geocode.earth/v1/search?text=london&api_key=<YOUR API KEY>" \
  | grep -i 'X-Ratelimit-Remaining'
# x-ratelimit-remaining-second: 10

require 'net/http'

api_key = '<YOUR API KEY>'
uri = URI("https://api.geocode.earth/v1/search?text=london&api_key=#{api_key}")
res = Net::HTTP.get_response(uri)

puts res['X-Ratelimit-Remaining-Second'] # 10

const https = require('https');

const api_key = '<YOUR API KEY>';
const url = `https://api.geocode.earth/v1/search?text=london&api_key=${api_key}`;

const req = https.get(url, (res) => {
  console.log(res.headers['x-ratelimit-remaining-second']); // 10
}).end();

import urllib.request

api_key = '<YOUR API KEY>'

response = urllib.request.urlopen(
  "https://api.geocode.earth/v1/search?text=london&api_key=" + api_key
)

print(response.headers['X-Ratelimit-Remaining-Second']) # 10

See your monthly usage in the dashboard #

You can view details about your usage of our service over time on the usage page of the Geocode Earth dashboard.

The usage page shows a breakdown of requests by endpoint and response code, and time.

Handling 429 HTTP Responses #

How best to handle rate limited responses depends on your use case.

In general, retrying requests when seeing 429 status codes is a good approach. It may make sense to briefly pause after seeing a 429, or check the X-Ratelimit-Remaining-Second header value to determine when you are getting close to your per-second limits.

Retrying makes the most sense for non-time-sensitive workloads, such as working through a large collection of addresses that need to be geocoded.

For real-time queries, such as an Autocomplete request, it may not make sense to retry: if another request has been generated in the meantime (for example, because the user has typed another character into the input box), its best to wait for the newer request to complete, and avoid retrying the older request.