Join your rows to a release
Send your own area codes or names and values, then receive the rows matched to one boundary release and keyed by the numeric id its tiles use.
/boundary-releases/{geography}/{release}:joinGood to know
- Rows that cannot identify exactly one area are returned in
unjoinedwith the reason, rather than being guessed or dropped. - Use
format=geojsonwith a suitabletierwhen you need the matched shapes as well as the join table.
geographystringrequiredA geography type id, e.g.
constituencyorward.releasestringrequiredA boundary release id, e.g.
2024-07-uk-bgc, orlatestfor the geography's newest release: the one/boundary-releases:resolvechooses for the furthest date. A response tolatestnames the release it read inContent-Location. A geography whose newest month holds several releases that differ in more than coverage, or that has a release whose id carries no month, is refused with409and the releases that could be newest.
formatstringoptionaljsonfor the join table,geojsonfor the joined areas with their geometry.One ofjsongeojsonDefaultjsontierstringoptionalThe geometry detail for
format=geojson, as on the map resource's features.One offullhighmediumlowDefaultmedium
Returns
EnvelopeThe joined values, numbered as the release's tiles, the rows that did not join and why, a summary, and links to the release's map resource and tiles. With format=geojson, a GeoJSON FeatureCollection of the joined areas.
apiVersionv1requiredatlasReleasestringrequiredThe immutable
/atlas-releasereleaseIdfor the artifacts that produced this response.metaobjectrequiredShowHide1 child field
nextCursorstring | nullrequiredOpaque cursor for the next page, or null at the end.
- 400The query is malformed, or the body cannot be read as rows with values.
- 404No resource matches that identity.
- 405The join was asked for with GET; it reads its rows from a POST body.
- 413The body is larger than 8 MiB, or holds more than 250,000 rows.
- 415The body is declared as neither JSON nor CSV. A body sent as form-urlencoded, as curl does by default, or with no type is read as JSON when it opens with { or [, and as CSV otherwise.
- 422The requested GeoJSON tier is too large to read for one request.
- 503The referenced build artifact has not been built yet.
Every error has the same shape. See Errors for how to handle them.
Show the precise behaviourHide the precise behaviour
Send a column of area codes or names with a value each, and get the values back numbered as this release's tiles and downloads number their features, ready to draw on its map resource. Nothing is stored: the request carries the data, and the answer is never cached.
Send JSON, {"rows": [{"area": "E05000650", "value": 12.5}]}, where the area may also be given as code or name and a row may carry a parent to settle a shared name, or CSV with a header naming the area column area, code or name, a value column and optionally a parent column. A CSV cell reading as a number is a number, and an empty one is null; any other value, JSON included, is passed through as sent. At most 250,000 rows in an 8 MiB body.
Each row is read as areas:validate reads it. A code must be in this release, and a name must mean exactly one of its areas. A row that does not is listed in unjoined with its reason and the validator's full result: a superseded code says which releases hold it, and an ambiguous name lists its candidates. Two rows naming the same area leave that area out, both listed as duplicate-area, because which value was meant is the caller's to say. values holds one row per joined area, as id, code, name and value, where id is the integer the tiles carry, so a renderer sets feature state by it.
With format=geojson the joined areas come back as a GeoJSON FeatureCollection at the requested tier, each feature's properties carrying its value, with the release's attribution and the join summary beside the features. A tier whose GeoJSON exceeds 64 MB is refused with 422, since the join table and the tiles draw the same map without parsing a whole release per request.