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:

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

Search results matching criteria

Body

linkedIdentifiers*linkedIdentifiers

Request

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

Response

{
  "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

Search results matching criteria

Body

linkedIdentifier*linkedIdentifier

correlations*correlations

Request

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

Response

{
  "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

Search results matching criteria

Body

linkedIdentifier*linkedIdentifier

correlations*correlations

Request

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

Response

{
  "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

Returns product version information about the requested correlation

Body

methodIdentifiercorrelationMethodIdentifier (enum)

productCreationDate*string

productPublicationNamestring

identifier1Source*identifierSource (object)

identifier2Source*identifierSource (object)

Request

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

Response

{
  "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:

PreviousGetting started with implementing a look-up application NextOS Places API

Last updated 7 months ago

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