OS Linked Identifier API relationships

OS MasterMap product feature relationships

The OS Open Linked Identifiers product provides the valuable relationships between the following features found in OS MasterMap (OSMM) products:

  • TopographicArea (TOID): is a polygon taken from the OS MasterMap Topographic Layer and depicts land, roads and buildings among other things. The OS Linked Identifiers API has only selected the TopographicArea features related to either an address (typically a building) or a road.
     
  • RoadLink (TOID): is taken from the OS MasterMap Highways product and details a road section from junction to junction. 

  • Road (TOID): is taken from the OS MasterMap Highways product and groups a collection of RoadLink to form the full extent of a name road feature (e.g. “The High Street”).

  • ORRoadLink/ORRoadNode (GUID): is taken from OS Open Roads and depicst the junctions and road sections between them. They are a simplified geometry to that in the OS MasterMap Highways product with some dual carriageways reduced to a single ORRoadLink and some roundabouts/cul-de-sacs reduced to a single ORRoadNode.

  • Street (USRN): is taken from the OS MasterMap Highways product and like a Road groups together a collection of RoadLinks forming the full extent of a named road within an administrative area. This feature is used to track maintenance for the road feature and is given a Unique Street Reference Number (USRN). 
  • BLPU (USRN): the Building Land Property Unit (BLPU) is taken from AddressBase Premium and gives a Unique Property Reference Number (UPRN) to each address.  

Technical specification on OS Data Hub

Open-linked IDs relationships

Image showing feature relationships.

  • Open Roads RoadLink/RoadNode GUID
  • OSMM Highways RoadLink TOID
  • OSMM Highways Road TOID
  • OSMM Topo Layer TopographicsArea TOID
  • AddressBase BLPU UPRN
  • OSMM Highways Street USRN

Useful user interactions and feature labelling

Linking between these features enables a wide range of useful user interactions and feature labelling as follows:

Clickable building and road features

All the valuable identifiers are linked back to our TopographicArea TOID, from our most detailed large-scale data in OS MasterMap Topographic Layer. These features are available via both our OS Feature API and OS Vector Tiles API. The OS Vector Tiles API can be used to create a contextual web map application. Because it supplies the map in a vector form (unlike the OS Maps API, which supplies images) the browser based application is able to identify the feature the user's mouse is over when they click on the map. If the map is zoomed to the largest scale then the features displayed are TopographicAreas. The OS Vector Tiles API supplies the TOID along with each of these features. The browser-based application is then able to supply this TopographicArea TOID to the OS Linked Identifiers API to quickly discover if the feature is either a building with an address or road. If it is then the related identifiers are returned as follows:

  • For a building with an address: BLPU UPRN, this can be passed to the OS Places API to retrieve the full address of the property.

  • For a road: Road TOID, RoadLink TOID, Street USRN, these can be passed to the OS Features API to retrieve further details about these features such as the roads name(s) and whether it is maintained at public expense or not.

 

Third party data annotation

Across all central and local government there's a big push to make data open and available as possible to enable better decision making for all. This is enabled using identifiers such as the UPRN, USRN and TOID. Data related to an address, such as council tax banding, can be published with a UPRN. Data related to a road, such as accident counts, pollution levels, traffic flows; can be published with either a Road TOID, RoadLink TOID or Street USRN.

  • With premium data: The OS Linked Identifiers API enables this data to be linked in real time (as it is viewed in the user web browser map application) back to the features being rendered via the OS Vector Tiles API. This enables the web map application to colour code the building and road features with which ever related data is needed.
  • With open data: OS has made it new OS Open UPRN, OS Open USRN, OS Open TOID data products available via its OS Features API. This enables a browser based web map application to find in real time the related location/geometry for these identifiers, and link it to the third party related data to overlay the information on a backdrop map - provided via either the OS Maps API or OS Vector Tiles API. For data related to RoadLink TOIDs, the OS Linked Identifiers API can be used to link this data through to OS Open Road RoadLink/RoadNode GUIDs. The OS Features API can then be used to access the OS Open Road geometry so that the related third-party data can be overlaid using it.

Relationship specifics

The following section provides use case details specific for each relationship accessible via the OS Linked Identifiers API.

TopographicArea TOID

Map clicks: A query to the OS Linked Identifiers API with a TopographicArea TOID enables a web map application to look up related identifiers when a user clicks on a map.

Map annotations: if you have data related to either a UPRN for a building with an address, or Road/RoadLink TOID, Street USRN; then these identifiers can be used in a query to the OS Linked Identifiers API to retrieve the related TopographicArea TOID. The geometry can then be retrieved via OS Features API and used to annotate a backdrop map from OS Maps API or OS Vector Tiles API - with the related data colour coding the feature appropriately.

RoadLink ↔ TopographicArea: RoadLink_TOID_TopographicArea_TOID_2

TopographicArea -> RoadLink: Supports clicking on a section of road and discovering related information such as whether it is maintained at public expense.

RoadLink -> TopographicArea: Supports highlighting a section of road and colour coding it with third party related data - such as traffic flows, pollution levels and accident counts.

Road ↔ TopographicArea: Road_TOID_TopographicArea_TOID_3

TopographicArea -> Road: Supports clicking on a section of road and discovering its name.

Road -> TopographicArea: Supports highlighting the full extent of the named road feature and annotating it with related data.

Street ↔ TopographicArea: Street_USRN_TopographicArea_TOID_4 

TopographicArea -> Street: Supports clicking on a section of road and discovering its USRN.

Street -> TopographicArea: Supports highlighting the full extent of a street feature and annotating it with data related to the USRN.

BLPU ↔ TopographicArea: BLPU_UPRN_TopographicArea_TOID_5

TopographicArea -> BLPU: Supports clicking on a building with an address and discovering its UPRN.

BLPU -> TopographicArea: Supports annotating buildings with an address with third party data related to its UPRN.

Road TOID, RoadLink TOID and Street USRN

The relationships between the Road, RoadLink and Street features are typically used for discovering the name or USRN for a road section; or to validate the road name related to a USRN. Once you've retrieved the related identifier via the OS Linked Identifiers API you can then access it via premium or open data via the OS Features API.

RoadLink ↔ Road: RoadLink_TOID_Road_TOID_7 

RoadLink -> Road: Supports discovering the name of a section of road.

Road -> RoadLink: Supports accessing (via OS Features API) the full extent of the named road feature.

RoadLink ↔ Street: RoadLink_TOID_Street_USRN_8 

RoadLink -> Street: Supports discovering the USRN for a section of road.

Street -> RoadLink: Supports accessing (via OS Features API) the full road extent for a USRN.

Road ↔ Street: Road_TOID_Street_USRN_10 

Road -> Street: Supports discovering the USRN for a named road.

Street -> Road: Supports accessing (via OS Features API) the road name for a given USRN.

Addressing BLPU UPRN with road features

Being able to relate a UPRN to the road related features is useful for validating your data. Additionally, being able to go from a road feature to a UPRN enables discovering all of the addresses on that road. This can be useful if you need to notify people of possible disruption due to road works.

BLPU ↔ RoadLink: BLPU_UPRN_RoadLink_TOID_9 

BLPU -> RoadLink: Supports discovering the section of road that accesses the property.

RoadLink -> BLPU: Supports listing all the address UPRNs on a specific section of road.

BLPU ↔ Street: BLPU_UPRN_Street_USRN_11 

BLPU -> Street:  Supports discovering the USRN for the road that accesses the property.

Street -> BLPU: Supports listing all the address UPRNs on a road defined by the Street USRN.

OS MasterMap Highways Networks with OS Open Roads

Being able to relate the RoadLink TOID in OS MasterMap Highways Networks with OS Open Roads RoadLink/RoadNode GUID features enables third party data that is published with a RoadLink TOID to be visualised for free using the OS Open Roads geometry. This can be done in real time (as it is viewed in the user web browser map application) by accessing the OS Open Road geometry via the OS Features API and overlaying it on a backdrop map from OS Maps API. The related RoadLink TOID can then be retrieved from the OS Linked Identifier API and used to annotate the OS Open Road features with data related to the RoadLink TOID.

Open Roads RoadLink ↔ OSMM Highways RoadLink: ORRoadLink_GUID_RoadLink_TOID_12 

Open Roads RoadNode ↔ OSMM Highways RoadLink:ORRoadNode_GUID_RoadLink_TOID_13 

RoadLink/RoadNode GUID -> RoadLink TOID: Supports discovering of the RoadLink TOID so that data related to it can be annotated onto the OS Open Roads features being rendered.

RoadLink TOID -> RoadLink/RoadNode GUID: Supports the highlighting of OS Open Roads features related to a given OS MasterMap Highways Networks RoadLink TOID. It also enables the OS Open Roads features being annotated with data related to its RoadLink TOIDs.

Next steps

  • OS Linked Identifiers API

    Access the relationships between properties, streets and OS MasterMap identifiers for free.

  • OS Linked Identifiers API - Overview

    The overview introduces the product and gives context for all users. It highlights key features, provides examples of potential uses for the product and lists details like file sizes and supply formats.

  • Developer support

    Our developer support resources are available to all users, providing guidance in managing your OS data account and your mapping projects.