UK Data AtlasAPI

List neighbouring areas

Find the areas that share a border with this one, longest shared border first. Just what you need for "how does this ward compare with the ones around it?".

get
/areas/{geography}/{release}/{code}/neighbours

Good to know

  • Set touches=any to include areas that only meet at a corner. Their sharedBorderM is zero.

Path parameters

  • geographystringrequired

    A geography type id, e.g. constituency or ward.

  • releasestringrequired

    A boundary release id, e.g. 2024-07-uk-bgc, or latest for the geography's newest release: the one /boundary-releases:resolve chooses for the furthest date. A response to latest names the release it read in Content-Location. A geography whose newest month holds several releases that differ in more than coverage, or that has a release whose id carries no month, is refused with 409 and the releases that could be newest.

  • codestringrequired

    The official source code for this area on this boundary release.

Query parameters

  • touchesstringoptional

    edge for areas sharing a border with length; any to include areas meeting only at a point.

    One ofedgeany
    Defaultedge

Returns

AreaNeighboursEnvelope

The neighbouring areas, ordered by shared border, longest first.

  • apiVersionv1required
  • atlasReleasestringrequired

    The immutable /atlas-release releaseId for the artifacts that produced this response.

  • metaobjectrequired
    Show1 child field
    • nextCursorstring | nullrequired

      Opaque cursor for the next page, or null at the end.

  • dataAreaNeighboursrequired
    Show10 child fields
    • idstringrequired
    • geographystringrequired
    • boundaryReleasestringrequired
    • codestringrequired
    • namestringrequired
    • aliasesstring[]optional
    • touchesstringrequired
      One ofedgeany
    • borderobjectrequired
      Show4 child fields
      • perimeterMnumberrequired
      • sharedBorderMnumberrequired

        Border shared with the neighbours returned.

      • unsharedBorderMnumberrequired

        The remainder: coastline, a national boundary, or a border with an area outside this release. Nothing for a landlocked area.

      • pointOnlyTouchesintegerrequired

        Areas meeting only at a point, counted whether or not touches returned them.

    • methodobjectrequired
      Show4 child fields
      • rulestringrequired
      • sharedBorderstringrequired
      • unsharedstringrequired
      • limitsstringrequired
    • neighboursAreaInRelease[]required
      Show11 child fields
      • idstringrequired
      • geographystringoptional
      • boundaryReleasestringoptional
      • codestringrequired
      • namestringrequired
      • aliasesstring[]optional
      • touchstringrequired
        One ofedgepoint
      • sharedBorderMnumberrequired

        Zero for a point touch.

      • shareOfPerimeternumberrequired

        The shared border as a fraction of this area's own perimeter.

      • sharedEdgesintegerrequired
      • sharedVerticesintegerrequired

When it goes wrong

  • 400touches is neither edge nor any.
  • 404Either no compiled area matches that identity, or the area exists but no feature for its code was found in the raw geometry source.
  • 503The area exists but its geometry cannot be served: no raw source is declared, or its CRS has no transformation to WGS84.

Every error has the same shape. See Errors for how to handle them.

Technical notes

Show the precise behaviour

Returns the areas next to this one within the same geography and release, each with the length of the border they share. This supports local comparison, map navigation and spatial modelling: "how does this ward compare with the ones around it" needs to know which those are.

Neighbours are found from shared vertices, not from a distance threshold. Adjacent areas in one published release are drawn from the same vertices, so a common border is the same coordinates on both sides and matches exactly; the shared length is summed over those edges, each counted once, with ground length from the ellipsoid's radii of curvature. Nobody picks a tolerance, and nothing is approximate.

touches decides whether areas meeting at a single point count. edge, the default, returns only areas sharing a border with length; any also returns those meeting at a corner, whose sharedBorderM is zero. Four areas at a crossroads are not neighbours of each other in any sense useful for comparison or for colouring a map, so they are excluded unless asked for; border.pointOnlyTouches counts them either way, so their exclusion is visible rather than silent. They are real: none occur between local authorities, while about 3% of ward adjacencies are corners.

border totals the perimeter, the border shared with the neighbours returned, and the remainder. For a landlocked area the remainder is nothing; otherwise it is coastline, a national boundary, or a border with an area outside this release. Birmingham shares 100% of its perimeter across seven neighbours; the Isle of Wight has none, and all 188.7 km of its boundary is its own.

Within one geography and release only. Two areas that genuinely touch on the ground but were drawn from different vertices are not found, which is why this is not offered across releases.