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.

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"
      }
    }
  ]
}