Guide

Profile a postcode

Building a property listing, a house-hunting tool or a local news page? Turn a postcode into a short profile of the area around it, with each figure taken from the right geography and labelled with the area it describes.

Look up the postcode

Start by checking the postcode is real and finding the areas it sits in. The answer lists its council, ward and Westminster constituency, with the boundary release each was matched in.

curl "https://api.ukdataatlas.com/v1/postcodes/LS6%203AA"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:9e5c1f2b00f6d7becc55f3e569310568fdcbd59cbdf754f70f5dfc8cb2d4a8e8",
  "data": {
    "postcode": "SW1A 1AA",
    "status": "live",
    "introduced": "1980-01",
    "userType": "large",
    "country": "E92000001",
    "centroid": {
      "crs": "EPSG:27700",
      "easting": 529090,
      "northing": 179645,
      "positionalQuality": {
        "indicator": 1,
        "description": "Within the building of the matched address closest to the postcode mean.",
        "accuracyM": 0.5
      }
    },
    "point": {
      "lng": -0.141588,
      "lat": 51.501009,
      "crs": "EPSG:4326",
      "precision": {
        "uncertaintyM": 2.5,
        "basis": "decimal-places-and-transformation"
      }
    },
    "date": "2026-08",
    "dateBasis": "directory-edition",
    "pointCountry": {
      "code": "GB-ENG",
      "determinedBy": "area-code"
    },
    "boundaryRule": "included",
    "results": [
      {
        "geography": "localAuthority",
        "boundaryRelease": "2026-05-uk-bgc",
        "status": "matched",
        "matches": [
          {
            "id": "localAuthority/2026-05-uk-bgc/E09000033",
            "code": "E09000033",
            "name": "Westminster",
            "nearBoundary": false
          }
        ]
      },
      {
        "geography": "ward",
        "boundaryRelease": "2026-05-uk-bgc",
        "status": "matched",
        "matches": [
          {
            "id": "ward/2026-05-uk-bgc/E05013806",
            "code": "E05013806",
            "name": "St James's",
            "nearBoundary": false
          }
        ]
      },
      {
        "geography": "constituency",
        "boundaryRelease": "2024-07-uk-bgc",
        "status": "matched",
        "matches": [
          {
            "id": "constituency/2024-07-uk-bgc/E14001172",
            "code": "E14001172",
            "name": "Cities of London and Westminster",
            "nearBoundary": false
          }
        ]
      }
    ],
    "source": {
      "title": "ONS Postcode Directory (August 2026)",
      "edition": "2026-08",
      "publisher": "Office for National Statistics"
    }
  }
}

Check status. A terminated postcode still resolves, because old addresses still turn up in real data, so decide whether your users should see it.

Ask each measure

Each measure is published for its own kind of area. Deprivation is ranked for small neighbourhoods, council tax is set by councils and crime is counted by community safety partnerships. You don't need to work out which area to ask about. Pass the postcode as place and the API finds the area of the right kind:

curl "https://api.ukdataatlas.com/v1/data/imd-decile/value?place=LS6%203AA"

Example 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/value?place=location/north-west&geography=localAuthority&codeYear=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 figure is in answer.value, with its unit. Ask the same way for each measure in your profile. These answer for these areas:

Measure	Answered for
`imd-decile`	The neighbourhood (LSOA), about 1,500 people
`population`	The ward
`council-tax`	The council
`broadband-full-fibre-availability`	The council
`median-annual-pay`	The council
`crime-total`	The community safety partnership, usually the council

curl "https://api.ukdataatlas.com/v1/data/council-tax/value?place=LS6%203AA"

Leave out period and you get the latest one. answer.periodDefaulted is true when the period was chosen for you, so always show answer.period beside the figure.

Say how local each figure is
Every answer has an area naming what the figure describes. Show it. A deprivation decile describes a few streets, but the crime count for this postcode is every offence recorded across Leeds, which is not the same as the crime on its street.
A postcode is placed by a single point, its centroid. When that point is close to an area's edge, area.nearBoundary is true and distanceToBoundaryM says how close. LS6 3AA is about 16 metres from the edge of its neighbourhood, so some of its addresses may fall in the next one. Treat neighbourhood figures for such postcodes as approximate.
Handle gaps in coverage
Not every measure covers the whole UK. The Index of Multiple Deprivation is England's, so a Cardiff postcode is refused with place_not_served, and each entry in candidates says why:
curl "https://api.ukdataatlas.com/v1/data/imd-decile/value?place=CF10%201AA"
Each nation publishes its own index, and they can't be compared with each other. Use wimd-decile in Wales, simd-decile in Scotland and nimdm-rank in Northern Ireland, and label which one you show. A refused measure should leave a gap in your profile, not a zero.
Northern Ireland postcodes can't be looked up at all. Land and Property Services license them for internal business use only, so they are refused with 451.

Credit the sources

Publishing the profile? Ask for the attribution for the measures you show. text is ready to print under the profile, and licences lists the licence terms.

curl "https://api.ukdataatlas.com/v1/attribution?measure=imd-decile&measure=council-tax&measure=broadband-full-fibre-availability&measure=crime-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
  }
}

get/postcodes/{postcode}Find a postcode's areas get/data/{measure-id}/valueGet a value for a place get/attributionGet attribution text

Profile a postcode

Look up the postcode

Ask each measure

Say how local each figure is

Handle gaps in coverage

Credit the sources