UK Data AtlasAPI

Get an area's relationships

See how an area relates to others through published crosswalks: what it sits within, what it contains, what it replaced or was replaced by, and what it overlaps.

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

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.

Returns

AreaRelationshipsEnvelope

The area identity and its published relationship edges.

  • 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.

  • dataAreaWithRelationshipsrequired
    Show8 child fields
    • idstringrequired
    • geographystringrequired
    • boundaryReleasestringrequired
    • codestringrequired
    • namestringrequired
    • aliasesstring[]optional
    • relationshipsAreaRelationship[]required
      Show4 child fields
      • relationenumrequired
        One ofwithincontainssuccessorpredecessorsplit-frommerged-fromequivalent-tooverlaps
      • overlapobjectoptional

        Present only for overlaps relationships. Each share is seen from this area's side: shareOfArea is the overlap as a share of this area and shareOfCounterpart as a share of the counterpart.

        Show3 child fields
        • areaM2integerrequired
        • shareOfAreanumberrequired
        • shareOfCounterpartnumberrequired
      • counterpartobjectrequired
        Show5 child fields
        • idstringrequired
        • geographystringrequired
        • boundaryReleasestringrequired
        • codestringrequired
        • labelsstring[]required
      • crosswalkobjectrequired
        Show4 child fields
        • idstringrequired
        • methodCrosswalkMethodrequired

          official-lookup and clean-containment read an explicit code pair from a published file. area-overlap intersects the two releases' boundary geometries and weights each source by the area it shares with each target. population-overlap reweights an area-overlap crosswalk's pairs by the residents of the building blocks in each. geometric-containment derives a hierarchy from geometry where no publisher lookup carries it. best-fit names, for each child, the one parent holding most of its area where the two do not nest. extent-continuity pairs the codes two releases of one geography share, as identity only where their geometries differ by no more than generalisation slivers.

          One ofofficial-lookupclean-containmentarea-overlappopulation-overlapgeometric-containmentbest-fitextent-continuity
        • qualityCrosswalkQualityrequired

          publisher-supplied mappings restate a publisher's own correspondence. derived mappings are computed by the Atlas.

          One ofpublisher-suppliedderived
        • weightingCrosswalkWeightingrequired
    • childSelectionobjectoptional

      Present on the children route. contemporary selects the child release current at the parent's release month; release records an exact child geography/release filter.

When it goes wrong

  • 404No resource matches that identity.
  • 503The referenced build artifact has not been built yet.

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

Technical notes

Show the precise behaviour

Returns only relationships from published crosswalks. A clean-containment mapping is represented as within from child to parent and contains in reverse. An official historical lookup is represented as successor from source to target and predecessor in reverse; a one-to-many lookup is split-from on each new area and a many-to-one lookup is merged-from on the new area. An extent-continuity crosswalk is equivalent-to in both directions. An area-overlap mapping is represented as overlaps in both directions, with the shared area and its share of each side.