UK Data AtlasAPI

Find the nearest areas

Get the areas closest to a point, nearest first, with the distance to each. It answers the questions a containment lookup can't, like which ward is nearest a point just offshore.

get
/areas:near

Good to know

  • A distance of zero means the point touches the area, but only Find areas at a point says an area contains it.
  • within sets how far to look, in metres, and limit how many areas to return.

Query parameters

  • lngstringoptional

    Longitude in WGS 84 decimal degrees, -180 to 180.

  • lonstringoptional

    Alias for lng, the WGS 84 longitude in decimal degrees.

  • longitudestringoptional

    Alias for lng, the WGS 84 longitude in decimal degrees.

  • latstringoptional

    Latitude in WGS 84 decimal degrees, -90 to 90.

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

    Easting in grid metres. Required with crs=EPSG:27700 or crs=EPSG:29902; do not combine it with WGS 84 lng/lat.

  • northingstringoptional

    Northing in grid metres. Required with crs=EPSG:27700 or crs=EPSG:29902; do not combine it with WGS 84 lng/lat.

  • gridrefstringoptional

    A two-letter Ordnance Survey National Grid reference, followed by an even number of digits from 2 to 10, for example TQ 30000 80000. Use only with crs=EPSG:27700; do not combine it with easting or northing. A grid reference denotes a square, represented by its cell centre with the cell's half-diagonal included in uncertainty.

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

  • limitinteger 1–10optional

    How many areas to return per geography, 1 to 10.

    Default1
  • withininteger 1–50000optional

    The furthest an area may be, in whole metres, up to 50 km.

    Default1000

Returns

NearestAreasEnvelope

Each requested geography's nearest areas, with their distances.

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

  • dataNearestAreasrequired
    Show8 child fields
    • pointLookupPointrequired
      Show5 child fields
      • lngnumberrequired
      • latnumberrequired
      • crsEPSG:4326required
      • precisionobjectrequired
        Show3 child fields
        • decimalPlacesobjectrequired
        • uncertaintyMnumberrequired

          How far the true position may lie from the coordinate, in metres.

        • basisstringrequired
          One ofstated-accuracydecimal-placesstated-accuracy-and-transformationdecimal-places-and-transformationgrid-reference-and-transformationstated-accuracy-and-grid-reference-and-transformation
      • inputobjectoptional

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

        Show5 child fields
        • crsenumrequired
          One ofEPSG:27700EPSG:29902
        • eastingnumberrequired
        • northingnumberrequired
        • gridReferenceobjectoptional

          Present when an Ordnance Survey National Grid reference was supplied.

        • transformationobjectrequired
    • datestringoptional
    • withinintegerrequired
    • limitintegerrequired
    • relationdistancerequired
    • distanceMethodstringrequired
    • resultsPointLookupRelease[]required
      Show15 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
        One offoundnone-withinambiguous-releaseno-release-for-dategeometry-unavailable
      • detailstringoptional
      • choicesReleaseReference[]optional
        Show5 child fields
        • idstringrequired
        • monthstringrequired
        • titlestringrequired
        • countriesstring[]required
        • hrefstringrequired
      • earliestReleaseReferenceoptional
        Show5 child fields
        • idstringrequired
        • monthstringrequired
        • titlestringrequired
        • countriesstring[]required
        • hrefstringrequired
      • matchedintegeroptional
      • truncatedbooleanoptional
      • nearestobject[]required
        Show6 child fields
        • rankintegerrequired
        • idstringrequired
        • codestringrequired
        • namestringrequired
        • distanceMnumberrequired

          Metres to the area, zero when the point is on or inside it. Not a containment claim.

        • geometrySourceGeometrySourceoptional

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

    • notestringrequired

When it goes wrong

  • 400The point, limit, within or accuracy is malformed or out of range, or the geographies and releases 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

Returns up to limit areas of each requested geography whose published geometry lies within within metres of the point, nearest first. Releases are selected exactly as for areas:contains.

The coordinate forms are the same as areas:contains: default WGS 84 lng/lat (lon and longitude are also accepted for longitude), British National Grid easting/northing or an Ordnance Survey gridref with crs=EPSG:27700, or Irish Grid metres with crs=EPSG:29902.

This is a distance answer, labelled relation: distance, and never a containment one. An area at zero metres has the point on or inside it, but only areas:contains makes that claim, with its boundary rule and tolerance. Use this route where containment has nothing to say: a point offshore or in an estuary that a generalised boundary leaves out, or a site for which the nearest few areas all matter.

Distances are to the nearest part of each area's geometry, measured on the WGS 84 ellipsoid in a plane tangent at the point, which within the 50 km this route reaches departs from the geodesic by less than a tenth of a percent. They carry the coordinate's own uncertainty, given in point.precision. matched counts every area within the distance, and truncated says whether limit cut it.