Skip to main content
We don’t score every field in England in advance. When you ask about a field we haven’t scored yet, we queue it for scoring and answer straight away with what we have.

The three statuses

Each field in an answer has a status: /v1/scores only returns open fields, so its fields are always scored or pending. You’ll see not_open_land only from /v1/fields/{field_id}, when you ask about a piece of land that isn’t an open field, such as a garden. Treat it as having no score.

What happens when you ask

1

You ask

You call /v1/scores or /v1/fields/{field_id}, and an open field in the answer has no score.
2

We queue it, once

We queue the field for scoring. Asking again, by you or anyone else, doesn’t queue it a second time while it waits.
3

It is scored

Scoring usually takes a few minutes. API requests wait behind people using our site, so it can take longer when we’re busy.
4

You ask again

The field comes back scored, with its score, band, horizons and reasons.
A call with pending fields is still an answer, so it counts against your quota. Each time you ask again counts too. Poll sparingly.
Scores belong to a scoring model, named in model_version. When we bring in a new model, fields not yet scored under it come back pending again until they are.

Asking again

Wait a minute or two, then back off. Ask only about the fields still pending, with /v1/fields/{field_id}, rather than repeating the whole search.
In your own product, show a pending field as “being checked” and let the reader come back, rather than holding a page open while you poll.

If a field stays pending

Now and then scoring fails. A field whose scoring failed in the last day isn’t queued again on every request, so it stays pending for a while. After a day, asking about it queues it again. If a field stays pending for longer than that, email hello@checkthatfield.com with its field_id.