UK Data AtlasAPI

Find areas for many points

The same lookup as Find areas at a point, for up to 100 points in one request. Handy for tagging a list of sites or addresses with their ward and council.

post
/areas:containsBatch

Good to know

  • Give each point as point={lng},{lat}, repeated. Add a third number for its accuracy in metres.
  • Details that are the same for every point, like which boundary release was used, are given once in releases rather than repeated per point.
  • For more than 100 points, send them in batches.

Query parameters

  • crsstringoptional

    The input coordinate reference system. The default EPSG:4326 uses lng and lat; EPSG:27700 uses British National Grid easting and northing or an Ordnance Survey gridref; EPSG:29902 uses Irish Grid easting and northing.

    One ofEPSG:4326EPSG:27700EPSG:29902
    DefaultEPSG:4326
  • geographystring[]optional

    A geography to look the point up in. Repeat it or give a comma-separated list, up to four in total. A geography named only in a pinned release need not be repeated here.

  • releasestring[]optional

    A release to pin, as {geography}/{release}, such as ward/2025-12-uk-bgc, or ward/latest for its newest unambiguous published release. A bare release id is accepted when exactly one geography is requested. A pinned release is used whatever date says.

  • datestringoptional

    A calendar date as YYYY-MM-DD, or a month as YYYY-MM. Every geography without a pinned release uses the latest release dated on or before it; without a date it uses the newest unambiguous published release. The country boundaries used to place a point that matches nothing are chosen the same way.

  • accuracynumberoptional

    How far the true position may lie from the coordinate, in metres, such as a GPS fix's reported accuracy. Without it, uncertainty is half the coordinate's last written decimal place, which overstates it where a client drops trailing zeros.

Returns

PointContainmentBatchEnvelope

Each point's containing areas in every requested release.

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

  • dataPointContainmentBatchrequired
    Show6 child fields
    • datestringoptional
    • boundaryRuleincludedrequired
    • releasesPointLookupRelease[]required
      Show12 child fields
      • geographystringrequired
      • boundaryReleasestringoptional
      • hrefstringoptional
      • selectionobjectrequired
        Show4 child fields
        • policystringrequired
          One ofpinnedlatest-release-dated-on-or-before
        • datestringoptional
        • sameMonthbooleanoptional
        • nextReleaseReference | nulloptional
      • coverageobjectoptional
        Show1 child field
        • countriesstring[]required
      • boundaryResolutionobjectoptional

        How much the boundary's lines were generalised, read from the ONS release name. undeclared where the name does not say.

        Show4 child fields
        • generalisationstringrequired
        • extentstringoptional
          One ofclipped-to-coastlinefull-extent-of-realm
        • toleranceMnumberoptional
        • basisons-release-nameoptional
      • geometrySourceGeometrySourceoptional

        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.

      • sourceobjectoptional
        Show2 child fields
        • publisherstringoptional
        • licenceobjectoptional
      • statusstringoptional

        ambiguous-release, no-release-for-date or geometry-unavailable when no release could be read. The schema this is combined with lists every status a result may carry.

      • detailstringoptional
      • choicesReleaseReference[]optional
        Show5 child fields
        • idstringrequired
        • monthstringrequired
        • titlestringrequired
        • countriesstring[]required
        • hrefstringrequired
      • earliestReleaseReferenceoptional
        Show5 child fields
        • idstringrequired
        • monthstringrequired
        • titlestringrequired
        • countriesstring[]required
        • hrefstringrequired
    • summaryobjectrequired
      Show7 child fields
      • pointsintegerrequired
      • lookupsintegerrequired
      • matchedintegerrequired
      • noMatchintegerrequired
      • outsideCoverageintegerrequired
      • unresolvedintegerrequired

        Lookups with no answer about the point, such as an ambiguous release.

      • nearBoundaryintegerrequired
    • pointsobject[]required
      Show4 child fields
      • indexintegerrequired
      • pointLookupPointrequired
        Show5 child fields
        • lngnumberrequired
        • latnumberrequired
        • crsEPSG:4326required
        • precisionobjectrequired
        • inputobjectoptional

          Present when British National Grid or Irish Grid input was transformed to WGS 84.

      • countryPointCountryrequired

        The UK country the point lies in. area-code reads it from a matched area's GSS code; country-boundary tests the point against a country release, and a null code there means no UK country contains it.

        Show5 child fields
        • codestring | nullrequired
          One ofGB-ENGGB-NIRGB-SCTGB-WLSnull
        • determinedBystringrequired
          One ofarea-codecountry-boundaryundetermined
        • areastringoptional
        • boundaryReleasestringoptional
        • detailstringoptional
      • resultsPointLookupResult[]required

        One per entry in releases, in the same order.

        Show7 child fields
        • geographystringrequired
        • boundaryReleasestringoptional
        • statusstringrequired
          One ofmatchedno-matchoutside-coverageambiguous-releaseno-release-for-dategeometry-unavailable
        • reasonstringoptional
          One ofcountry-not-coveredoutside-uk-boundaries
        • detailstringoptional
        • positionalToleranceMnumberoptional

          Coordinate uncertainty, boundary generalisation and transformation accuracy added together, in metres.

        • matchesobject[]required
    • notestringrequired

When it goes wrong

  • 400No point is given, more than 100 are, or one is malformed, and the detail names it; or the geographies, releases, date or accuracy are refused as for areas:contains.
  • 404No resource matches that identity.
  • 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

The areas:contains lookup for up to 100 points at once, each given in the JSON body's points array as {lng},{lat} or {lng},{lat},{accuracy} in the default WGS 84, as point={easting},{northing} with crs=EPSG:27700 or EPSG:29902, or as one Ordnance Survey reference such as point=TQ3000080000 with crs=EPSG:27700. Geographies, release selection and statuses are exactly as for a single point.

Release-wide facts, including selection, coverage, resolution and geometry provenance, are given once in releases. Each point then lists its country and, per release in the same order, its status and matches; a match carries corrections only where a declared grid correction moved that area. summary counts the lookups by outcome and how many have a match near a boundary.

Every release is read once for all the points, so the cost of a batch grows with its points rather than with its points times its geographies. This is a bounded convenience for a caller's own point dataset, not a bulk geocoder: for more points, page through them in batches.