Technical specification

Product has reached its End of Life (withdrawal) date

The OS Match & Cleanse API reached its End of Life on 31 March 2026 and was withdrawn. As a result, the API has been removed from existing API projects and is no longer be accessible. Historic usage of this API can still be tracked in the API Transaction History tab of the OS Data Hub.

Documentation on this site for the API will remain in place for a short time to support customers migrating to a new solution. Future requests made to the OS Match & Cleanse API will fail. For further information, please visit End of Life Information.

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

OS Match & Cleanse API has one type of request:

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

API test authentication

The Open API block allows you to test OS APIs directly from the page with example data and parameters. To use this feature, you will need to add your API Key or OAuth2 token to the authentication field.

For help generating an API Key or OAuth2 token, please see the Getting started with an API project or OAuth2 documentation.

Returns matched addresses

get

Authorizations

api-key & api-key-header & oauth2

keystringRequired

keystringRequired

OAuth2clientCredentialsRequired

Token URL:

Query parameters

querystringRequired

Free text search parameter.

formatstring · enumOptional

The format the response will be returned in. Default: JSON.

Default: JSONPossible values:

maxresultsinteger · min: 1 · max: 100Optional

The maximum number of results to return. Default: 100.

Default: 100

offsetintegerOptional

Offset the list of returned results by this amount.

Default: 0

datasetstring · enumOptional

The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.

Default: DPAPossible values:

lrstring · enumOptional

Which language of addresses to return. Default: EN, CY.

Possible values:

minmatchnumber · min: 0.1 · max: 1Optional

The minimum match score a result has to have to be returned.

matchprecisionnumber · min: 1 · max: 10Optional

The decimal point position at which the match score value is to be truncated.

output_srsstring · enumOptional

The intended output spatial reference system. Default: EPSG:27700

Default: EPSG:27700Possible values:

fqstring[]Optional

Filter for classification code, logical status code, LPI logical status code and/or country code. Filtering for classification code will accept wildcard ( * ) searches. Multiple searches can be done by separating the codes with a space. Multiple filters can be used together by including the parameter multiple times

Example: ["CLASSIFICATION_CODE:CI CLASSIFICATION_CODE:RD","LOGICAL_STATUS_CODE:6","LPI_LOGICAL_STATUS_CODE:3","COUNTRY_CODE:EN"]

Responses

200

Retrieves matched addresses

application/jsonapplication/xml

get/match

HTTPcURLJavaScriptPython

GET /search/match/v1/match?query=text HTTP/1.1
Host: api.os.uk
key: YOUR_API_KEY
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

200

Retrieves matched addresses

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