UK Data AtlasAPI

Using the API

Responses

Every JSON response has the same simple shape, so once you've read one, you can read them all.

The envelope

Successful JSON responses look like this:

Response
{
  "apiVersion": "v1",
  "atlasRelease": "sha256:9377970cfffdd2f92b153ba2ac76190812fc8925f5d65498d0e5149dfc0b1b5d",
  "data": {
    "…": "the result you asked for"
  },
  "meta": {
    "nextCursor": null
  }
}
FieldWhat it holds
dataThe result you asked for. Its shape is shown on each endpoint's page.
atlasReleaseThe Atlas release that produced this response.
meta.nextCursorThe cursor for the next page, or null if this is the last. See Pagination.
apiVersionAlways v1 for this version of the API.

Reading a response

Data responses also explain themselves. Look inside data and you'll typically find:

  • The measure, with its unit and whether it can be added up.
  • Which areas and period the values describe.
  • provenance, linking the values to their source dataset, and stating plainly whether anything was transformed.
  • coverage, saying which nations or areas are included, and why any aren't.

If you're building something people will rely on, store atlasRelease with your results. It lets you reproduce them exactly.

Files and tiles

A few endpoints return a file rather than an envelope: whole dataset downloads, lookup tables, vector tiles, the tile archive and the OpenAPI spec. Each says so on its reference page.

Errors are never wrapped in the envelope either. They have a shape of their own, described in Errors.