Guide

Explore a coordinate

Have a latitude and longitude from a phone, a map or a spreadsheet? Start with the point, discover which UK areas it falls in, then use those area identities to ask for statistics and context without guessing what the place is called.

Find containing areas

Use WGS 84 longitude and latitude in decimal degrees. Here the point is in Leeds, and we ask for both its ward and local authority. Add a date when you want the API to choose the boundary release that was current at a particular time.

curl "https://api.ukdataatlas.com/v1/areas:contains?lng=-1.5491&lat=53.8008&geography=ward&geography=localAuthority&date=2025-06-01"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:da4898229392e8fa52cd5098cf24c52f11abf454b0adcab178c6c82e30032c15",
  "data": {
    "point": {
      "lng": -3.1791,
      "lat": 51.4816,
      "crs": "EPSG:4326",
      "precision": {
        "decimalPlaces": {
          "lng": 4,
          "lat": 4
        },
        "uncertaintyM": 5.56,
        "basis": "decimal-places"
      }
    },
    "date": "2025-06-01",
    "country": {
      "code": "GB-WLS",
      "determinedBy": "area-code",
      "area": "ward/2025-05-uk-bgc-v2/W05001274"
    },
    "boundaryRule": "included",
    "results": [
      {
        "geography": "ward",
        "boundaryRelease": "2025-05-uk-bgc-v2",
        "href": "/v1/boundary-releases/ward/2025-05-uk-bgc-v2",
        "selection": {
          "policy": "latest-release-dated-on-or-before",
          "date": "2025-06-01",
          "sameMonth": false
        },
        "boundaryResolution": {
          "generalisation": "generalised-20m",
          "extent": "clipped-to-coastline",
          "toleranceM": 20,
          "basis": "ons-release-name"
        },
        "geometrySource": {
          "sourceCrs": "EPSG:4326"
        },
        "status": "matched",
        "positionalToleranceM": 25.56,
        "matches": [
          {
            "id": "ward/2025-05-uk-bgc-v2/W05001274",
            "code": "W05001274",
            "name": "Cathays",
            "containment": "interior",
            "distanceToBoundaryM": 465.67,
            "nearBoundary": false
          }
        ]
      },
      {
        "geography": "localHealthBoard",
        "boundaryRelease": "2023-12-w-bgc",
        "coverage": {
          "countries": [
            "GB-WLS"
          ]
        },
        "status": "matched",
        "matches": [
          {
            "id": "localHealthBoard/2023-12-w-bgc/W11000029",
            "code": "W11000029",
            "name": "Cardiff and Vale University Health Board",
            "containment": "interior",
            "nearBoundary": false
          }
        ]
      },
      {
        "geography": "combinedAuthority",
        "selection": {
          "policy": "latest-release-dated-on-or-before",
          "date": "2025-06-01"
        },
        "status": "no-release-for-date",
        "detail": "The earliest combinedAuthority boundary release is dated 2025-12, after 2025-06.",
        "earliest": {
          "id": "2025-12-en-bgc",
          "month": "2025-12"
        },
        "matches": []
      }
    ]
  }
}

Understand the result
Read matches[].id, not just the displayed name. An id such as localAuthority/2025-05-uk-bgc-v2/E08000035 tells you the geography, boundary release and official code together. The response also says whether the point was in the interior or on a boundary, and how much positional uncertainty was allowed.
Names are for people; ids are for joining data. Keep the full id when you store the result, because an area code can be reused in a different boundary release.

Handle the edge cases

A point can be offshore, just outside a generalised boundary or near several places. areas:contains reports explicit statuses; it never invents an area. If containment has no answer, ask for the nearest areas instead and show the distance to the user.

curl "https://api.ukdataatlas.com/v1/areas:near?lng=-1.5491&lat=53.8008&geography=ward&date=2025-06-01&limit=3&within=5000"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:da4898229392e8fa52cd5098cf24c52f11abf454b0adcab178c6c82e30032c15",
  "data": {
    "point": {
      "lng": -0.58,
      "lat": 54.51,
      "crs": "EPSG:4326"
    },
    "date": "2025-06-01",
    "within": 5000,
    "limit": 2,
    "relation": "distance",
    "results": [
      {
        "geography": "ward",
        "boundaryRelease": "2025-05-uk-bgc-v2",
        "selection": {
          "policy": "latest-release-dated-on-or-before",
          "date": "2025-06-01"
        },
        "status": "found",
        "matched": 4,
        "truncated": true,
        "nearest": [
          {
            "rank": 1,
            "id": "ward/2025-05-uk-bgc-v2/E05014272",
            "code": "E05014272",
            "name": "Esk Valley & Coast",
            "distanceM": 2372.3
          }
        ]
      }
    ]
  }
}

A nearest area is not a containing area. Use it as nearby context, not as proof that the point lies inside it.

Get a statistic

Once you have the geography, release and code, pass the code to a measure route. This asks for the population published for Leeds' local authority source partition in 2024.

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

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

Keep the evidence

For anything you publish, retain the response's atlasRelease, boundary release and source partition. The top-level hash pins the API response build; inside data, the identity, boundary and measure hashes pin the artifacts that support the result. The area resource's citation include also gives you attribution text for a map or report.

curl "https://api.ukdataatlas.com/v1/areas/localAuthority/2025-05-uk-bgc-v2/E08000035?include=citation&measure=population"

Example response200

{
  "apiVersion": "v1",
  "atlasRelease": "sha256:9edc254c5d4cd0a90fc5d3b2544e5f64946d6d0e6a8b68860e3aa6f0ac8d0912",
  "data": {
    "id": "constituency/2024-07-uk-bgc/E14001262",
    "geography": "constituency",
    "boundaryRelease": "2024-07-uk-bgc",
    "code": "E14001262",
    "name": "Halifax",
    "postcodes": {
      "live": 3412,
      "terminated": 1412,
      "largeUser": 123,
      "edition": "2026-08"
    }
  },
  "meta": {
    "nextCursor": null
  }
}

The same containment route accepts British National Grid easting and northing, Irish Grid coordinates and Ordnance Survey grid references when you set the matching crs. That makes it suitable for survey data as well as web-map coordinates.

get/areas:containsFind areas at a point get/areas:nearFind the nearest areas get/areas/{geography}/{release}/{code}Get an area

Explore a coordinate

Find containing areas

Understand the result

Handle the edge cases

Get a statistic

Keep the evidence