OS Linked Identifiers API

What is 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 Unique Property Reference Number (UPRN) for a building on a map, or the Unique Street Reference Number (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) to the street that it is on (USRN).

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 and returns data in a readable JSON format. These standards integrate well with JavaScript and support the creation of sophisticated interactive map web applications in conjunction with our OS Maps API, OS Vector Tile API and OS Features API.

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.

Get this data

To access the OS Linked Identifiers, you need an API Key. This key will be specific to a dedicated API project linked to your OS Data Hub account.

Click Get started to find out how to get your API Key and access OS Linked Identifiers API data, or Go to the OS Data Hub where you can access the API Projects page to manage all of your OS APIs.

Get startedGo to the OS Data Hub

Features

Comprehensive data

Take advantage of direct access to the 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.

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.

Summary

• Format: GeoJSON

• Data Source: OS Open Linked Identifiers

• Coverage: Great Britain

• Update: Five working days from product product refresh date

Things to remember for OS Linked Identifiers API

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 OS MasterMap Highways RoadLink identifiers for free with the OS Open Roads dataset. This is enabled via the OS MasterMap Highways RoadLink TOID to OS Open Roads RoadLink / RoadNode GUID relationships.

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.

What's next?

What data is available?

Detailed information about the data that can be accessed through the OS Linked Identifiers API.

Getting started with implementing a look-up application

A guide to implementing an identifier look-up web application using the OS Linked Identifiers API

Technical specification

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

Code examples

Code examples you can use to display a map using the OS Linked Identifiers API.

Labs.os.uk

How to access the OS Linked Identifiers API

Visit the Getting started with an API project page for details on how to access and use the OS Linked Identifiers API in your projects.