UK Data AtlasAPI

Concepts

Areas and boundaries

Boundaries in the UK change all the time. Wards are redrawn, councils merge and constituencies are reshaped. The API keeps track of exactly which version of an area you mean, so your data and your maps always match.

Area codes

Every official area has a code. Birmingham City Council is E08000025, and a code's first letter usually tells you the country: E for England, W for Wales, S for Scotland and N for Northern Ireland. Some Northern Ireland statistics use their own codes, like 95AA01S1.

Codes are the reliable way to name an area. Names aren't unique, but codes are.

Geographies

A geography is a kind of area. You'll see these most often:

GeographyWhat it is
wardElectoral wards, the building blocks of councils
localAuthorityCouncils, like Leeds or Cornwall
constituencyWestminster parliamentary constituencies
regionThe English regions, like the North West
lsoaSmall statistical areas in England and Wales
dataZoneSmall statistical areas in Scotland

List geographies returns every one the Atlas knows about.

Boundary releases

A boundary release is a dated snapshot of one geography's boundaries, as its publisher released them. Its id tells you what it is:

  • 2024-07-uk-bgc is the July 2024 release covering the UK.
  • The middle part is the coverage, such as uk, gb, ew (England and Wales), en or sc.
  • The last part is the publisher's boundary type: bgc is generalised and clipped to the coastline, and bfc is full resolution.
  • A year can have more than one release. Use the full id, including its month and coverage, when you need one exact set of shapes.

Not sure which release to use for a date? Find boundaries for a date picks the right one. The geography pages list every available release and its coverage.

Naming an exact area

Because the same code can appear in several releases, an area's full identity has three parts: its geography, its boundary release and its code. You'll see them together in URLs:

curl "https://api.ukdataatlas.com/v1/areas/constituency/2024-07-uk-bgc/E14001262"

Which areas data is on

Publishers release statistics against the area codes that were current when they made them. When you ask for data, you name that set of codes with two parameters:

  • geography: the kind of area the publisher used, such as ward.
  • boundaryYear: the year of the codes they used, such as 2023.

This doesn't choose which boundaries to draw. To put values on a map, add a release. The API only accepts one that contains every area code in the data, so nothing silently goes missing. Check which boundaries fit lists the releases that work.

Shapes

Shapes come back as GeoJSON in ordinary longitude and latitude (WGS 84). Full detail can be heavy, so geometry endpoints take a tier of full, high, medium or low. medium or low is usually right for web maps.

Useful endpoints

get/boundary-releasesList boundary releasesget/areas/{geography}/{release}/{code}Get an areaget/areas:validateCheck codes or namesget/areas/{geography}/{release}/{code}/geometryGet an area's shape