Stations Experience API
Network Rail's Stations Experience API provides endpoints to retrieve details of lift and escalator status over an HTTP endpoint. The API is documented here.
Access
To request access to the API, email APIIntegrationServicesC4E@networkrail.co.uk and request access to 's-nr-sfdc-liftsandescalator' and 'e-nr-stations'. You may be asked to justify your request for access, which will only be given if your response is satisfactory.[1]
You will receive an email some time later containing a client ID and secret. These are effectively your user identity and password for access to the API. There is no automated mechanism for signup at the time of writing.
Restrictions
There are some restrictions placed on what can be done with the data. Specifically, the data is licensed under the Open Government Licence v3.0, with a mandatory protocol (initial version) which sets out the requirements for using this data. Note that the protocol - and its list of stations - may change without warning, and that no changelog is provided.
The mandatory protocol (summary)
Consult the protocol (linked above) for the canonical version of the guidance. For further details, please contact Network Rail.
- Use identical symbols, wording, and section structure to the National Rail access map only
- Display a mandatory disclaimer on live lift data with specific wording
- Display only in-commission and public-facing lifts, don't display any escalators
- Do not display fields marked in the protocol as not for public display
- Display a mandatory disclaimer about no live data being available for TfL lifts for stations in Figure 1. Note that the list of stations in Figure 1 contains a number of significant errors, including stations with lifts managed by Network Rail, and stations far from London. Note that live data is available for TfL lifts. An annotated version of the Figure 1 list is is available on this wiki.
Base URL
All HTTP requests to this endpoint start with https://data.networkrail.co.uk/api/stations/v1.0/. Making a GET request to this URL without a valid client ID and secret will result in an HTTP 401 response with the following body:
{
"error": "Authentication denied."
}
Authorization
These headers must be passed with every HTTP request:
| Header | Description | Example |
|---|---|---|
| client_id | Client ID | 1a3rfe496jfkms49402srr93 |
| client_secret | Client secret | 7o9der492wklsmnxcvrt48f1 |
| x-correlation-id | Correlation ID (any text) | 1705956083 |
| Accept | Standard Accept header (RFC9110) | application/json or */* |
The correlation ID is just an identifier which is returned in the response, it doesn't need to be unique to the request. The Accept header is required, but some clients automatically set it, and the API will provide a descriptive error message if the header isn't provided.
Example (HTTP)
GET /api/stations/v1.0/stations/crs-codes/WAT/lifts-and-escalators HTTP/1.1 Host: data.networkrail.co.uk Accept: */* client_id: 1a3rfe496jfkms49402srr93 client_secret: 7o9der492wklsmnxcvrt48f1 x-correlation-id: 1705956083
Example (cURL)
curl 'https://data.networkrail.co.uk/api/stations/v1.0/stations/crs-codes/WAT/lifts-and-escalators' \
-H 'client_id: 1a3rfe496jfkms49402srr93' \
-H 'client_secret: 7o9der492wklsmnxcvrt48f1' \
-H 'x-correlation-id: 1705956083'
Responses
All responses are in JSON and have a 'header' and 'data' key.
The following key/value pairs are supplied underneath the 'header' key:
| Key | Value | Description |
|---|---|---|
| apiName | e-nr-stations | Name of the responding API |
| apiVersion | v1.0 | Current API version |
| correlationId | 1705956083 | The correlationId passed in the HTTP request |
The 'data' key contains the JSON response from the API.
Endpoint parameters
.../lifts-and-escalators
All endpoints ending in /lifts-and-escalators (i.e. endpoints which return multiple lifts/escalators) appear to support these get parameters, with the same behaviour. All parameters are optional.
| Name | Valid values | Remark |
|---|---|---|
| status | Available, Not Available, or Not Known |
Note that the case must be matched. When URL-encoded, the spaces are replaced by + (e.g. ?status=Not+Available)
|
| customerFacingOnly | true or false |
If not provided, both customer and non customer facing assets will be returned. if anything other than true - exactly as cased - is passed (including false), only non-customer-facing assets will be included.
|
| inCommissionOnly | true or false |
If true is passed, only in-commission assets will be returned. If anything other than true - exactly as cased - is passed, it'll be taken as false and both in-commission and non-commission assets will be returned.
|
| assetType | Lift or Escalator |
Returns all asset types if omitted. Note that the case must be matched, it's Lift not lift
|
Endpoints
The following endpoints exist:
/ping
This endpoint will identify whether the API is up.
/stations
All locations, with IDs, and CRS codes. Despite the name of the endpoint, many locations are not stations, and many do not have any lifts or escalators.
/stations/all/lifts-and-escalators
This endpoint will return details of the availability of all lifts and escalators included in the API.
Note that the API gateway does not support any HTTP compression methods. As of 2024-02-05, a full response is approximately 1.5MiB, customer-facing only (?customerFacingOnly=true) is approximately 1.2MiB, customer-facing only with only in-commission lifts (?customerFacingOnly=true&inCommissionOnly=true&assetType=Lift, full URL) is approximately 1.1M.
/stations/crs-codes/{crs-code}/lifts-and-escalators
This endpoint will return details of the availability of all lifts and escalators at the given station, identified by CRS code
/stations/{station-id}/lifts-and-escalators
Availability of known lifts and escalators at the given station, identified by ID, not CRS code.
/stations/{station-id}/lifts-and-escalators/{lift-or-escalator-id}
This endpoint will return details of a specific lift at a specific station. Note that you must use the location ID, not CRS code. The lift/escalator ID is the block ID of the lift or escalator.
/regions
This endpoint should return the names and IDs of Network Rail's five regions.
| Region name | Region ID |
|---|---|
| Wales & Western Region | 0Hh4K0000000XR8SAM |
| Scotland Region | 0Hh4K0000008zLDSAY |
| Eastern Region | 0Hh4K0000008zMcSAI |
| Southern Region | 0Hh4K0000008zNESAY |
| North West & Central Region | 0Hh4K0000000XQTSA2 |
/regions/{region-id}/lifts-and-escalators
All lifts and escalators within a region
/tocs
Names and IDs of operators
/tocs/{toc-id}/lifts-and-escalators
All lifts and escalators assigned to a particular operator
/routes
Routes and IDs
/routes/{route-id}/lifts-and-escalators
All lifts and escalators assigned to a particular route
Types
Note that the official documentation doesn't describe the purpose of any fields, and implies incorrect types for a number of them.
Keys in bold are those which the mandatory protocol permits you to show to passengers.
Lift/Escalator
| Key | Null? | Type | Example | Remark |
|---|---|---|---|---|
| blockId | N | String | "10866" |
Primary key |
| blockTitle | N | String | "Lancaster Stn Lift/Escalator 01" |
Internal-facing name for the asset |
| alternateName | Y | String | "Lift, Platform 4" |
Short descriptive name |
| type | N | String enum: "Lift", "Escalator" |
"Lift" |
Whether this is a lift or escalator |
| uprn | Y | String | "147969000" |
Non-unique asset identifier? |
| status | N | String enum: "Available", "Not Available", "Unknown" |
"Available" |
Status of the asset |
| operationalStatus | N | String enum: "Operational", "Ownership Transferred", "Demolished", "Out of use" |
"Operational" |
Operational status of lift. Note that the observed statuses might not reflect all possibilities. |
| updatedTime | Y | String (ISO datestamp) | "2024-02-06T12:59:42.000Z" |
Time sensor information was last updated? |
| customerFacingFlag | N | String (boolean) | "true" |
Whether the lift is customer-facing. Wrongly typed (as bool) in documentation. |
| inCommissionFlag | N | Boolean | true |
Whether the lift is in commission. Note that this field is actually boolean, rather than true/false in a string. |
| station | N | Station | Which location (not necessarily a station) this asset is in | |
| region | N | Region | Which region this asset is in | |
| route | N | Route | Which route this asset is in | |
| toc | N | TOC | The applicable Train Operating Company (TOC) | |
| long | Y | String (float) | "-2.8072" |
Longitude of the station/asset? |
| lat | Y | String (float) | "54.0488" |
Latitude of the station/asset? |
| engineerOnSite | N | String (boolean) | "true" |
Whether an engineer is on site. Wrongly typed (as bool) in documentation. |
| independent | N | String (boolean) | "false" |
Whether the asset is in independent service mode. Wrongly typed (as bool) in documentation. |
| isolated | N | String (boolean) | "false" |
Whether the asset is isolated? Wrongly typed (as bool) in documentation. |
| sensorId | Y | String | "8759" |
The ID of the relevant sensor |
| timeToFix | Y | String (ISO datestamp) | "2024-02-02T23:00:00.000" |
Date of planned fix? |
Region/Route
| Key | Null? | Type | Example | Remark |
|---|---|---|---|---|
| id | N | String | "0Hh4K0000000XQYSA2" |
Opaque ID |
| name | N | String | "North West Route" |
Name of region or route |
TOC
| Key | Null? | Type | Example | Remark |
|---|---|---|---|---|
| id | Y | String | "0014K00000bX7FeQAK" |
Opaque ID |
| name | Y | String | "First Great Western TOC" |
Name of train operating company |
Station
| Key | Null? | Type | Example | Remark |
|---|---|---|---|---|
| id | N | String | "02i4K00000FIHGkQAP" |
Opaque ID |
| crsCode | Y | String | "HIL" |
CRS code of location |
| name | N | String | "Hillside Stn" |
Location name |
| postCode | Y | String | "PR8 4QR" |
Postcode of location (omitted in documentation) |