Lift and Escalator API
Network Rail's Lift and Escalator API contains details of the status of lifts and escalators at many locations in Great Britain. The supplied documentation is sparse and difficult to follow, and so Peter Hicks of OpenTrainTimes has written this document for the community to help usage of the API.
Signing up
The developer preview does not require you to sign up, however it is probably worth your while to show how many people are using the API.
Access
The developer preview does not require use of an authentication token, even though the HTTP requests on the API page return a 401 Unauthorized.
Data elements
The following data elements are held within the API:
Field | Description |
---|---|
uprn | Unique asset identifier (not a UPRN) |
sensorId | A four-digit sensor identifier for the Electronic Monitoring Unit (EMU), left-padded with zeroes if required. |
blockId | An identifier for the location of the asset within a station |
blockTitle | The name of the location within the station |
station | Name of the station at which this asset is located |
location | Name of the location within the station at which this asset is located |
lat | Latitude in (WGS84) |
long | Longitude (WGS84) |
postcode | Postcode of the station in which this asset is located |
route | Network Rail Route in which this asset is located |
territory | Network Rail Region in which this asset is located |
toc | Set to 'Managed Stations' for Network Rail Managed Stations, otherwise the name of the train operator |
branch | Unknown, but possibly the branch of the lift or escalator maintainer's organisation where |
type | Type of asset, e.g. Lift or Escalator |
status | Current status of the asset |
isolated | Indicates whether the asset is powered down or disconnected |
engineerOnSite | Indicates if an engineer has logged in to the sensor and is servicing the asset |
independant | (note the misspelling) Indicates if the lift is on Independent Service by use of a car preference key |
updatedTime | Date and time when the status was last updated |
Making a request
All requests are through the API endpoint. Requests must be made via an HTTP POST call - accessing the endpoint through a web browser will make an HTTP GET request, resulting in the following error:
{"path":"$","error":"resource does not exist","code":"not-found"}
The API uses GraphQL, which allows complex queries to be submitted in an HTTP POST request. A query is just a JSON data structure with some fields to filter on, and other fields to return.
Simple requests
All assets at a station
To return the status of all lifts and escalators at a particular station, such as Edinburgh Waverley:
query MyQuery { status(where: {station: {_eq: "Edinburgh Waverley"}}) { blockTitle branch engineerOnSite independant isolated lat location long postCode route sensorId station status territory toc type updatedTime uprn blockId } }
All assets at all stations
To return data for all stations, remove the text in brackets after status, remove the statement within the brackets of the example above:
query MyQuery { status { blockTitle branch engineerOnSite independant isolated lat location long postCode route sensorId station status territory toc type updatedTime uprn blockId } }
Stream of updates
It is supposedly possible to make an API request and receive a stream of updates using the @live
directive on the GraphQL query, but does not seem to work on this API.
Room for improvement
There is some room for improvement on the API:
- Null entries - some fields are set to "#N/A", and some are set to null
- Unmapped sensors - there are instances (such as sensorId 3104) where no data has been filled in about the asset at all
- No escalators - some escalators are included but fall fully within the problem above, all have null locational data
- Incorrect references to territories - the term 'territory' was in use during Railtrack days, but is no longer used - Region and Routes are the current terminology
- Out-of-date TOC information - sensor 4052 refers to London Midland, sensor 3082 refers to East Coast, and 6148 to Arriva Trains Wales - none of whom currently operate franchises
- Lack of machine-interpretable data - sensor 5006 is described as 'Wolverhampton Stn Lift/Escalator 05', in location 'Passenger Lift Platform 4', whereas sensor 8127, 'Imperial Wharf Stn Lift/Escalator 01' is in location 'Platform 1' - these are not easy to parse and necessarily link to a particular platform
- Non-passenger assets - 1032 and 4034 are lifts situated in the South Wales and Thames Valley signalling centres, respectively. 1041 is "Mepham Street Goods No. 2" at London Waterloo, and 5054 will take you to "Red Star Parcels" in Milton Keynes