UK Data AtlasAPI

Compare two areas

Put two areas side by side for one period and get both values and the difference between them.

get
/data/{measure-id}/compare

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

  • periodstringoptional

    The observation period as the partition publishes it. Left out, the partition's latest period is used and returned in defaults.

  • geographystringoptional

    The geography the publisher observed the values on, selecting one source partition with boundaryYear. It may be left out when an area named in the request is published on one geography of the measure, or when the measure is published on only one; geographies are never chosen between, so a measure published on several otherwise needs it. A selected geography is returned in defaults.

    One ofwardlocalAuthorityconstituencylsoamsoadataZonesuperOutputArea
  • boundaryYearintegeroptional

    The year of the boundaries the values are published on. Left out, the geography's newest partition is used and returned in defaults, unless two datasets share it, when datasetId must choose.

  • baselineAreaCodestringrequired

    The area the difference is measured from.

  • comparisonAreaCodestringrequired

    The area the difference is measured to.

Returns

Envelope

The named source-exact observations and their directed difference.

  • 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.
  • 409An area name means more than one area the measure is published for. choices lists each, with ask, the same request with that area's code and geography in place of the name.
  • 422The requested conversion, aggregation or geometry release is not supported.
  • 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 the comparison observation minus the baseline observation for one published period, geography and code vintage. Area codes may be replaced by unambiguous place names. Omitting source selectors uses the current published partition and latest period, recorded in defaults. The two named areas must be in the same source partition. Ratios report a difference on their source scale rather than a misleading relative change. The route does not select a boundary release, convert values or aggregate them.