UK Data AtlasAPI

Get a value for a place

The quickest way to answer a question like "what was the population of the North West in 2022?". Give a measure and a place name and you get a single number back, with a note of exactly how it was worked out.

get
/data/{measure-id}/value

Good to know

  • Leave out period to get the latest one. The answer tells you when it did that, with periodDefaulted.
  • If a name could mean several places with different answers, you'll get a 409 listing the choices. Pass one of their place references to pick.
  • Already know the area code? Get observations or Get a time series give you more control.

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

  • placestringoptional

    A place name, an area code, a unit postcode, or a place reference such as localAuthority/E08000003 or postcode/SW1A1AA from GET /v1/places. One of place or postcode is required.

  • postcodestringoptional

    A full unit postcode, in any case and with or without its space. Refused as /postcodes/{postcode} refuses it.

  • geographystringoptional

    With postcode, the geography to answer in, such as lsoa or localAuthority. Omit for the finest that answers.

  • boundaryYearstringoptional

    With postcode, the boundary year of the partition to answer from. Omit for the newest.

  • periodstringoptional

    A published period. Omit for the latest.

Returns

Envelope

The answer, the place it is for, and the route that gives it.

  • 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 published measure has that id, or no place is called or coded that.
  • 409The name gives more than one distinct answer. choices lists each place with its answer and the request that asks about it alone.
  • 422The name matches places, but the measure answers none of them. candidates says why for each.
  • 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

A deliberately narrow convenience for a place-name question, not the primary way to fetch one observation: it resolves the name and dispatches to a route that already serves that kind of place. Ask /data/{measure-id} for observations, or /data/{measure-id}/series for one area's values, when the area is already known.

It answers "what is the population of the North West?" in one call. The place may be a name, an area code or a place reference from /places; the period may be omitted, in which case the latest the chosen partition publishes is used and the answer says so. Where a name may mean several places, GET /v1/places?q=Newport lists them first, and a candidate's place reference asks about that one alone: GET /v1/data/population/value?place=localAuthority/W06000022.

Nothing is computed here. Each place the name could mean is put to the route that already serves that kind of place: series for an area, aggregate for a curated location or a country. The value, its provenance and every refusal are exactly what that route gives, and via names the call that gives the answer directly, for citing or repeating.

The candidate is chosen by what the measure can answer rather than by guessing what was meant. Places matching the name exactly are tried first; names merely beginning with it only when no exact match answers. Answers resting on the same partition, period and area codes are the same ground reached two ways and count once, keeping the publisher's own observation over an aggregate of one member: Manchester the authority and Manchester the curated location of that authority give one answer. The other places the name matched are listed in otherMatches, answered or not.

When the name gives more than one distinct answer, the usual geography tier chooses the most likely match. question.placeDefaulted says this happened and otherMatches lists every alternative with its answer or refusal. "Newport", for example, defaults to the Welsh authority over wards of the same name. When the name matches places but the measure answers none, the response is a 422 with a candidates member saying why for each, such as a median, which cannot be summed over a region.

Give postcode instead of place to answer for where a unit postcode is: GET /v1/data/imd-decile/value?postcode=M1 1AE. The postcode's centroid is placed in the areas the data was published for, as drawn for the data's own boundary year rather than today's, in a boundary release holding that partition's codes; boundaryMatch names it. With no geography, the finest geography the measure is published on is tried first, and a coarser one only where a finer does not cover the postcode's country or has no value there; passedOver says why, and otherGeographies gives the request for each other geography. A centroid on a shared boundary whose areas answer differently is a 409 with choices, and a postcode no geography answers is a 422 with a candidates member saying why for each.