Technical specification

This technical specification explains the content of the OS Places API and the methods that you can use to call it.

If you are not familiar with the OS Places API please read the overview documentation before proceeding.

Core concepts

This specification does not cover core concepts that apply to all Ordnance Survey APIs.

Please read the following pages to learn more about OS API core concepts:

• Authentication

• Error codes

• Rate-limiting policy

API reference

OS Places API has seven types of requests, that fall into two categories:

• Capture and verification:

  • Find: A free text search designed for quick use.

  • Postcode: A search based on a property’s postcode.

  • UPRN: A search that takes a UPRN as the search parameter.

• GeoSearch:

  • Nearest: Can find the closest address to a given point.

  • BBox: Can find all addresses inside a bounding box.

  • Radius: Can find all addresses that intersect a given circle.

  • Polygon: Can find all addresses in a polygon or multi-polygon object.

Returns matched addresses based on a free text search.

GEThttps://api.os.uk/search/places/v1/find

Authorization

api-key

Query parameters

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/find?query=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}

Returns matched addresses based on a property's postcode.

GEThttps://api.os.uk/search/places/v1/postcode

Authorization

api-key

Query parameters

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/postcode?postcode=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}

Returns matched addresses based on a UPRN.

GEThttps://api.os.uk/search/places/v1/uprn

Authorization

api-key

Query parameters

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/uprn?uprn=0', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}

Returns closest addresses to a pair of coordinates (X and Y).

GEThttps://api.os.uk/search/places/v1/nearest

Authorization

api-key

Query parameters

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/nearest?point=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}

Returns matched addresses within a bounding box.

GEThttps://api.os.uk/search/places/v1/bbox

Authorization

api-key

Query parameters

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/bbox?bbox=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}

Takes a pair of coordinates as the centre for a circle and returns all addresses that are intersected by it.

GEThttps://api.os.uk/search/places/v1/radius

Authorization

api-key

Query parameters

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/radius?point=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}

Returns matched addresses within a geoJSON polygon or multi-polygon object.

POSThttps://api.os.uk/search/places/v1/polygon

Authorization

api-key

Query parameters

Header parameters

Body

application/json

type*string

geometry*object

Response

200

Retrieves matched addresses

Body

application/jsonapplication/xml

headerobject

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/places/v1/polygon', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "type": "text"
    }),
});
const data = await response.json();

Response

200

{
  "header": {
    "uri": "text",
    "query": "text",
    "offset": 0,
    "totalresults": 0,
    "format": "text",
    "dataset": "text",
    "lr": "text",
    "maxresults": 0,
    "matchprecision": 0,
    "epoch": "text",
    "lastupdate": "text",
    "output_srs": "text"
  },
  "results": [
    {
      "DPA": {
        "UPRN": 0,
        "UDPRN": 0,
        "ADDRESS": "text",
        "ORGANISATION_NAME": "text",
        "DEPARTMENT_NAME": "text",
        "SUB_BUILDING_NAME": "text",
        "BUILDING_NAME": "text",
        "BUILDING_NUMBER": 0,
        "DEPENDENT_THOROUGHFARE_NAME": "text",
        "THOROUGHFARE_NAME": "text",
        "DOUBLE_DEPENDENT_LOCALITY": "text",
        "DEPENDENT_LOCALITY": "text",
        "POST_TOWN": "text",
        "POSTCODE": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text",
        "DELIVERY_POINT_SUFFIX": "text"
      },
      "LPI": {
        "UPRN": 0,
        "ADDRESS": "text",
        "USRN": 0,
        "LPI_KEY": "text",
        "ORGANISATION": "text",
        "SAO_START_NUMBER": 0,
        "SAO_START_SUFFIX": "text",
        "SAO_END_NUMBER": 0,
        "SAO_END_SUFFIX": "text",
        "SAO_TEXT": "text",
        "PAO_START_NUMBER": 0,
        "PAO_START_SUFFIX": "text",
        "PAO_END_NUMBER": 0,
        "PAO_END_SUFFIX": "text",
        "PAO_TEXT": "text",
        "STREET_DESCRIPTION": "text",
        "LOCALITY_NAME": "text",
        "TOWN_NAME": "text",
        "ADMINISTRATIVE_AREA": "text",
        "AREA_NAME": "text",
        "POSTCODE_LOCATOR": "text",
        "RPC": "text",
        "X_COORDINATE": 0,
        "Y_COORDINATE": 0,
        "LNG": 0,
        "LAT": 0,
        "STATUS": "text",
        "LOGICAL_STATUS_CODE": 0,
        "CLASSIFICATION_CODE": "text",
        "CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LOCAL_CUSTODIAN_CODE": 0,
        "LOCAL_CUSTODIAN_CODE_DESCRIPTION": "text",
        "COUNTRY_CODE": "text",
        "COUNTRY_CODE_DESCRIPTION": "text",
        "POSTAL_ADDRESS_CODE": "text",
        "POSTAL_ADDRESS_CODE_DESCRIPTION": "text",
        "BLPU_STATE_CODE": 0,
        "BLPU_STATE_CODE_DESCRIPTION": "text",
        "TOPOGRAPHY_LAYER_TOID": "text",
        "WARD_CODE": "text",
        "PARISH_CODE": "text",
        "PARENT_UPRN": 0,
        "LAST_UPDATE_DATE": "text",
        "ENTRY_DATE": "text",
        "LEGAL_NAME": "text",
        "BLPU_STATE_DATE": "text",
        "STREET_STATE_CODE": 0,
        "STREET_STATE_CODE_DESCRIPTION": "text",
        "STREET_CLASSIFICATION_CODE": "text",
        "STREET_CLASSIFICATION_CODE_DESCRIPTION": "text",
        "LPI_LOGICAL_STATUS_CODE": 0,
        "LPI_LOGICAL_STATUS_CODE_DESCRIPTION": "text",
        "LANGUAGE": "text",
        "MATCH": 0,
        "MATCH_DESCRIPTION": "text"
      }
    }
  ]
}