Latest revision as of 09:12, 30 July 2024

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"`	Unique Property Reference Number (UPRN)
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

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)

References

↑ https://groups.google.com/g/openraildata-talk/c/QpMtQjeechk/m/nE5ia9o3BAAJ

[1] ttps://groups.google.com/g/openraildata-talk/c/QpMtQjeechk/m/nE5ia9o3BAAJ

[1]