Guide

Find the areas most in need

Deciding where to open a service, target a grant or send outreach workers? Find the most deprived neighbourhoods in a council area, count the people who live in them and put them on a map, without averaging numbers that can't be averaged.

List the neighbourhoods

England's Index of Multiple Deprivation ranks small neighbourhoods called LSOAs, each home to about 1,500 people. A council is far too large to target, so start from its LSOAs. Leeds has 488:

curl "https://api.ukdataatlas.com/v1/areas/localAuthority/2023-05-uk-bgc-v2/E08000035/children?childGeography=lsoa"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "id": "localAuthority/2023-05-uk-bgc-v2/E08000025",
    "geography": "localAuthority",
    "boundaryRelease": "2023-05-uk-bgc-v2",
    "code": "E08000025",
    "name": "Birmingham",
    "relationships": [
      {
        "relation": "contains",
        "counterpart": {
          "id": "ward/2023-05-uk-bgc/E05011118",
          "geography": "ward",
          "boundaryRelease": "2023-05-uk-bgc",
          "code": "E05011118",
          "labels": [
            "Acocks Green"
          ]
        },
        "crosswalk": {
          "id": "ward-2023-05-uk-bgc-to-local-authority-2023-05-uk-bgc-v2-clean-containment",
          "method": "clean-containment",
          "quality": "publisher-supplied",
          "weighting": {
            "status": "not-applicable"
          }
        }
      }
    ]
  },
  "meta": {
    "nextCursor": null
  }
}

Each entry in relationships has the LSOA's code and name. The list comes from the official LSOA-to-council lookup, which is published against the May 2023 council boundaries, hence that release.

Get every decile at once

Rather than asking 488 times, download the whole index once. It's about 2 MB and covers every LSOA in England:

curl "https://api.ukdataatlas.com/v1/exports/imd-decile-observations"

Example response200

{
  "schemaVersion": 1,
  "measureId": "total-jobs"
}

Keep the Leeds rows and count how many fall in each decile. Decile 1 is the most deprived tenth of LSOAs in England.

const API = "https://api.ukdataatlas.com/v1";
const get = (path) => fetch(API + path).then((r) => r.json());

// Leeds's neighbourhoods
const { data } = await get("/areas/localAuthority/2023-05-uk-bgc-v2/E08000035/children?childGeography=lsoa");
const leeds = new Set(data.relationships.map((r) => r.counterpart.code));

// Every neighbourhood's decile, in one file
const imd = await get("/exports/imd-decile-observations");
const deciles = new Map(
  imd.periods[0].records
    .filter((r) => leeds.has(r.areaCode))
    .map((r) => [r.areaCode, r.value]),
);

// How many neighbourhoods fall in each decile
const counts = {};
for (const decile of deciles.values()) counts[decile] = (counts[decile] ?? 0) + 1;

const mostDeprived = [...deciles].filter(([, d]) => d === 1).map(([code]) => code);

Summarise without averaging
An average decile for Leeds would be a number with no meaning, because a decile is a band of ranks. Ask for one and the API refuses with aggregation_not_supported:
curl "https://api.ukdataatlas.com/v1/data/imd-decile/value?period=2025&geography=lsoa&codeYear=2021&place=E08000035"
Report the share of neighbourhoods in each decile instead. In Leeds, 84 of 488 are in the most deprived tenth nationally, about one in six.
Count the people
A count of neighbourhoods hides how many people are affected. Census 2021 resident counts add up across areas, so total them over the decile 1 LSOAs. The census export is a table: measures names the columns, and each row is a code followed by one value per measure.
```
const table = await get("/exports/usual-residents-total-lsoa-2021");
const column = table.measures.indexOf("usual-residents-total") + 1;
const residents = new Map(table.records.map((row) => [row[0], row[column]]));

const people = mostDeprived.reduce((sum, code) => sum + residents.get(code), 0);
```
For Leeds that's about 145,000 people. The census was taken in 2021 and the index is from 2025, so say which year each figure comes from.

Map them

Fetch every LSOA's shape in one request, then colour each feature by its decile, matching on properties.code:

curl "https://api.ukdataatlas.com/v1/areas/localAuthority/2023-05-uk-bgc-v2/E08000035/children/geometry?childGeography=lsoa&tier=medium"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:24a500c55416bd7d58c28b1fc8cc4931d4a2fd831addafa3116556a91f2c4857",
  "data": {
    "type": "FeatureCollection",
    "id": "localAuthority/2023-05-uk-bgc-v2/E08000025/children",
    "parent": {
      "id": "localAuthority/2023-05-uk-bgc-v2/E08000025",
      "geography": "localAuthority",
      "boundaryRelease": "2023-05-uk-bgc-v2",
      "code": "E08000025",
      "name": "Birmingham"
    },
    "collection": {
      "members": 69,
      "withGeometry": 69,
      "vertices": 314,
      "tier": "low",
      "toleranceM": 1000,
      "minEffectiveAreaM2": 1000000
    },
    "withoutGeometry": [],
    "features": [
      {
        "type": "Feature",
        "id": "ward/2023-05-uk-bgc/E05011118",
        "properties": {
          "id": "ward/2023-05-uk-bgc/E05011118",
          "geography": "ward",
          "boundaryRelease": "2023-05-uk-bgc",
          "code": "E05011118",
          "name": "Acocks Green",
          "membership": {
            "id": "ward-2023-05-uk-bgc-to-local-authority-2023-05-uk-bgc-v2-clean-containment",
            "method": "clean-containment",
            "quality": "publisher-supplied"
          },
          "generalisation": {
            "vertices": 5,
            "verticesAtFullResolution": 32,
            "parts": 1,
            "partsAtFullResolution": 1
          },
          "geometrySource": {
            "sourceCrs": "EPSG:27700",
            "transformation": {
              "name": "OSGB36 to WGS 84 (6)",
              "epsg": "EPSG:1314",
              "accuracyM": 2
            }
          }
        },
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                -1.8,
                52.44
              ],
              [
                -1.82,
                52.45
              ]
            ]
          ]
        }
      }
    ]
  },
  "meta": {
    "nextCursor": null
  }
}

Check that collection.withGeometry equals collection.members. At tier=low, any LSOA smaller than about a square kilometre is left out, and in a city that's most of them. medium keeps them all.

Credit the sources

The index is published by the Ministry of Housing, Communities and Local Government, and the census by ONS. Print the attribution beside your map:

curl "https://api.ukdataatlas.com/v1/attribution?measure=imd-decile&measure=usual-residents-total"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "atlasRelease": {
      "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
      "href": "/v1/atlas-release"
    },
    "resources": [
      {
        "kind": "dataset",
        "id": "ghg-emissions",
        "label": "Greenhouse Gas Emissions",
        "href": "/v1/datasets/ghg-emissions",
        "publisher": "Department for Energy Security and Net Zero",
        "sourceUrl": "https://www.gov.uk/government/statistics/uk-local-authority-and-regional-greenhouse-gas-emissions-statistics-2005-to-2024",
        "licence": {
          "name": "Open Government Licence v3.0",
          "url": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
        }
      }
    ],
    "licences": [
      {
        "name": "Open Government Licence v3.0",
        "url": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
      }
    ],
    "note": "Licence names are reproduced as the publisher states them and are not interpreted here. Where several apply, check each before reusing the combined work."
  },
  "meta": {
    "nextCursor": null
  }
}

Working outside England? Wales, Scotland and Northern Ireland publish their own indices, as wimd-decile, simd-decile and nimdm-rank. They rank different areas in different years, so don't compare them with each other.

get/areas/{geography}/{release}/{code}/childrenList child areas get/exports/{export-id}Download a dataset get/areas/{geography}/{release}/{code}/children/geometryGet the shapes inside an area

Find the areas most in need

List the neighbourhoods

Get every decile at once

Summarise without averaging

Count the people

Map them

Credit the sources