UK Data AtlasAPI

Rank areas by change

Find where things changed most between two periods, such as where population grew fastest between 2011 and 2022. Add place to see one area's change and where it ranks against all the others.

get
/data/{measure-id}/change

Good to know

  • by=absolute ranks the plain difference. by=relative ranks it as a proportion of the starting value.
  • Relative change isn't offered for percentages: going from 2% to 4% isn't really "100% growth".

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

  • geographystringoptional

    The geography of the source partition the change is measured inside. Both periods come from that one partition.

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

  • startPeriodstringoptional

    The period the change is measured from. Left out, the latest period before endPeriod that does not overlap it.

  • endPeriodstringoptional

    A published period of the partition after startPeriod. Left out, the partition's latest period.

  • bystringoptional

    Whether change is the difference in the published unit, or that difference as a proportion of the start value.

    One ofabsoluterelative
    Defaultabsolute
  • orderstringoptional

    desc puts the largest rise first, asc the largest fall.

    One ofascdesc
    Defaultdesc
  • placestringoptional

    The area, as its name, its code in the source partition, such as E08000035, or a place reference from /places, such as localAuthority/E08000035, which also names its geography. A name is read among the areas the measure is published for; one that means several is a 409 listing each. A postcode, or a larger place the measure is summed over, is answered by /data/{measure-id}/value.

  • 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 competition ranks of change for the source partition.

  • 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 measure is a rank, decile or category; its partition publishes a single period; the two periods overlap; or a geometry release, conversion or aggregation was asked for.
  • 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 how each area changed between two periods, ranked: the question "where did population grow fastest between 2011 and 2022?" Pass place for one area, which keeps its rank among all of them, so "Manchester grew 13.2%, 42nd of 361" is a single call.

Change is measured inside one source partition, never across two. The publisher restates every period of a partition on a single set of codes, so an area code names the same ground at the start and the end. Pairing periods from partitions on different codes would pair areas that are not the same place, so it is not offered. A partition that cannot be chosen returns a 400 listing the partitions and how many periods each has.

The geography may be left out when place names an area, by name or code, or the measure is published on one geography. The boundary year and periods may be left out too: the newest partition is used, ending at its latest period and starting at the latest one before the end that does not overlap it. What was chosen is returned in defaults.

by=absolute ranks the end value less the start, in the measure's unit. by=relative ranks that as a proportion of the start, and is refused for a ratio: change in a share is read in points, and a rise in coverage from 2% to 3% is not usefully called 50%. An area whose start is zero has no relative change and is left out of a relative ranking, counted in coverage.withoutRelativeChange. Currency is nominal and not adjusted for inflation.

Some changes are refused outright. A rank or decile is a position among the other areas rather than a quantity, so a move in it is not change in the area. A partition publishing one period has nothing to change between. Rolling windows that share years, such as life expectancy for 2017-2019 and 2018-2020, are refused because most of the apparent change is the same data counted twice.

Where the publisher gives intervals, each record says whether the start and end intervals overlap. Intervals that do not overlap mean the change is unlikely to be chance; intervals that do overlap do not show that it is. Areas with a value in only one period are listed in coverage.onlyAtStart and coverage.onlyAtEnd rather than paired with anything.