Guide
Brief on a constituency
Writing about a seat, briefing a candidate or building a page for constituents? Go from a postcode to the 2024 result, put turnout in context and describe who lives there, without comparing against 2019 as if the boundaries hadn't changed.
Find the constituency
Most people know their postcode, not their constituency. Look it up, and take the
constituencyresult. LS6 3AA is in Leeds Central and Headingley,E14001319, in the2024-07-uk-bgcrelease: the seats first contested in July 2024.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" } } }Matching a mailing list or petition to seats? Locate a batch of points sends up to 100 postcodes at a time.
Get the 2024 result
The winner is a category rather than a number, so it comes back as
category, hereLAB:curl "https://api.ukdataatlas.com/v1/data/general-election-winning-party?period=2024&geography=constituency&codeYear=2024&place=E14001319"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", "codeYear": 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", "codeYear": 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", "codeYear": 2023 }, "provenance": { "atlasRelease": { "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "href": "/v1/atlas-release" }, "measure": { "id": "population", "href": "/v1/measures/population" }, "geography": { "source": { "type": "ward", "codeYear": 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 } }Votes and vote shares are one measure per party. Search the catalogue to list them, then ask for the ones you need:
curl "https://api.ukdataatlas.com/v1/measures?q=vote%20share"curl "https://api.ukdataatlas.com/v1/data/general-election-lab-vote-share?period=2024&geography=constituency&codeYear=2024&place=E14001319"Put turnout in context
A turnout of 45% means more next to every other seat. Rank all of them, lowest first, to see where this one falls:
curl "https://api.ukdataatlas.com/v1/data/general-election-turnout/rankings?period=2024&geography=constituency&codeYear=2024&order=asc&limit=20"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", "codeYear": 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", "codeYear": 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", "codeYear": 2023 }, "provenance": { "atlasRelease": { "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "href": "/v1/atlas-release" }, "measure": { "id": "population", "href": "/v1/measures/population" }, "geography": { "source": { "type": "ward", "codeYear": 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" } } }, "ranking": { "order": "desc", "method": "competition", "note": "Equal values share a rank; the following rank accounts for every preceding observation (for example 1, 1, 3)." }, "records": [ { "areaCode": "E05011403", "value": 34637, "status": "observed", "rank": 1, "tieCount": 1 } ] }, "meta": { "nextCursor": "RTA1MDExNDAz" } }Or set it against one other seat. Turnout is a percentage, so the
differenceis in percentage points, not a percentage change:curl "https://api.ukdataatlas.com/v1/data/general-election-turnout/compare?period=2024&geography=constituency&codeYear=2024&baselinePlace=E14001319&comparisonPlace=E14001172"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", "codeYear": 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", "codeYear": 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", "codeYear": 2023 }, "provenance": { "atlasRelease": { "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c", "href": "/v1/atlas-release" }, "measure": { "id": "population", "href": "/v1/measures/population" }, "geography": { "source": { "type": "ward", "codeYear": 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" } } }, "comparison": { "baseline": { "areaCode": "E05000932", "value": 12676, "status": "observed" }, "comparison": { "areaCode": "W05001039", "value": 3288, "status": "observed" }, "difference": { "direction": "comparison-minus-baseline", "value": -9388, "unit": "people", "interpretation": "Difference in the source-published unit." }, "relativeDifference": { "value": -0.74061218049858, "basis": "(comparison - baseline) / baseline" } } }, "meta": { "nextCursor": null } }Describe who lives there
ONS publishes population estimates for the new seats in England and Wales:
curl "https://api.ukdataatlas.com/v1/data/population?period=2022&geography=constituency&codeYear=2024&place=E14001319"Most other measures are published for councils, and seats don't line up with councils. Before you quote a council figure for a seat, check how much of the seat the council covers. Compare an area shows how.
Be careful with 2019
The 2024 seats have new boundaries, so there is no published 2019 result for Leeds Central and Headingley. The seat's history lists the four old seats it was made from:
curl "https://api.ukdataatlas.com/v1/areas/constituency/2024-07-uk-bgc/E14001319/history"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": "predecessor", "counterpart": { "id": "localAuthority/2022-12-uk-bgc-v2/E08000025", "geography": "localAuthority", "boundaryRelease": "2022-12-uk-bgc-v2", "code": "E08000025", "labels": [ "Birmingham" ] }, "crosswalk": { "id": "local-authority-2022-12-uk-bgc-v2-to-2023-05-uk-bgc-v2-official-lookup", "method": "official-lookup", "quality": "publisher-supplied", "weighting": { "status": "not-provided" } } } ], "lineage": [ { "relation": "predecessor", "depth": 1, "from": "localAuthority/2023-05-uk-bgc-v2/E08000025", "counterpart": { "id": "localAuthority/2022-12-uk-bgc-v2/E08000025" } } ], "sameCodeReleases": [ { "id": "localAuthority/2016-12-gb-bgc/E08000025", "geography": "localAuthority", "boundaryRelease": "2016-12-gb-bgc", "code": "E08000025", "name": "Birmingham", "status": "same-code-continuity" } ], "note": "Lineage follows only published historical edges and never infers a connection from a reused code. equivalent-to is published only for extent continuity. Same-code continuity only reports that the identifier appears in another release; it does not assert unchanged geometry or an exact historical equivalent." }, "meta": { "nextCursor": null } }You can't add those four results together, because each old seat only partly became this one. The official lookup doesn't say how the voters were split, so converting 2019 votes onto the new seats is refused with
conversion_not_availablerather than guessed:curl "https://api.ukdataatlas.com/v1/data/general-election-lab-votes/convert?period=2019&geography=constituency&codeYear=2019&crosswalk=constituency-2010-to-2024-official-lookup-v2"Talking about a "swing" from 2019 means comparing with notional 2019 results for the new seats. Those are estimates made by others, and the API doesn't serve them. If you quote one, say whose it is.
Credit the sources
The election results are compiled by the House of Commons Library. Get the attribution for what you quote:
curl "https://api.ukdataatlas.com/v1/attribution?measure=general-election-turnout&measure=population"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 } }
/data/{measure-id}Get observationsget/data/{measure-id}/rankingsRank areasget/data/{measure-id}/compareCompare two areasget/areas/{geography}/{release}/{code}/historyGet an area's history