Get started
Quickstart
Five requests that take you from a place name to real numbers. There's nothing to install and no key to set up: every request is a plain GET, so you can paste any of these URLs straight into your browser.
How responses look
Every successful response wraps its result in data, alongside atlasRelease, which identifies the exact version of the data you got. Responses explains the rest.
Search for a place
Most questions start with a place. Search for one by name to see which official areas it could mean:
curl "https://api.ukdataatlas.com/v1/places?q=Bristol"Response200 { "apiVersion": "v1", "atlasRelease": "sha256:24a500c55416bd7d58c28b1fc8cc4931d4a2fd831addafa3116556a91f2c4857", "data": { "query": "Bristol", "candidates": [ { "place": "localAuthority/E06000023", "kind": "area", "name": "Bristol, City of", "geography": "localAuthority", "code": "E06000023", "match": "exact-without-title", "boundaryReleases": [ "2025-12-uk-bgc", "2023-05-uk-bgc-v2" ] }, { "place": "majorTownAndCity/J01000015", "kind": "area", "name": "Bristol", "geography": "majorTownAndCity", "code": "J01000015", "match": "exact", "boundaryReleases": [ "2015-12-ew-bgc" ] } ] }, "meta": { "nextCursor": null } }"Bristol" is both a council and a major town, so you get both. Each has a
code(likeE06000023), itsgeography(the kind of area) and aplacereference you can use in later requests.Ask a question
For a quick answer, give a measure and a place. Here's the population of the North West in 2022:
curl "https://api.ukdataatlas.com/v1/data/population/value?place=North%20West&period=2022"Response200 { "apiVersion": "v1", "atlasRelease": "sha256:24a500c55416bd7d58c28b1fc8cc4931d4a2fd831addafa3116556a91f2c4857", "data": { "measure": { "id": "population", "label": "Population estimate", "valueKind": "count", "unit": "people" }, "question": { "place": "North West", "period": "2022", "placeDefaulted": false }, "answer": { "period": "2022", "periodDefaulted": false, "status": "derived", "value": 7526285, "unit": "people" }, "place": { "place": "location/north-west", "kind": "named-location", "name": "North West", "geography": "named-location", "code": "north-west", "match": "exact" }, "method": "aggregate", "via": "/v1/data/population/aggregate?place=location/north-west&geography=localAuthority&boundaryYear=2023&period=2022", "otherMatches": [ { "place": "region/E12000002", "kind": "area", "name": "North West", "geography": "region", "code": "E12000002", "match": "exact", "served": false, "reason": "population is not published for region areas." } ] }, "meta": { "nextCursor": null } }The
answerholds the number.viashows the exact request that produced it, so you can always see how it was worked out.See what's available
A measure is something that's counted or measured, like
populationormedian-annual-pay. List them all to see their units, coverage and whether they can be added up:curl "https://api.ukdataatlas.com/v1/measures"Get values for areas
To fetch data yourself, ask for a measure, a
periodand the set of areas it was published on. That set is named bygeographyandboundaryYear: here, wards as they were coded in 2023.curl "https://api.ukdataatlas.com/v1/data/population?period=2022&geography=ward&boundaryYear=2023&place=E05000932"Response200 { "apiVersion": "v1", "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "data": { "measure": { "id": "population", "label": "Population estimate", "valueKind": "count", "unit": "people", "aggregation": { "kind": "extensive", "operation": "sum", "available": true }, "sources": [ { "datasetId": "population", "periods": [ "2022" ], "sourceGeography": { "type": "ward", "boundaryYear": 2023 }, "coverage": { "kind": "partial", "countries": [ "GB-ENG" ], "recordCount": 7608, "note": "Published source records are available for England and Wales only; this endpoint does not infer Scottish or Northern Irish values." } } ], "availability": { "sourceExact": true, "conversion": false, "aggregation": true }, "links": { "data": "/v1/data/population" } }, "source": { "datasetId": "population", "periods": [ "2022" ], "sourceGeography": { "type": "ward", "boundaryYear": 2023 }, "coverage": { "kind": "partial", "countries": [ "GB-ENG" ], "recordCount": 7608, "note": "Published source records are available for England and Wales only; this endpoint does not infer Scottish or Northern Irish values." } }, "period": "2022", "sourceGeography": { "type": "ward", "boundaryYear": 2023 }, "provenance": { "atlasRelease": { "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "href": "/v1/atlas-release" }, "measure": { "id": "population", "href": "/v1/measures/population" }, "geography": { "source": { "type": "ward", "boundaryYear": 2023 }, "match": { "status": "no-boundary-release-selected", "note": "The published observations declare a geography type and code vintage, but not a boundary release." } }, "transformation": { "status": "not-applied", "note": "Values are served source-exact; no geographic conversion or aggregation was applied." }, "source": { "dataset": { "id": "population", "href": "/v1/datasets/population" }, "observations": { "artifact": "population-observations", "contentHash": "sha256:af1de02a052ace448dfb92c80cc312118a16c30bc77bf7a8c4d0e24a24ddab18", "period": "2022" } } }, "conversion": null, "aggregation": null, "records": [ { "areaCode": "E05000932", "value": 12676, "status": "observed" } ] }, "meta": { "nextCursor": null } }Leave out
placeto get every ward, a page at a time. Pagination shows how to fetch the rest.Follow an area over time
Ask for one area's series to get every period at once, ready for a chart. This is Birmingham:
curl "https://api.ukdataatlas.com/v1/data/population/series?place=E08000025&geography=localAuthority&boundaryYear=2023"Response200 { "apiVersion": "v1", "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "data": { "measure": { "id": "population", "label": "Population estimate", "valueKind": "count", "unit": "people", "aggregation": { "kind": "extensive", "operation": "sum", "available": true }, "sources": [ { "datasetId": "population", "periods": [ "2022" ], "sourceGeography": { "type": "ward", "boundaryYear": 2023 }, "coverage": { "kind": "partial", "countries": [ "GB-ENG" ], "recordCount": 7608, "note": "Published source records are available for England and Wales only; this endpoint does not infer Scottish or Northern Irish values." } } ], "availability": { "sourceExact": true, "conversion": false, "aggregation": true }, "links": { "data": "/v1/data/population" } }, "source": { "datasetId": "population-uk", "periods": [ "2011" ], "sourceGeography": { "type": "localAuthority", "boundaryYear": 2023 }, "coverage": { "kind": "source-reported", "countries": [ "GB-ENG" ], "recordCount": 361, "note": "Published source records cover all four UK nations for every available period. Historic values remain keyed to the source's 2023 local-authority code vintage." } }, "areaCode": "E08000025", "sourceGeography": { "type": "localAuthority", "boundaryYear": 2023 }, "provenance": { "atlasRelease": { "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "href": "/v1/atlas-release" }, "measure": { "id": "population", "href": "/v1/measures/population" }, "geography": { "source": { "type": "localAuthority", "boundaryYear": 2023 }, "match": { "status": "no-boundary-release-selected", "note": "The published observations declare a geography type and code vintage, but not a boundary release." } }, "transformation": { "status": "not-applied", "note": "Values are served source-exact; no geographic conversion or aggregation was applied." }, "source": { "dataset": { "id": "population-uk", "href": "/v1/datasets/population-uk" }, "observations": { "artifact": "population-local-authority-observations", "contentHash": "sha256:1bf9e38cc9c37b37492b4a3cdc6b28c28ddeb5c2adc81e838ef947d78a0c0a9b", "periods": [ "2011" ] } } }, "series": [ { "period": "2011", "areaCode": "E08000025", "value": 1074283, "status": "observed" } ] }, "meta": { "nextCursor": null } }
That's the core of it. From here: