UK Data AtlasAPI

Add up a measure

Get a total over a group of areas, such as a country, a combined authority, a county or a named location like Greater Manchester. Shares with a published weight are averaged instead. It only combines values where the result genuinely means something.

get
/data/{measure-id}/aggregate

Good to know

  • place is what to sum onto: location/{id} for a named location, a country code, or any other area a crosswalk groups members into.
  • An area that isn't a country is summed onto through whatever geography your chosen crosswalk maps to, so the same call gives you a combined authority, a county or a region. Find one with List crosswalks.
  • Only a crosswalk that establishes membership can be used. Clean containment and full area overlap qualify; a lookup that relates two vintages of the same area does not, and is refused rather than summed.
  • Counts add up. Medians and ranks don't, so asking for one gets a 422 that explains why, rather than a misleading number.
  • If a named location is missing some of its areas, you get a partial_coverage refusal. A country or membership total with gaps is still returned, with its coverage stated plainly.

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.

  • placestringrequired

    What to sum onto: location/{id} for a curated named location, a country code such as E92000001, or the code of an area a named membership crosswalk or path groups the members into, such as E47000006 for the Tees Valley combined authority. A reference such as region/E12000001 also names the target's geography, and the crosswalk must map to it.

  • fromstringoptional

    The exact source release the membership crosswalk maps from, as {geography}/{release}. Its geography must match the source partition, and its codes must be compatible with that partition.

  • crosswalkstringoptional

    A membership crosswalk returned by GET /crosswalks. Name either this or path when place is neither a location nor a country.

  • pathstringoptional

    A relationship path id from GET /relationships whose every step establishes membership, in place of crosswalk.

Returns

Envelope

A derived sum with its direct-code membership evidence and source 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 non-aggregatable, aggregation is unavailable, the location is not a complete direct match, the regional relationship is split or partial, or the partition holds no areas for the requested target.
  • 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 a derived sum for a measure declared extensive, or a weighted mean for a measure that publishes an available weight measure. place names what to sum onto. With place=location/{id}, the location's member codes are matched in the requested source partition. A location lists every code it has been made of, so a code of another vintage, whose successor or predecessor the partition holds instead, is passed over, as is a legacy code naming no compiled area; both are listed in aggregation.memberCodesNotInPartition. Any other missing member is refused with code: partial_coverage rather than silently returning a partial total, and a location none of whose codes is in the partition is refused with its reason. A named location's kind says whether it is an official area sourced from an ONS lookup or an editorial code grouping that claims no official status. With a country code such as place=E92000001, membership follows the first character of the GSS area code, which the coding scheme assigns by country. That is definitional rather than geometric, so it needs no boundary comparison and cannot drift between releases. The sum covers every area of that country the partition publishes, which is not a claim of national completeness: a partition holding no areas for the country is rejected rather than summed to zero. aggregation.coverage compares the areas summed with the country's areas in each boundary release the partition is assessed to match. It is complete when every such release is covered, partial with code: partial_coverage and the missing counts when any release holds areas the partition has no value for, as a local election does for wards that did not go to the polls, and not-assessed when no matching release is compiled. With any other area code, callers must also name a code-set-compatible from={geography}/{release} and a published crosswalk; the target's geography is the crosswalk's, so a combined authority, county, integrated care board or any other published membership target is summed the same way a region is. The crosswalk must declare membership: a clean-containment or full area-overlap crosswalk is membership by construction, an official lookup only where it declares relationshipPurpose: membership, and an identity lookup never, because it relates two vintages of one area rather than the parts of a larger one. It must then show complete one-to-one source-area membership for the target; split or partial overlap is rejected rather than used as an implicit conversion, and a target the crosswalk never mentions is 404 rather than a sum of nothing. aggregation.membership names which of those claims the total rests on, and aggregation.coverage is partial when the partition has no value for some of the areas the crosswalk places in the target. A place reference such as region/E12000001 names the target's geography as well as its code, and a crosswalk that maps to any other geography is refused.

A published relationship path may be named with path in place of crosswalk, to reach a target no single crosswalk maps to, such as wards summed into a region through their local authorities. Every step must run forward and declare membership, as a crosswalk must, or be an extent continuity step, which carries an area onto the same extent in a later release, under its own code or a new one; an identity lookup or a reversed step is refused. A source area is a member only if every step carries it wholly into one area and the last of those is the target, and any source that reaches the target another way refuses the whole sum. aggregation.membership is then composed-membership-path, and aggregation.path lists each step's crosswalk and membership claim. period, geography and boundaryYear may be left out: a named location's member geography or a country's local authorities name the geography, and the newest partition and its latest period are used. What was chosen is returned in defaults. place may also be the name of a named location or a country, such as place=north wales.

This route does not select a boundary release or perform a code or geometry conversion.