UK Data AtlasAPI

Find areas at a point

Which ward is this spot in? Give a longitude and latitude and get the area, or areas, of one geography that contain it.

get
/areas:contains

Good to know

  • A point exactly on a border belongs to both sides, so you can get more than one result. Those are labelled boundary.

Query parameters

  • lngstringoptional

    Longitude in WGS 84 decimal degrees, -180 to 180. Written as a plain decimal: its decimal places are read as its precision.

  • 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, as for lng.

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

  • postcodestringoptional

    A unit postcode such as SW1A 1AA, the space optional, in place of a coordinate. It cannot be combined with lng, lat, easting, northing, gridref, crs or accuracy.

  • 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

PointContainmentEnvelope

Each requested geography's containing areas, or why there are none.

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

  • dataPointContainmentrequired
    Show7 child fields
    • postcodeobjectoptional

      Present when the point is a postcode's centroid.

      Show5 child fields
      • postcodestringrequired
      • statusenumrequired
        One ofliveterminated
      • hrefstringrequired
      • cautionstringoptional

        Present when the directory does not state how accurate the centroid is.

      • sourceobjectrequired
        Show5 child fields
        • titlestringoptional
        • editionstringoptional
        • publisherstringoptional
        • licenceanyoptional
        • attributionstringoptional
    • 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
    • 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
    • boundaryRuleincludedrequired
    • resultsPointLookupRelease[]required

      One per requested geography, in the order requested.

      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
      • statusstringrequired
        One ofmatchedno-matchoutside-coverageambiguous-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
      • reasonstringoptional
        One ofcountry-not-coveredoutside-uk-boundaries
      • positionalToleranceMnumberoptional

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

      • matchesobject[]required
        Show9 child fields
        • idstringrequired
        • codestringrequired
        • namestringrequired
        • aliasesstring[]optional
        • containmentstringrequired
          One ofinteriorboundary
        • distanceToBoundaryMnumberrequired

          Metres from the point to the area's nearest edge.

        • nearBoundarybooleanrequired

          The edge lies within positionalToleranceM.

        • geometrySourceGeometrySourceoptional

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

        • correctionsobject[]optional
    • notestringrequired

When it goes wrong

  • 400The point is missing, malformed or out of range; a postcode is not a unit postcode, or is given with a coordinate; more than four geographies are named; a geography has neither a pinned release nor a date; a bare release id is given with several geographies; or date or accuracy is malformed.
  • 404A pinned release is not published or not compiled, or a geography is unknown; or the postcode is not in the directory edition served, or the directory gives it no grid reference.
  • 451The postcode is in Northern Ireland, which this API is not licensed to serve.
  • 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

Tests a point against one boundary release of each requested geography, at most four in one request, and says for each what contains it or why nothing does.

Supply WGS 84 lng (also accepted as lon or longitude) and lat (the default), or set crs=EPSG:27700 and supply British National Grid easting and northing or an Ordnance Survey gridref such as TQ 30000 80000. Set crs=EPSG:29902 for Irish Grid metres. Or give a unit postcode instead of a coordinate: it is placed by its ONS Postcode Directory centroid, with the directory's own stated accuracy, exactly as /postcodes/{postcode} places it, and the answer names the postcode. A grid reference denotes a square, so its answer uses the cell centre and includes its whole half-diagonal as uncertainty. Every answer is normalised to WGS 84 and retains the input coordinate and named transformation.

Each geography's release is either pinned, as release={geography}/{release}, chosen for date as the latest one dated on or before it, or defaults to the newest unambiguous published release. With neither geography nor release, the lookup covers localAuthority, ward and constituency. Every result states its selection policy. A date no release fits, or one several releases of the same month fit equally, is reported in that geography's result as no-release-for-date or ambiguous-release rather than failing the whole lookup.

Points on an exterior or hole ring are included and labelled boundary, so a point on a shared border returns every area sharing it. A result with no match is outside-coverage when the point's country is outside the release's coverage, or outside every UK country boundary, and no-match when the release covers the point's country but no area of it contains the point. The country comes from a matched area's code where one has it, and otherwise from the country boundaries, and country.determinedBy says which.

Every result states how far its answer can be trusted. positionalToleranceM adds the coordinate's uncertainty, taken from accuracy or else from its written decimal places, the boundary's generalisation, read from the ONS release name, and the stated accuracy of any transformation from the source CRS to WGS 84. A match whose edge lies within that tolerance is nearBoundary. The geometry's source file, hash, CRS and transformation are given for each release and each match.

Each release is read into memory on first use, which can take a second or more for a large release; later lookups against it are fast.