# OS Linked Identifiers API

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. It's as easy as providing the identifier you are interested in and the API will return the related feature identifiers. This allows you to find what addresses exist on a given street, or the UPRN for a building on a map, or the USRN for a road and more.

An identifier is a unique reference assigned to a specific thing. The ability to link identifiers ensures that you refer to the same single thing, even when if it is referenced by multiple identifiers. Identifiers are used all the time, such as telephone numbers, postcodes and customer reference numbers. OS strives to make its identifiers more accessible and useful for its customers.

The OS Linked Identifiers API takes this further by enabling the linking together of datasets that use different identifiers, for example linking a property address (UPRN - Unique Property Reference Number) to the street that it is on (USRN - Unique Street Reference Number).

Some of these relationships need Premium OS data and for others it is possible to create these relationships yourself through analysis of OS OpenData. However, both situations require significant effort and can yield errors. Wherever possible you should use an authoritative source for better data reliability. The OS Linked Identifiers API gives you direct access to an authoritative source for all of the relationships it publishes and removes the need for you to manage and manipulate large datasets.

These relationships can be used in conjunction with other OS APIs to, for example:

* Create clickable interactive maps for web applications to display road or building features by presenting their USRN or UPRN.
* Search for a street name and highlight all the properties that are on it.
* Visualise accident counts, pollution levels or average vehicle speed data using Open Roads.

The API was designed with ease-of-use in mind. It conforms to [OpenAPI v3.0.2 specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) and returns data in a readable [JSON](https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf) format. These standards integrate well with JavaScript and support the creation of sophisticated interactive map web applications in conjunction with our [os-maps-api](https://docs.os.uk/os-apis/accessing-os-apis/os-maps-api "mention"), [os-vector-tile-api](https://docs.os.uk/os-apis/accessing-os-apis/os-vector-tile-api "mention") and [os-features-api](https://docs.os.uk/os-apis/accessing-os-apis/os-features-api "mention").

The following diagram and table show all the feature types that are included (such as address records, building outlines, road surface area, road names, road sections and street records) and the relationships between them that we provide links for.

<figure><img src="https://4043944746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoEzqrBzRGoJw7nQyLj1W%2Fuploads%2Fgit-blob-343879c9e3fa10655d6a3c5a61f5f2e664b18e10%2FLIDSOverview.png?alt=media" alt="OS Linked Indentifiers API: diagram showing attribution linkages between different OS products."><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Features" %}
**Comprehensive data**

Take advantage of direct access to the [OS Open Linked Identifiers](https://docs.os.uk/os-downloads/products/buildings-and-infrastructure-portfolio/os-open-linked-identifiers) data.

**Dataset linking and enrichment**

Link different geographic datasets for richer insights.

**Integration with other OS APIs**

Work alongside and link other OS APIs for comprehensive analysis.
{% endtab %}

{% tab title="Benefits" %}
**Improves data interoperability**

Ensure consistency across datasets by linking to the appropriate identifier.

**Visualise third party data**

Accurately visualise related data that is published against OS identifiers.
{% endtab %}

{% tab title="Summary" %}

* **Format:** GeoJSON
* **Data Source**: [OS Open Linked Identifiers](https://docs.os.uk/os-downloads/products/buildings-and-infrastructure-portfolio/os-open-linked-identifiers)
* **Coverage:** Great Britain
* **Update:** Five working days from product [product refresh date](https://docs.os.uk/os-downloads/resources/product-resources/product-refresh-dates)
  {% endtab %}
  {% endtabs %}

## **Things to remember for OS Linked Identifiers API**

{% hint style="success" %}
You can:

* Create clickable interactive web app maps:
  * The relationships to our OS MasterMap Topography Layer TopographicArea TOID enable the creation of interactive clickable maps when used in conjunction with our OS Vector Tile API and/or OS Features API.
  * When selecting a building, an OS Linked Identifiers API query can provide details of the UPRN for the building address.
  * If a road surface feature is selected, the OS MasterMap Highways Road TOID can be retrieved to access the name of the road.
* Link properties to streets:
  * Our link between USRN and UPRN makes it easy to find the property address on a given street or identify the street that an address is on.
* Visualise third party street data:
  * Visualise road speed, traffic pollution and other road related data that is published against our OSMM Highways RoadLink identifiers for free with the Open Roads dataset. This is enabled via the OSMM Highways RoadLink TOID to Open Roads RoadLink/RoadNode GUID relationships.
    {% endhint %}

{% hint style="warning" %}
You can't:

* Access geometry or other attribution linked to the identifier. The OS Linked Identifier API only provides details of the related identifiers. Once you have the related identifiers, you can retrieve geometry and attribution via the OS Features API from either our OS Open Identifier or Premium products.
  {% endhint %}

## What's next?

<table data-view="cards"><thead><tr><th></th><th></th><th><select><option value="Btgab6EQCyWz" label="Labs.os.uk" color="blue"></option></select></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>What data is available?</strong></td><td>Detailed information about the data that can be accessed through the OS Linked Identifiers API.</td><td></td><td><a href="os-linked-identifiers-api/what-data-is-available">what-data-is-available</a></td></tr><tr><td><strong>Getting started with implementing a look-up application</strong></td><td>A guide to implementing an identifier look-up web application using the OS Linked Identifiers API</td><td></td><td><a href="os-linked-identifiers-api/getting-started-with-implementing-a-look-up-application">getting-started-with-implementing-a-look-up-application</a></td></tr><tr><td><strong>Technical specification</strong></td><td>This technical specification explains the content of the OS Linked Identifiers API and the methods you can use to call it.</td><td></td><td><a href="os-linked-identifiers-api/technical-specification">technical-specification</a></td></tr><tr><td><strong>Code examples</strong></td><td>Code examples you can use to display a map using the OS Linked Identifiers API.</td><td><span data-option="Btgab6EQCyWz">Labs.os.uk</span></td><td><a href="https://labs.os.uk/public/os-data-hub-examples/os-linked-identifiers-api/lids-example-correlation-method-2#maplibre-gl-js">https://labs.os.uk/public/os-data-hub-examples/os-linked-identifiers-api/lids-example-correlation-method-2#maplibre-gl-js</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.os.uk/os-apis/accessing-os-apis/os-linked-identifiers-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.