Guide

Draw a map

Maps go wrong quietly: data from one year drawn on boundaries from another leaves areas blank or in the wrong place. This guide maps Birmingham's population in a way that can't go wrong, and shows you why each step is there.

Find the place

Start from the name and pick the local authority from the results. Its code is E08000025.

curl "https://api.ukdataatlas.com/v1/places?q=Birmingham"

Example 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
  }
}

Choose boundaries

Decide which boundaries to draw by date. This returns an exact release id in data.selected.id, never a moving "latest", so your map won't change underneath you.

curl "https://api.ukdataatlas.com/v1/boundary-releases:resolve?geography=localAuthority&date=2023-06-30"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "geography": "localAuthority",
    "date": "2023-06-30",
    "month": "2023-06"
  },
  "meta": {
    "nextCursor": null
  }
}

Check the data fits

Ask which boundary releases the population data can be drawn on. Look for your release with a status of exact-code-set or code-set-compatible, which means every area in the data exists in those boundaries.

curl "https://api.ukdataatlas.com/v1/measures/population/compatibility"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "measureId": "population",
    "sources": [
      {
        "datasetId": "population",
        "sourceGeography": {
          "type": "ward",
          "boundaryYear": 2023
        },
        "periods": [
          "2022"
        ],
        "candidates": [
          {
            "boundaryRelease": "2023-05-uk-bgc",
            "title": "Wards, May 2023 (United Kingdom, generalised, clipped)",
            "coverageCountries": [
              "GB-ENG"
            ]
          }
        ],
        "note": "This is code-set compatibility only, based on area-code membership. It does not select a boundary release or claim that compatible releases have equal geometry."
      }
    ],
    "note": "Candidates report code-set compatibility only. They do not select a geometry release or assert equal geometry."
  },
  "meta": {
    "nextCursor": null
  }
}

Fetch the values

Now request the values with your chosen release. The API joins them to the boundaries by area code, and provenance.transformation.status confirms nothing was converted.

curl "https://api.ukdataatlas.com/v1/data/population?period=2024&geography=localAuthority&boundaryYear=2023&release={release}&place=E08000025"

Example 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
  }
}

Replace {release} with the id from step 2. If the codes didn't fit, this request would be refused with incompatible_geometry rather than drawing a map with holes.

Fetch the shape

Get Birmingham's boundary from the same release. tier=medium keeps the file small enough for the web.

curl "https://api.ukdataatlas.com/v1/areas/localAuthority/{release}/E08000025/geometry?tier=medium"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:24a500c55416bd7d58c28b1fc8cc4931d4a2fd831addafa3116556a91f2c4857",
  "data": {
    "type": "Feature",
    "id": "constituency/2024-07-uk-bgc/E14001262",
    "properties": {
      "id": "constituency/2024-07-uk-bgc/E14001262",
      "geography": "constituency",
      "boundaryRelease": "2024-07-uk-bgc",
      "code": "E14001262",
      "name": "Halifax",
      "generalisation": {
        "tier": "full",
        "toleranceM": 0,
        "minEffectiveAreaM2": 0,
        "vertices": 1204,
        "verticesAtFullResolution": 1204,
        "parts": 1,
        "partsAtFullResolution": 1
      },
      "geometrySource": {
        "sourceCrs": "EPSG:4326"
      }
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -1.9269,
            53.7874
          ],
          [
            -1.9146,
            53.7815
          ]
        ]
      ]
    }
  },
  "meta": {
    "nextCursor": null
  }
}

Credit your sources

Published maps need attribution. This returns ready-to-use text covering both the data and the boundaries:

curl "https://api.ukdataatlas.com/v1/attribution?measure=population&boundaryRelease=localAuthority/{release}"

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
  }
}

Finally, check every response carries the same atlasRelease. If they do, your whole map came from one consistent set of data.

Mapping many areas

For a map of the whole country, fetching one shape at a time is too slow. Use vector tiles instead: configure your map library with the TileJSON, then colour the areas with a small table of values that shares the tiles' numbering.

get/map-resources/{geography}/{release}/tiles.jsonGet TileJSON get/map-resources/{geography}/{release}/join/{measure-id}Get values for tiles get/map-resources/{geography}/{release}.pmtilesDownload all tiles

Draw a map

Find the place

Choose boundaries

Check the data fits

Fetch the values

Fetch the shape

Credit your sources

Mapping many areas#

Mapping many areas