Technical specification

This technical specification explains the content of the OS Match & Cleanse API, and the methods that you can use to call it.

If you are not familiar with the OS Match & Cleanse 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

The OS Match & Cleanse API is only available on a Premium Plan.

OS Match & Cleanse API has one type of request:

• Match for granular matching and cleansing of existing address records.

Returns matched addresses

GEThttps://api.os.uk/search/match/v1/match

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/match/v1/match?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"
      }
    }
  ]
}