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 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 on how the information should be displayed.

The mandatory protocol (summary)

Consult the protocol (linked above) for the canonical version of the guidance. For further details, please contact Network Rail.

1. Use identical symbols, wording, and section structure to the National Rail access map only
2. Display a mandatory disclaimer on live lift data with specific wording
3. Display only in-commission and public-facing lifts, don't display any escalators
4. Do not display fields marked in the protocol as not for public display
5. 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.

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.

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.

The following optional get parameters can be used

Name	Valid values	Remark
status	Available, Not Available, or Not Known	(not yet tested what this actually does)
customerFacingOnly	true or false	Note that this must be entirely lowercase. If not provided, all customer facing states will be provided. 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 (and only true, in that exact capitalisation) 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.
assetType	Lift or Escalator	Returns all asset types if omitted. Note that the case must be matched, it's Lift not lift

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