Usage and limits

Units

A unit is a response with status 200. All routes cost the same. A response with an error costs no unit, and Get dataset details costs no unit.

These responses also have status 200, so each one costs one unit:

• An autocomplete or a search that finds no city.
• An autocomplete or a search with a text of fewer than 2 characters. The API returns no cities for this text.
• A reverse lookup that finds no city. data is null.

The dashboard shows the units of each day of the month.

Estimate your units

Count the requests that each feature sends:

A city field that waits for a pause in the typing sends a few requests for each city, and not one for each letter. Add city autocomplete to a form shows this delay.

Monthly limit

Each plan gives a number of units for each month. The month starts at 00:00 UTC on the first day.

The API accepts requests up to 120% of the plan units, at the same price. Above this limit, the API returns status 429 with the error quota_exceeded until the next month. The Retry-After header gives the number of seconds until the next month.

If a batch reverse lookup has more positions than the units left in the month, the API refuses the full batch. The detail of the error gives the units left.

Requests per second

Each plan sets a limit of requests per second for the account. The limit applies to all keys of the account together. A batch reverse lookup counts as one request for this limit.

A public key also has a limit of 10 requests per second for each IP network. This limit stops one visitor from using all the requests of the account.

Above a limit of requests per second, the API returns status 429 with the error rate_limited. The Retry-After header gives the number of seconds to wait.

Handle status 429

Read the code of each response with status 429:

• If the code is rate_limited, wait for the seconds in Retry-After. Then send the request again.
• If the code is quota_exceeded, do not send the request again before the next month.

This function sends a request up to 3 times. After each rate_limited error, it waits for the seconds in Retry-After.

const MAX_ATTEMPTS = 3

async function requestCityApi(url, options) {
  for (let attempt = 1; ; attempt += 1) {
    const response = await fetch(url, options)
    if (response.status !== 429 || attempt === MAX_ATTEMPTS) {
      return response
    }
    const problem = await response.clone().json()
    if (problem.code !== 'rate_limited') {
      return response
    }
    const seconds = Number(response.headers.get('Retry-After'))
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
  }
}

A browser can read Retry-After, because the API sends it in Access-Control-Expose-Headers.

Your form must work also when the API refuses a request. If the city field gets no cities, let the person type the city as text. Accept text with no selection tells how to find the city later.