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 web app maps for selection of road or building features that display 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.

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 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.

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.