API overview

The Check That Field API tells your server how likely the open fields near a place are to be built on for housing. It answers with the same things our free report shows, as JSON.

What you can ask for

Scores near a place

GET /v1/scores: the open fields around a postcode, a town or village, an address with a postcode, or a point. Nearest first, with nearby housing applications.

One field

GET /v1/fields/{field_id}: one field by the field_id the scores give, with the housing applications within 1 km.

Your usage

GET /v1/usage: your calls this month against your quota.

The Endpoints section of this tab lists each endpoint, every parameter and every field of the answers, and lets you try them.

The basics

Base URL: https://api.checkthatfield.com/v1
Format: JSON in every answer, errors included.
Versioning: the version is in the path. Everything here is /v1.
Keys: every call needs a secret key. See Authentication.
OpenAPI: the machine-readable description is at https://api.checkthatfield.com/v1/openapi.json.

What the answers include

Each field comes with:

its score, from 0 to 100
its band: Low (0–19), Moderate (20–44), High (45–69) or Very High (70–100)
two horizons: the likelihood of housing within about 5 and about 15 years
the top reasons behind the score, at most three, in words. Each says whether it raises or lowers the score and how much (strong, moderate, slight, or cap). There are no numbers.

The API gives what the free report gives. The sources, the records behind each reason and the full reasoning stay in the deep report on checkthatfield.com. Each field’s report_url links to it on our map.

A field we haven’t scored yet comes back as "status": "pending" and is queued for scoring. See Pending scores.

Your first request

curl -H "Authorization: Bearer $CTF_KEY" \
  "https://api.checkthatfield.com/v1/scores?postcode=HP18%209TH&limit=5"

import os
import requests

r = requests.get(
    "https://api.checkthatfield.com/v1/scores",
    params={"postcode": "HP18 9TH", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['CTF_KEY']}"},
    timeout=30,
)
r.raise_for_status()
for field in r.json()["fields"]:
    print(field["field_id"], field["status"], field["score"], field["band"])

// Server-side only (Node 18+). Never send a secret key to a browser.
const url = new URL("https://api.checkthatfield.com/v1/scores");
url.search = new URLSearchParams({ postcode: "HP18 9TH", limit: "5" });

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CTF_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { fields } = await res.json();

Call the API from your server. A secret key in a web page or app can be read by anyone. To show scores in a page, use the widget.

A response, trimmed

{
  "centre": { "point": [-1.0731, 51.7512], "from": "postcode", "place": null },
  "radius_m": 500,
  "model_version": "0.4.0",
  "fields": [
    {
      "field_id": 7341642,
      "inspire_id": 54712093,
      "distance_m": 140,
      "area_ha": 3.2,
      "council": { "code": "E06000060", "name": "Buckinghamshire" },
      "point": [-1.0702, 51.7525],
      "status": "scored",
      "score": 52,
      "band": "High",
      "horizons": { "five_year": 38, "fifteen_year": 57 },
      "reasons": [
        { "label": "Allocated for housing in the Local Plan", "direction": "up", "strength": "strong" },
        { "label": "Adjacent to a settlement boundary", "direction": "up", "strength": "moderate" },
        { "label": "Partly in a flood zone", "direction": "down", "strength": "slight" }
      ],
      "scored_at": "2026-11-02T09:14:00Z",
      "report_url": "https://www.checkthatfield.com/map?fields=7341642&at=-1.07020,51.75250,16"
    }
  ],
  "applications": [
    {
      "council": "Buckinghamshire",
      "reference": "24/01234/OUT",
      "address": "Land off Church Lane",
      "description": "Outline application for up to 40 homes",
      "type": "outline",
      "homes": 40,
      "status": "decided",
      "decision": "refused",
      "received_date": "2024-03-11",
      "decision_date": "2024-09-02",
      "distance_m": 420,
      "located_by": "published",
      "url": "https://publicaccess.example.gov.uk/…"
    }
  ],
  "attribution": ["…"]
}

Points are [longitude, latitude]. Distances are in metres: from the postcode or point, or from the edge of the built-up area when you ask about a town or village.

Authentication

Get a key and send it.

Quotas and limits

What counts, and how fast you can call.

Errors

Every error code and what to do.

Attribution

What you must show beside the data.

Partner API

Endpoints

What you can ask for

Scores near a place

One field

Your usage

The basics

What the answers include

Your first request

A response, trimmed

Next

Authentication

Quotas and limits

Errors

Attribution