UK Data AtlasAPI

Convert to other areas

Regroup a measure onto a different set of areas, such as wards up to local authorities, using a crosswalk you choose. Only counts can be converted, because converting works by adding values up.

get
/data/{measure-id}/convert

Good to know

  • Find a crosswalk with List crosswalks.
  • The response's method tells you whether the conversion was exact, meaning every area fitted neatly inside one target.

Path parameters

  • measure-idstringrequired

    A measure id from GET /v1/measures, such as population, or one of its aliases, such as house-prices. An alias is read as the id it names, and the response's Content-Location header gives the request it was read as. Case, spaces and punctuation are set aside, so House Prices is house-prices.

Query parameters

  • crosswalkstringoptional

    A crosswalk id returned by GET /crosswalks, applied forward. Required unless path is named; naming both is refused.

  • pathstringoptional

    A relationship path id returned by GET /relationships, applied through every step. Required unless crosswalk is named; naming both is refused.

  • periodstringrequired

    The observation period as the partition publishes it, e.g. 2022, 2026-04 or year-ending-2026-03. A measure's periods are listed in its catalogue entry.

  • geographystringrequired

    The geography the publisher observed the values on. With boundaryYear it selects one source partition of the measure; it never converts values onto another geography.

    One ofwardlocalAuthorityconstituencylsoamsoadataZonesuperOutputArea
  • boundaryYearintegerrequired

    The year of the boundaries the values are published on: 2023 with geography=localAuthority means local authorities as they were in 2023. It names the publisher's area set, not one boundary release; a year can have several releases (May and December), and release chooses which to draw where a route offers it.

  • limitinteger 1–500optional

    How many records to return, 1 to 500.

    Default100
  • cursorstringoptional

    The meta.nextCursor of the previous page. A cursor is opaque and belongs to the query that issued it.

Returns

Envelope

Cursor-paginated derived values on the crosswalk's target areas, with the conversion method and the crosswalk's own provenance.

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

When it goes wrong

  • 400A query parameter is malformed or its cursor is not valid for this result set.
  • 404No resource matches that identity.
  • 422The measure is intensive, the crosswalk starts at another geography, or the partition cannot be converted completely.
  • 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

Converts a source partition onto another geography or code vintage using the crosswalk, or the published relationship path, the caller names. Exactly one of crosswalk and path is required. The route never selects a conversion path: GET /crosswalks lists the published crosswalks and GET /relationships the published paths, and the response repeats each crosswalk's method, quality, weighting and content hash.

A path carries values through every one of its steps in order, in the direction each step declares. Weights multiply along the path, so a source split at one step and split again at the next is apportioned by the product of the two published weights. A path is refused as a whole if any step would drop a value or split one without a weight.

The crosswalk decides the target areas, so this route selects no geometry release: passing release is refused rather than ignored. Ask /data/{measure-id} with a compatible release to join geometry to source-exact values instead. Only a measure declared extensive may be converted, because conversion works by adding values up. An intensive measure is rejected: a share or a rank cannot be regrouped by summing, and weighting one by area produces a number with no meaning. The reported method distinguishes the outcomes. Across a path it describes every step together: exact only if no step splits a source, and population-weighted only if every splitting step is. exact means every source area sits wholly within one target, so the conversion is a regrouping and the partition total is unchanged. area-weighted means some sources were split in proportion to overlapping area, which is an estimate that assumes the measure is spread evenly across each source. population-weighted means they were split by where each source's residents live, counted from the crosswalk's population building blocks, which assumes the measure follows resident population. A source code the crosswalk does not carry, or a split source with no published weight, is rejected rather than partially converted.