Technical specification

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

The OS Linked Identifiers API is a free OpenData product that allows you to access the valuable relationships between properties, streets and OS MasterMap identifiers.

If you are not familiar with the OS Linked Identifiers 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 Linked Identifiers API has four main endpoints:

• Identifiers

• Identifier Types

• Feature Types

• Product Version Information

Query identifer

Query by identifier and find its associated IDs. May return more than one set of links due to the namespace overlap between UPRNs and USRNs.

GEThttps://api.os.uk/search/links/v1/identifiers/{id}

Path parameters

id*string

ID of the feature that is being matched

Response

200400401403404405429500503

Search results matching criteria

Body

application/json

linkedIdentifiers*linkedIdentifiers

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/links/v1/identifiers/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "linkedIdentifiers": [
    {
      "linkedIdentifier": {
        "identifier": "text",
        "featureType": "BLPU",
        "identifierType": "GUID"
      },
      "correlations": [
        {
          "searchedIdentifierVersionDate": "text",
          "searchedIdentifierVersionNumber": 0,
          "correlationMethodIdentifier": "RoadLink_TOID_TopographicArea_TOID_2",
          "correlatedFeatureType": "BLPU",
          "correlatedIdentifierType": "GUID",
          "correlatedIdentifiers": [
            {
              "identifier": "text",
              "versionNumber": 0,
              "versionDate": "text",
              "confidence": "text",
              "correlationIdentifier": "text"
            }
          ]
        }
      ]
    }
  ]
}

Queries ID when input identifierType is known

Returns associated Linked Identifiers, when the input identifier type is known. Returns an object.

GEThttps://api.os.uk/search/links/v1/identifierTypes/{identifierType}/{id}

Path parameters

id*string

ID of the feature that is being matched

identifierType*enum

Identifier type of ID being queried

GUIDTOIDUPRNUSRN

Response

200400401403404405429500503

Search results matching criteria

Body

application/json

linkedIdentifier*linkedIdentifier

correlations*correlations

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/links/v1/identifierTypes/{identifierType}/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "linkedIdentifier": {
    "identifier": "text",
    "featureType": "BLPU",
    "identifierType": "GUID"
  },
  "correlations": [
    {
      "searchedIdentifierVersionDate": "text",
      "searchedIdentifierVersionNumber": 0,
      "correlationMethodIdentifier": "RoadLink_TOID_TopographicArea_TOID_2",
      "correlatedFeatureType": "BLPU",
      "correlatedIdentifierType": "GUID",
      "correlatedIdentifiers": [
        {
          "identifier": "text",
          "versionNumber": 0,
          "versionDate": "text",
          "confidence": "text",
          "correlationIdentifier": "text"
        }
      ]
    }
  ]
}

Query ID when input featureType is known

Returns associated Linked Identifiers, when feature type is known. Returns an object.

GEThttps://api.os.uk/search/links/v1/featureTypes/{featureType}/{id}

Path parameters

id*string

ID of the feature that is being matched

featureType*enum

Feature type of ID being queried

BLPUORRoadNodeORRoadLinkRoadRoadLinkStreetTopographicArea

Response

200400401403404405429500503

Search results matching criteria

Body

application/json

linkedIdentifier*linkedIdentifier

correlations*correlations

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/links/v1/featureTypes/{featureType}/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "linkedIdentifier": {
    "identifier": "text",
    "featureType": "BLPU",
    "identifierType": "GUID"
  },
  "correlations": [
    {
      "searchedIdentifierVersionDate": "text",
      "searchedIdentifierVersionNumber": 0,
      "correlationMethodIdentifier": "RoadLink_TOID_TopographicArea_TOID_2",
      "correlatedFeatureType": "BLPU",
      "correlatedIdentifierType": "GUID",
      "correlatedIdentifiers": [
        {
          "identifier": "text",
          "versionNumber": 0,
          "versionDate": "text",
          "confidence": "text",
          "correlationIdentifier": "text"
        }
      ]
    }
  ]
}

Returns product version details of the source data products

Returns current valid version information for identifier relationships

GEThttps://api.os.uk/search/links/v1/productVersionInfo/{correlationMethod}

Path parameters

correlationMethod*enum

Correlation method being queried

RoadLink_TOID_TopographicArea_TOID_2Road_TOID_TopographicArea_TOID_3Street_USRN_TopographicArea_TOID_4BLPU_UPRN_TopographicArea_TOID_5RoadLink_TOID_Road_TOID_7RoadLink_TOID_Street_USRN_8BLPU_UPRN_RoadLink_TOID_9Road_TOID_Street_USRN_10BLPU_UPRN_Street_USRN_11ORRoadLink_GUID_RoadLink_TOID_12ORRoadNode_GUID_RoadLink_TOID_13

Response

200400401403404405429500503

Returns product version information about the requested correlation

Body

application/json

methodIdentifiercorrelationMethodIdentifier (enum)

RoadLink_TOID_TopographicArea_TOID_2Road_TOID_TopographicArea_TOID_3Street_USRN_TopographicArea_TOID_4BLPU_UPRN_TopographicArea_TOID_5RoadLink_TOID_Road_TOID_7RoadLink_TOID_Street_USRN_8BLPU_UPRN_RoadLink_TOID_9Road_TOID_Street_USRN_10BLPU_UPRN_Street_USRN_11ORRoadLink_GUID_RoadLink_TOID_12ORRoadNode_GUID_RoadLink_TOID_13

productCreationDate*string

productPublicationNamestring

identifier1Source*identifierSource (object)

identifier2Source*identifierSource (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.os.uk/search/links/v1/productVersionInfo/{correlationMethod}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "methodIdentifier": "RoadLink_TOID_TopographicArea_TOID_2",
  "productCreationDate": "text",
  "productPublicationName": "text",
  "identifier1Source": {
    "productName": "AddressBase Premium",
    "productPublicationDate": "text",
    "productPublicationName": "text",
    "featureType": "BLPU",
    "identifierType": "GUID"
  },
  "identifier2Source": {
    "productName": "AddressBase Premium",
    "productPublicationDate": "text",
    "productPublicationName": "text",
    "featureType": "BLPU",
    "identifierType": "GUID"
  }
}

Correlation method table

The table below lists all of the correlation methods:

Correlation method	Feature relationship
RoadLink_TOID_TopographicArea_TOID_2	RoadLink ↔ TopographicArea
Road_TOID_TopographicArea_TOID_3	Road ↔ TopographicArea
Street_USRN_TopographicArea_TOID_4	Street ↔ TopographicArea
BLPU_UPRN_TopographicArea_TOID_5	BLPU ↔ TopographicArea
RoadLink_TOID_Road_TOID_7	RoadLink ↔ Road
RoadLink_TOID_Street_USRN_8	RoadLink ↔ Street
BLPU_UPRN_RoadLink_TOID_9	BLPU ↔ RoadLink
Road_TOID_Street_USRN_10	Road ↔ Street
BLPU_UPRN_Street_USRN_11	BLPU ↔ Street
ORRoadLink_GUID_RoadLink_TOID_12	Open Roads RoadLink ↔ OSMM Highways RoadLink
ORRoadNode_GUID_RoadLink_TOID_13	Open Roads RoadNode ↔ OSMM Highways RoadLink

Please see the following documents for more information about how each of these identifiers has been linked to each other:

• OS Open Linked Identifiers Technical Specification

• Open Identifiers product family

• Open Identifiers support page