> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkthatfield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Scores for England's fields, around a postcode, place, address or point, as JSON for your server.

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

> [card] 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.

> [card] One field
>
> `GET /v1/fields/{field_id}`: one field by the `field_id` the scores give, with the housing applications within 1 km.

> [card] 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](https://docs.checkthatfield.com/api/authentication.md).
* **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.

> [!NOTE]
>
> 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](https://www.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](https://docs.checkthatfield.com/api/pending-scores.md).

## Your first request

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

```python Python theme={null}
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"])
```

```javascript JavaScript theme={null}
// 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();
```

> [!WARNING]
>
> 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](https://docs.checkthatfield.com/widget/overview.md).

## A response, trimmed

```json theme={null}
{
  "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.

## Next

> [card] [Authentication](https://docs.checkthatfield.com/api/authentication.md)
>
> Get a key and send it.

> [card] [Quotas and limits](https://docs.checkthatfield.com/api/quotas-and-limits.md)
>
> What counts, and how fast you can call.

> [card] [Errors](https://docs.checkthatfield.com/api/errors.md)
>
> Every error code and what to do.

> [card] [Attribution](https://docs.checkthatfield.com/api/attribution.md)
>
> What you must show beside the data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.