UK Data AtlasAPI

Convert a coordinate

Convert between WGS 84 and the supported UK national grids while keeping the transformation and any precision caveat visible.

get
/coordinates:convert

Good to know

  • Use crs=EPSG:27700 for British National Grid easting/northing or a grid reference.
  • The result is a horizontal position; it does not infer elevation or a terrain value.

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

    The requested output CRS. point is always WGS 84; choose a national grid here to add target with easting and northing. The API rejects a point that falls outside its supported range for the requested grid.

    One ofEPSG:4326EPSG:27700EPSG:29902
    DefaultEPSG:4326
  • gridrefDigitsinteger 1–5optional

    With to=EPSG:27700, the maximum number of digits per coordinate in target.gridReference. The API may return fewer digits when the input or transformation uncertainty requires a coarser cell. It is invalid with another target CRS.

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

  • 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

CoordinateConversionEnvelope

The normalised WGS 84 coordinate, and an optional requested national-grid coordinate, with transparent precision.

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

  • dataCoordinateConversionrequired
    Show4 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
    • targetCrsenumrequired
      One ofEPSG:4326EPSG:27700EPSG:29902
    • targetobjectoptional

      Present when to requests a national grid. The named EPSG transformation is used in its inverse direction from WGS 84.

      Show6 child fields
      • crsenumrequired
        One ofEPSG:27700EPSG:29902
      • eastingnumberrequired
      • northingnumberrequired
      • uncertaintyMnumberrequired

        Input uncertainty plus the transformation's stated accuracy, in metres.

      • gridReferenceobjectoptional

        A British National Grid cell containing the target coordinate, present only for an encodable EPSG:27700 target. Its cell is no finer than the target uncertainty permits.

        Show4 child fields
        • valuestringrequired
        • digitsintegerrequired
        • cellSizeMnumberrequired
        • positioncontaining-cellrequired
      • transformationobjectrequired
        Show5 child fields
        • namestringrequired
        • epsgstringrequired
        • accuracyMnumberrequired
        • areaOfUsestringrequired
        • directioninverserequired
    • notestringrequired

When it goes wrong

  • 400A query parameter is malformed or its cursor is not valid for this result set.

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

Technical notes

Show the precise behaviour

Converts one horizontal coordinate without reading a boundary release. Its point is always normalised to WGS 84. By default that is the full response; select to=EPSG:27700 or to=EPSG:29902 to also receive a British National Grid or Irish Grid coordinate. Supply default WGS 84 lng and lat, British National Grid easting and northing or an Ordnance Survey gridref with crs=EPSG:27700, or Irish Grid easting and northing with crs=EPSG:29902.

The answer keeps the input form and named transformation. An Ordnance Survey grid reference denotes a square, not a point: the coordinate is the cell centre and uncertainty includes the square's half-diagonal. A British National Grid target also supplies its containing National Grid cell when one can represent the coordinate without overstating uncertainty; gridrefDigits can request a coarser cell. This route only converts horizontal position; it neither determines altitude nor implies an administrative-area relationship.