UK Data AtlasAPI

Find areas in a box

Give a box of coordinates as west,south,east,north and get every area that meets it, each marked within the box or overlaps if it crosses the edge. It's the query a map makes as you pan around.

get
/areas:intersects

Good to know

  • You get area identities by default, which keeps wide boxes quick. Add tier to include their shapes too.

Query parameters

  • bboxstringrequired

    west,south,east,north in WGS 84 degrees, with west < east and south < north.

  • geographystringrequired

    The geography of the boundary release to search.

  • releasestringoptional

    The boundary release to search, whose geometry the box is tested against. Omit it, or use latest, for the newest unambiguous published release.

    Defaultlatest
  • tierstringoptional

    Omit for identities only. Set to a tier to include each match's geometry, generalised to it.

    One offullhighmediumlow
  • limitinteger 1–1000optional

    How many matching areas to return in a page, 1 to 1000. truncated says whether more follow.

    Default200
  • cursorstringoptional

    The meta.nextCursor of the previous page. A cursor is opaque and belongs to the query that issued it.

Returns

AreaBoxSearchEnvelope

The areas meeting the box, and how each meets 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.

  • dataAreaBoxSearchrequired
    Show14 child fields
    • bboxnumber[]required
    • geographystringrequired
    • boundaryReleasestringrequired
    • matchedintegerrequired

      Areas meeting the box, before the limit is applied.

    • returnedintegerrequired
    • limitintegerrequired
    • truncatedbooleanrequired

      Whether matched exceeded limit.

    • relationRulestringrequired
    • geometrystringoptional

      Present only when no tier was asked for, saying how to get the coordinates.

    • tierstringoptional
      One offullhighmediumlow
    • toleranceMnumberoptional
    • minEffectiveAreaM2numberoptional
    • generalisationMethodobjectoptional
      Show4 child fields
      • rulestringrequired
      • thresholdstringrequired
      • partsstringrequired
      • sharedBordersstringrequired
    • matchesAreaInRelease[]required
      Show11 child fields
      • idstringrequired
      • geographystringoptional
      • boundaryReleasestringoptional
      • codestringrequired
      • namestringrequired
      • aliasesstring[]optional
      • relationstringrequired
        One ofwithinoverlaps
      • boundingBoxnumber[]required
      • geometrySourceGeometrySourcerequired

        Where the served WGS84 geometry came from. transformation is present only when the source was reprojected.

        Show3 child fields
        • sourceCrsstringrequired
        • transformationobjectoptional
        • correctionsobject[]optional

          Declared grid corrections that moved this area before it was reprojected, such as northern-ireland-offset.

      • generalisationobjectoptional

        Present only when a tier was asked for.

        Show4 child fields
        • verticesintegeroptional
        • verticesAtFullResolutionintegeroptional
        • partsintegeroptional
        • partsAtFullResolutionintegeroptional
      • geometryGeoJsonGeometryoptional

        A GeoJSON geometry object as read from the raw cached source, or a GeometryCollection when the source represents one area code as more than one feature fragment.

        Show3 child fields
        • typestringrequired
        • coordinatesanyoptional

          Present on every geometry type except GeometryCollection.

        • geometriesGeoJsonGeometry[]optional

          Present only when type is GeometryCollection.

When it goes wrong

  • 400The box is missing or malformed, the geography or release is missing, or tier or limit is out of range.
  • 404No compiled area release matches the requested geography and release.
  • 503The area exists but its geometry cannot be served: no raw source is declared, or its CRS has no transformation to WGS84.

Every error has the same shape. See Errors for how to handle them.

Technical notes

Show the precise behaviour

Returns every area of one geography and release that meets the given WGS 84 box: the query a map makes when it pans, and the one an analysis makes to scope a region before asking for anything heavier.

relation says how each area meets the box. within means the area lies entirely inside it; overlaps means it meets the box without being contained by it. Both are exact. An area is tested against the box itself, not against its own bounding box, so a crescent whose bounding box reaches into the query while its land does not is excluded, as is a box sitting inside a lake within an area.

Identities come back by default, each with its own bounding box, and the coordinates are opted into with tier, which generalises every match exactly as the geometry route does. That keeps the cost of a wide box bounded whether or not a caller wants geometry with it. The same caveat applies: above full, matches are generalised one at a time and neighbours drawn together may disagree along a shared border.

Results come a page at a time in code order, limit to a page, 200 by default and 1000 at most. matched counts every area the box meets, truncated says whether more follow this page, and nextCursor, with a Link: rel="next" header, fetches them. For every area of a release, the whole-release download is quicker. The cap is on results rather than on the box: a box covering the whole country is a reasonable analysis question, and it is the geometry that is expensive, not the extent. A box matching nothing is an empty answer, not an error; a geography and release the catalogue does not carry is a 404.