Stations Experience API

Network Rail's Stations Experience API provides endpoints to retrieve details of lift and escalator status over an HTTP endpoint.

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.

Documentation

There is no publicly-available official documentation, except for the information contained in the communication and mandatory protocol, neither of which documents endpoints, authentication headers, semantics, or types. No schema is known to be available. The communication suggests that Anypoint credentials — which would allow users to access official documentation — will be shared on request; access is restricted to Network Rail by internal policy. Network Rail says it will offer no further documentation until the API is published through the Rail Data Marketplace at an unknown point in the future.

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.

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	256c727ed31cd44d6fbe0cd67bafae4e
client_secret	Client secret	7hT1SPeN1VHMBfGxYjQ9DsEO29DTX3ae
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: 256c727ed31cd44d6fbe0cd67bafae4e
client_secret: 7hT1SPeN1VHMBfGxYjQ9DsEO29DTX3ae
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: 256c727ed31cd44d6fbe0cd67bafae4e' \
    -H 'client_secret: 7hT1SPeN1VHMBfGxYjQ9DsEO29DTX3ae' \
    -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/lifts-and-escalators

This endpoint will return details of the availability of all lifts and escalators included in the API. The size of the response is approximately 1.5MiB, as of 2024-01-27. Note that the API gateway does not support any HTTP compression methods.

/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.