UK Data AtlasAPI

Guide

Convert your own counts

Your referrals are counted by ward, but each council wants its own total. Or your members are counted by constituency, and a funder asks for them by council. Send your counts and get them back on the areas you need, with a clear statement of what is exact and what is an estimate.

  1. Find the crosswalk

    A crosswalk says which of your areas fall in which of the areas you want. Ask which ones join your release to the one you need. For wards counted on May 2026 boundaries, totalled by council:

    curl "https://api.ukdataatlas.com/v1/relationships?from=ward/2026-05-uk-bgc&to=localAuthority/2026-05-uk-bgc&purpose=membership"

    Each path's steps name the crosswalkId to use. Not sure which release your codes are from? Identify a column of codes finds it.

  2. Send your counts

    POST one row per area, as a code or a name, with its count. Ward names repeat across the country, so add a parent to say which one you mean. There are a dozen wards called Abbey; this one is in Merton.

    curl -X POST "https://api.ukdataatlas.com/v1/crosswalks/ward-2026-05-uk-bgc-to-local-authority-2026-05-uk-bgc-clean-containment:convert?semantics=count" \
  -H "Content-Type: application/json" \
  --data '{"rows":[{"name":"Headingley & Hyde Park","value":40},{"name":"Rusholme","value":25},{"code":"E05010885","value":18},{"name":"Abbey","parent":"Merton","value":12}]}'

    semantics=count is you confirming the values are counts that add up across areas, such as people, referrals or visits. You can send up to 250,000 rows, as JSON or CSV, and nothing you send is stored.

    Don't send rates, percentages, averages or medians. Adding them up gives a number that looks right and isn't.

  3. Read the result

    Each record is one council with its total in value. method is exact here, because every ward sits wholly inside one council, and inputTotal matches outputTotal.

    Check each record's coverage. partial means you sent some of the council's wards but not all, so its total only covers the wards you sent. A council you sent nothing for is left out rather than given a zero.

  4. When areas split

    Constituencies cross council boundaries, so a count for one seat has to be shared between councils. This crosswalk shares it by where people lived at the 2021 census, and you opt in with weighting=population:

    curl -X POST "https://api.ukdataatlas.com/v1/crosswalks/constituency-2024-07-uk-bgc-to-local-authority-2024-05-uk-bgc-population-overlap:convert?semantics=count&weighting=population" \
  -H "Content-Type: application/json" \
  --data '{"rows":[{"code":"E14001319","value":120},{"code":"E14001172","value":80}]}'

    Leeds Central and Headingley lies wholly in Leeds, so its 120 moves across unchanged. Cities of London and Westminster is split: about 6 of its 80 go to the City of London and 74 to Westminster, and method becomes population-weighted. Split values aren't rounded, so round them when you present them and call them estimates.

    Some crosswalks share by land area instead, with weighting=area. That assumes your count is spread evenly over the land, which is rarely true. Shared by area, the City of London gets about 12, twice as many, because it has a lot of land for very few residents. Prefer population weights for counts of people.

  5. When the request is refused

    If any row can't be placed, nothing is converted. You get a 422 with conversion_not_available, and rejected lists each problem row with its index and reason. Without a parent, Abbey is ambiguous, and its candidates list every ward with that name:

    curl -X POST "https://api.ukdataatlas.com/v1/crosswalks/ward-2026-05-uk-bgc-to-local-authority-2026-05-uk-bgc-clean-containment:convert?semantics=count" \
  -H "Content-Type: application/json" \
  --data '{"rows":[{"name":"Headingley & Hyde Park","value":40},{"name":"Abbey","value":12}]}'

    A split with no published weights is refused too, rather than guessed. That's why 2019 constituency results can't be moved onto the 2024 seats, as Brief on a constituency explains.

get/relationshipsExplore geography relationshipspost/crosswalks/{crosswalk-id}:convertConvert your own countsget/crosswalksList crosswalks