OS Linked Identifiers API
Resolves the relationships between properties, streets, and OS MasterMap identifiers - UPRN to TOID to USRN - which is the join key between OS data, HM Land Registry records, and local authority property data.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "OS Linked Identifiers API",
"version": "1.0.0",
"x-apievangelist-provenance": {
"method": "searched",
"generated": "2026-07-26",
"assembly": "Assembled by the API Evangelist enrichment pipeline from the per-operation OpenAPI 3.0.1 documents Ordnance Survey publishes inline on each docs.os.uk technical-specification page. Paths, parameters, schemas, security schemes and responses are verbatim from those published documents; only the per-page fragments were merged into one document per API.",
"sources": [
"https://docs.os.uk/os-apis/accessing-os-apis/os-linked-identifiers-api/technical-specification/feature-types.md",
"https://docs.os.uk/os-apis/accessing-os-apis/os-linked-identifiers-api/technical-specification/identifier-types.md",
"https://docs.os.uk/os-apis/accessing-os-apis/os-linked-identifiers-api/technical-specification/identifier.md",
"https://docs.os.uk/os-apis/accessing-os-apis/os-linked-identifiers-api/technical-specification/product-version-information.md"
],
"server_url_published": [
"${lids.api.server}/search/links/v1"
],
"server_url_note": "The published fragments carry an unresolved deployment template variable; substituted with the production host documented at https://api.os.uk/search/links/v1 and in the api.os.uk link index."
}
},
"servers": [
{
"url": "https://api.os.uk/search/links/v1"
}
],
"security": [
{
"ApiKeyAuth": []
},
{
"OAuth2": [
"read"
]
}
],
"tags": [
{
"name": "OS OpenData Users",
"description": "Operations available to customers using the OpenData plan"
}
],
"paths": {
"/featureTypes/{featureType}/{id}": {
"get": {
"tags": [
"OS OpenData Users"
],
"summary": "Query ID when input featureType is known",
"description": "Returns associated Linked Identifiers, when feature type is known. Returns an object.",
"parameters": [
{
"$ref": "#/components/parameters/featureIdentifier"
},
{
"name": "featureType",
"in": "path",
"description": "Feature type of ID being queried",
"explode": true,
"required": true,
"schema": {
"type": "string",
"enum": [
"BLPU",
"ORRoadNode",
"ORRoadLink",
"Road",
"RoadLink",
"Street",
"TopographicArea"
]
}
}
],
"responses": {
"200": {
"description": "Search results matching criteria",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/linkedIdentifier"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"405": {
"$ref": "#/components/responses/MethodNotAllowed"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/identifierTypes/{identifierType}/{id}": {
"get": {
"tags": [
"OS OpenData Users"
],
"summary": "Queries ID when input identifierType is known",
"description": "Returns associated Linked Identifiers, when the input identifier type is known. Returns an object.\n",
"parameters": [
{
"$ref": "#/components/parameters/featureIdentifier"
},
{
"name": "identifierType",
"in": "path",
"description": "Identifier type of ID being queried",
"explode": true,
"required": true,
"schema": {
"type": "string",
"enum": [
"GUID",
"TOID",
"UPRN",
"USRN"
]
}
}
],
"responses": {
"200": {
"description": "Search results matching criteria",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/linkedIdentifier"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"405": {
"$ref": "#/components/responses/MethodNotAllowed"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/identifiers/{id}": {
"get": {
"tags": [
"OS OpenData Users"
],
"summary": "Query identifer",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/featureIdentifier"
}
],
"responses": {
"200": {
"description": "Search results matching criteria",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/linkedIdentifierSet"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"405": {
"$ref": "#/components/responses/MethodNotAllowed"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
},
"/productVersionInfo/{correlationMethod}": {
"get": {
"tags": [
"OS OpenData Users"
],
"summary": "Returns product version details of the source data products",
"description": "Returns current valid version information for identifier relationships",
"parameters": [
{
"name": "correlationMethod",
"in": "path",
"description": "Correlation method being queried",
"explode": true,
"required": true,
"schema": {
"type": "string",
"enum": [
"RoadLink_TOID_TopographicArea_TOID_2",
"Road_TOID_TopographicArea_TOID_3",
"Street_USRN_TopographicArea_TOID_4",
"BLPU_UPRN_TopographicArea_TOID_5",
"RoadLink_TOID_Road_TOID_7",
"RoadLink_TOID_Street_USRN_8",
"BLPU_UPRN_RoadLink_TOID_9",
"Road_TOID_Street_USRN_10",
"BLPU_UPRN_Street_USRN_11",
"ORRoadLink_GUID_RoadLink_TOID_12",
"ORRoadNode_GUID_RoadLink_TOID_13"
]
}
}
],
"responses": {
"200": {
"description": "Returns product version information about the requested correlation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/correlationMethodInformation"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"405": {
"$ref": "#/components/responses/MethodNotAllowed"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "query",
"name": "key"
},
"OAuth2": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.os.uk/oauth2/token/v1",
"scopes": {
"read": "Grants read access"
}
}
}
}
},
"parameters": {
"featureIdentifier": {
"name": "id",
"in": "path",
"description": "ID of the feature that is being matched",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 36
}
}
},
"schemas": {
"linkedIdentifier": {
"type": "object",
"required": [
"linkedIdentifier",
"correlations"
],
"additionalProperties": false,
"properties": {
"linkedIdentifier": {
"title": "linkedIdentifier",
"type": "object",
"required": [
"identifier",
"featureType",
"identifierType"
],
"additionalProperties": false,
"properties": {
"identifier": {
"type": "string"
},
"featureType": {
"$ref": "#/components/schemas/featureType"
},
"identifierType": {
"$ref": "#/components/schemas/identifierType"
}
}
},
"correlations": {
"type": "array",
"title": "correlations",
"items": {
"type": "object",
"required": [
"correlationMethodIdentifier",
"correlatedFeatureType",
"correlatedIdentifierType",
"correlatedIdentifiers"
],
"additionalProperties": false,
"properties": {
"searchedIdentifierVersionDate": {
"type": "string"
},
"searchedIdentifierVersionNumber": {
"type": "number"
},
"correlationMethodIdentifier": {
"$ref": "#/components/schemas/correlationMethodIdentifier"
},
"correlatedFeatureType": {
"$ref": "#/components/schemas/featureType"
},
"correlatedIdentifierType": {
"$ref": "#/components/schemas/identifierType"
},
"correlatedIdentifiers": {
"type": "array",
"required": [
"identifier",
"confidence",
"correlationIdentifier"
],
"additionalProperties": false,
"items": {
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"versionNumber": {
"type": "number"
},
"versionDate": {
"type": "string"
},
"confidence": {
"type": "string"
},
"correlationIdentifier": {
"type": "string"
}
}
}
}
}
}
}
}
},
"featureType": {
"type": "string",
"enum": [
"BLPU",
"ORRoadNode",
"ORRoadLink",
"Road",
"RoadLink",
"Street",
"TopographicArea"
]
},
"identifierType": {
"type": "string",
"enum": [
"GUID",
"TOID",
"UPRN",
"USRN"
]
},
"correlationMethodIdentifier": {
"type": "string",
"enum": [
"RoadLink_TOID_TopographicArea_TOID_2",
"Road_TOID_TopographicArea_TOID_3",
"Street_USRN_TopographicArea_TOID_4",
"BLPU_UPRN_TopographicArea_TOID_5",
"RoadLink_TOID_Road_TOID_7",
"RoadLink_TOID_Street_USRN_8",
"BLPU_UPRN_RoadLink_TOID_9",
"Road_TOID_Street_USRN_10",
"BLPU_UPRN_Street_USRN_11",
"ORRoadLink_GUID_RoadLink_TOID_12",
"ORRoadNode_GUID_RoadLink_TOID_13"
]
},
"linkedIdentifierSet": {
"type": "object",
"required": [
"linkedIdentifiers"
],
"additionalProperties": false,
"properties": {
"linkedIdentifiers": {
"type": "array",
"title": "linkedIdentifiers",
"items": {
"$ref": "#/components/schemas/linkedIdentifier"
}
}
}
},
"correlationMethodInformation": {
"type": "object",
"required": [
"methodIdentfier",
"productCreationDate",
"identifier1Source",
"identifier2Source"
],
"additionalProperties": false,
"properties": {
"methodIdentifier": {
"$ref": "#/components/schemas/correlationMethodIdentifier"
},
"productCreationDate": {
"type": "string"
},
"productPublicationName": {
"type": "string"
},
"identifier1Source": {
"$ref": "#/components/schemas/identifierSource"
},
"identifier2Source": {
"$ref": "#/components/schemas/identifierSource"
}
}
},
"identifierSource": {
"type": "object",
"required": [
"productName",
"productPublicationDate",
"featureType",
"identifierType"
],
"additionalProperties": false,
"properties": {
"productName": {
"type": "string",
"enum": [
"AddressBase Premium",
"OS MasterMap Highways Network - Roads",
"OS MasterMap Topography Layer",
"OS Open Roads"
]
},
"productPublicationDate": {
"type": "string"
},
"productPublicationName": {
"type": "string"
},
"featureType": {
"$ref": "#/components/schemas/featureType"
},
"identifierType": {
"$ref": "#/components/schemas/identifierType"
}
}
}
},
"responses": {
"BadRequest": {
"description": "E.g. missing query parameter, malformed syntax."
},
"Unauthorized": {
"description": "The client has not provided authentication or incorrect authentication."
},
"Forbidden": {
"description": "The client has authenticated its access but does not have sufficient rights to complete the request."
},
"NotFound": {
"description": "The server has not found anything matching the Request-URI."
},
"MethodNotAllowed": {
"description": "Request used an unsupported HTTP method, e.g. DELETE or PUT."
},
"TooManyRequests": {
"description": "Exceeded the number of requests per minute (rate-limit)."
},
"InternalServerError": {
"description": "Generic internal server error."
},
"ServiceUnavailable": {
"description": "Temporary outage due to overloading or maintenance."
}
}
}
}