Stations Experience API

From Open Rail Data Wiki
Revision as of 07:27, 29 February 2024 by EvelynSnow (talk | contribs) (Add note about justifying access)

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.

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

References