Quotas and limits

Each key has two limits: a monthly quota of calls, and a rate limit of 600 calls a minute. Each request is also stopped if its search takes too long.

The monthly quota

We set your key’s quota when we make it. It counts calls to every endpoint: /v1/scores, /v1/fields/{field_id} and /v1/usage.

Only answers count. A call that fails (a typo, an unknown postcode, a 404, a 422, a search that took too long) is given back. Calls refused for the key, the quota or the rate limit aren’t counted either.

The month is the calendar month in UTC. Your count starts again at 00:00 UTC on the 1st of each month. The quota holds exactly, even under load. Calls made at the same moment are counted one at a time, so they can’t go past it.

Seeing what’s left

Answers from /v1/scores, /v1/fields/{field_id} and /v1/usage carry two headers:

Header	Meaning
`X-Quota-Limit`	Calls allowed a month
`X-Quota-Remaining`	Calls left this month, after this one

Or ask /v1/usage. It doesn’t count as a call, and it still answers when the month’s calls are used up:

curl -H "Authorization: Bearer $CTF_KEY" "https://api.checkthatfield.com/v1/usage"

{
  "month": "2026-11",
  "calls": 1240,
  "quota": 10000,
  "remaining": 8760,
  "resets_at": "2026-12-01T00:00:00+00:00"
}

string

The calendar month counted, YYYY-MM, in UTC.

integer

Calls answered this month.

integer

Calls allowed a month.

integer

Calls left this month.

string

When the count starts again, in UTC.

When the quota runs out

Every call, /v1/usage included, gets 429 quota_exceeded until the month ends. The Retry-After header gives the seconds until 00:00 UTC on the 1st. If you need more calls, email hello@checkthatfield.com.

The rate limit

Each key may make 600 calls a minute. The count is kept in fixed one-minute windows. Past it, calls get 429 rate_limited, with a Retry-After header giving the seconds until the window ends.

On a 429, wait for Retry-After seconds before trying again. Calls made while limited still count towards the window, so retrying at once keeps you limited.

import time
import requests

def get(url, **kwargs):
    while True:
        r = requests.get(url, **kwargs)
        if r.status_code == 429 and r.json()["error"]["code"] == "rate_limited":
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        return r

Don’t retry quota_exceeded this way: its Retry-After can be weeks.

The 15-second cap

Each database query behind a request may take at most 15 seconds. A search that goes over is stopped and answered 503 too_slow, and isn’t counted against your quota. It is most likely around the edge of a big town or city, with a wide radius. To avoid it:

ask with a postcode or a point instead of a town’s name
use a smaller radius_m
ask for fewer fields with limit

Request bounds

Parameter	Default	Bounds
`radius_m`	500	50 to 1,000 metres
`limit`	20	1 to 60 fields
`postcode`		at most 20 characters
`q`		at most 200 characters
`lat`		49 to 61
`lng`		−10 to 3

Values outside these get 422 bad_request. /v1/scores returns at most 50 housing applications, newest first.

Partner API

Endpoints

The monthly quota

Seeing what’s left

When the quota runs out

The rate limit

The 15-second cap

Request bounds