Guide

Explore a named place

People ask about places that official boundary systems do not always name: North Wales, Greater Manchester, the Highlands or the Belfast Metropolitan Area. Treat the name as a curated collection, inspect what it contains, then choose how to calculate an answer.

Search the name

Start with the words a person uses. Search is deliberately ambiguous-friendly: it returns the curated id rather than asking you to guess a URL slug.

curl "https://api.ukdataatlas.com/v1/locations?q=North%20Wales"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": [
    {
      "id": "york",
      "label": "York",
      "kind": "editorial-grouping",
      "definitionRevision": 1,
      "memberGeography": "localAuthority",
      "memberCodes": [
        "E06000014"
      ],
      "validity": {
        "from": null,
        "to": null
      },
      "bbox": [
        -1.15
      ]
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

Inspect the definition

Use the returned id, north-wales, to read the definition and its member geography. This is an editorial grouping, not a new official boundary, so the response keeps the definition revision and member codes visible.

curl "https://api.ukdataatlas.com/v1/locations/north-wales"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "id": "london",
    "label": "London",
    "kind": "region",
    "source": {
      "publisher": "Office for National Statistics",
      "lookup": "local-authority-to-region/2025-04-en",
      "code": "E12000007"
    },
    "definitionRevision": 2,
    "memberGeography": "localAuthority",
    "memberCodes": [
      "E09000001"
    ],
    "validity": {
      "from": null,
      "to": null
    },
    "bbox": [
      -0.5
    ]
  },
  "meta": {
    "nextCursor": null
  }
}

curl "https://api.ukdataatlas.com/v1/locations/north-wales?include=capabilities"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "id": "london",
    "label": "London",
    "kind": "region",
    "source": {
      "publisher": "Office for National Statistics",
      "lookup": "local-authority-to-region/2025-04-en",
      "code": "E12000007"
    },
    "definitionRevision": 2,
    "memberGeography": "localAuthority",
    "memberCodes": [
      "E09000001"
    ],
    "validity": {
      "from": null,
      "to": null
    },
    "bbox": [
      -0.5
    ]
  },
  "meta": {
    "nextCursor": null
  }
}

Resolve its members

Choose the boundary release you want to work in. For direct members, use the location's declared geography; for another geography, name a published crosswalk with via. The API returns unresolved codes and coverage instead of silently dropping them.

curl "https://api.ukdataatlas.com/v1/locations/north-wales/members?release=2025-12-uk-bgc"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "location": {
      "id": "north-wales",
      "label": "North Wales",
      "kind": "editorial-grouping",
      "definitionRevision": 1,
      "memberGeography": "localAuthority",
      "memberCodes": [
        "W06000001"
      ],
      "validity": {
        "from": null,
        "to": null
      },
      "bbox": [
        -4.8
      ]
    },
    "geography": "ward",
    "boundaryRelease": "2024-12-uk-bgc",
    "reach": {
      "memberCount": 6,
      "reachedCount": 6,
      "unreached": [],
      "complete": true
    }
  },
  "meta": {
    "nextCursor": null
  }
}

curl "https://api.ukdataatlas.com/v1/locations/north-wales/members?geography=ward&release=2024-12-uk-bgc&via=ward-2024-12-uk-bgc-to-local-authority-2024-12-uk-bgc-clean-containment"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "location": {
      "id": "north-wales",
      "label": "North Wales",
      "kind": "editorial-grouping",
      "definitionRevision": 1,
      "memberGeography": "localAuthority",
      "memberCodes": [
        "W06000001"
      ],
      "validity": {
        "from": null,
        "to": null
      },
      "bbox": [
        -4.8
      ]
    },
    "geography": "ward",
    "boundaryRelease": "2024-12-uk-bgc",
    "reach": {
      "memberCount": 6,
      "reachedCount": 6,
      "unreached": [],
      "complete": true
    }
  },
  "meta": {
    "nextCursor": null
  }
}

Ask a question

For an additive measure such as population, ask for a total over the named location. The route records the source partition and the coverage used to produce it.

curl "https://api.ukdataatlas.com/v1/data/population/aggregate?period=2024&geography=localAuthority&boundaryYear=2023&place=location/north-wales"

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-uk",
      "periods": [
        "2011"
      ],
      "sourceGeography": {
        "type": "localAuthority",
        "boundaryYear": 2023
      },
      "coverage": {
        "kind": "source-reported",
        "countries": [
          "GB-ENG"
        ],
        "recordCount": 361,
        "note": "Published source records cover all four UK nations for every available period. Historic values remain keyed to the source's 2023 local-authority code vintage."
      }
    },
    "period": "2022",
    "sourceGeography": {
      "type": "localAuthority",
      "boundaryYear": 2023
    },
    "area": {
      "id": "country/2025-12-uk-bgc/W92000004",
      "boundaryRelease": "2025-12-uk-bgc",
      "code": "W92000004",
      "name": "Wales",
      "aliases": [
        "Cymru"
      ]
    },
    "provenance": {
      "atlasRelease": {
        "id": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
        "href": "/v1/atlas-release"
      },
      "measure": {
        "id": "population",
        "href": "/v1/measures/population"
      },
      "geography": {
        "source": {
          "type": "localAuthority",
          "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": "Input observations are source-exact; no geographic conversion was applied."
      },
      "source": {
        "dataset": {
          "id": "population-uk",
          "href": "/v1/datasets/population-uk"
        },
        "observations": {
          "artifact": "population-local-authority-observations",
          "contentHash": "sha256:1bf9e38cc9c37b37492b4a3cdc6b28c28ddeb5c2adc81e838ef947d78a0c0a9b",
          "period": "2022"
        }
      }
    },
    "aggregation": {
      "operation": "sum",
      "membership": "gss-country-code",
      "inputRecordCount": 22,
      "coverage": {
        "status": "complete",
        "assessments": [
          {
            "boundaryRelease": "2023-05-uk-bgc-v2",
            "status": "complete",
            "expectedAreaCount": 22,
            "includedAreaCount": 22,
            "missingAreaCount": 0,
            "missingAreaSample": []
          }
        ],
        "href": "/v1/measures/population/coverage"
      },
      "note": "Country membership follows the first character of the GSS area code, which the coding scheme assigns by country."
    },
    "record": {
      "value": 3134196,
      "status": "derived"
    }
  },
  "meta": {
    "nextCursor": null
  }
}

Not every measure can be added. A median, rank or percentage may need a different question, and the API will explain the refusal rather than produce a misleading total.

Explain the result

Show the location label, definition revision, source geography, boundary release and coverage alongside the number. If you used a crosswalk, keep its id too: “North Wales” can mean different things depending on which published membership relationship you chose.

curl "https://api.ukdataatlas.com/v1/locations/north-wales/parents?geography=region&release=2025-12-en-bgc&via=local-authority-2025-12-uk-bgc-to-region-2025-12-en-bgc-area-overlap"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:5c4aa4529cbfbd5e4c844c55cddba1ef04a7bf76f3eaa085a357fff401af6d0c",
  "data": {
    "geography": "combinedAuthority",
    "boundaryRelease": "2025-12-en-bgc",
    "via": {
      "id": "local-authority-2025-12-uk-bgc-to-combined-authority-2025-12-en-bgc-official-lookup",
      "method": "clean-containment",
      "quality": "publisher-supplied"
    },
    "memberGeography": "localAuthority",
    "memberBoundaryRelease": "2025-12-uk-bgc",
    "locationWithin": {
      "id": "combinedAuthority/2025-12-en-bgc/E47000001",
      "code": "E47000001",
      "name": "Greater Manchester"
    },
    "parents": [
      {
        "id": "combinedAuthority/2025-12-en-bgc/E47000001",
        "code": "E47000001",
        "name": "Greater Manchester",
        "relation": "covers",
        "members": [
          {
            "id": "localAuthority/2025-12-uk-bgc/E08000003",
            "code": "E08000003",
            "name": "Manchester"
          }
        ],
        "parentMemberCount": 10
      }
    ],
    "unplaced": []
  },
  "meta": {
    "nextCursor": null
  }
}

Named locations are useful starting points, not permission to hide the method. When the exact boundary matters, move from the named location to its official members and keep the release and crosswalk in your records.

get/locationsList named locations get/locations/{location-id}/membersList a named location's areas get/data/{measure-id}/aggregateAdd up a measure