UK Data AtlasAPI

Guide

Identify a column of codes

Got a spreadsheet of area codes and no note of where they came from? Before you can map or join it, you need to know which kind of area they are and which year's boundaries they use. This guide asks the API to work that out.

  1. Send the column

    Send the codes without a geography or release. POST them as JSON or CSV, up to 250,000 values, or put a short column in the URL as repeated value parameters. Here are four council codes and one newer one:

    curl -X POST "https://api.ukdataatlas.com/v1/areas:validate" \
  -H "Content-Type: application/json" \
  --data '{"values":["E07000026","E07000028","E07000029","E08000025","E06000063"]}'

  2. Read the likely release

    The API checks the column against every compiled release and ranks them by how many values each holds exactly. likely names the best, here localAuthority release 2022-12-uk-bgc-v2, and candidates lists the top ten with a count of statuses for each.

    verdict sums up whether you can use the column as it is:

    VerdictWhat it means
    joinableEvery value names exactly one area of the likely release.
    mixed-code-systemsThe codes are real, but no single release holds them all.
    incompleteSome values are unknown, malformed or ambiguous.
    unmatchedNo release holds any of the values.

  3. Choose between ties

    Many codes stay the same for years, so several releases can hold a column equally well. When that happens, likely is the newest of them and likely.tiedWith lists the rest. The codes alone can't tell them apart, so pick by the date your data describes. Find boundaries for a date names the release that was current then:

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

  4. Handle a mixed column

    In the example, E06000063 is Cumberland, a council created in April 2023 from Allerdale, Copeland and Carlisle, which are also in the column. No release holds both, so the verdict is mixed-code-systems. The newer code's status is not-yet-current, and its presentIn lists the releases that do hold it.

    recommendations lists published lookups between the releases involved, with their quality. Use one to convert the stray codes, or drop them, then join the column to the release.

    The check never converts or joins anything for you. It reports what it found and leaves the choice to you.

post/areas:validateValidate a whole columnget/boundary-releases:resolveFind boundaries for a date