Difference between revisions of "Lift and Escalator API"

From Open Rail Data Wiki
Jump to navigation Jump to search
m (Remove errant "fields")
(Various edits, document REST API)
Line 1: Line 1:
−
Network Rail's '''[https://portal.nr-lift-and-escalator.net/ Lift and Escalator API]''' contains details of the status of lifts and escalators at many locations in Great Britain. The official documentation is quite sparse, hence this article was created by Peter in order to document the API unofficially.
+
Network Rail's '''[https://portal.nr-lift-and-escalator.net/ Lift and Escalator API]''' is an API developed for Network Rail in 2020 by rail technology consultancy Hack Partners Ltd (now a rail AI software company, trading as CrossTech), nominally offering the real-time status of lifts and escalators at many locations across the rail network in Great Britain. The official documentation is quite sparse, hence this article was created by Peter in order to document the API unofficially.
  
 
== Signing up ==
 
== Signing up ==
−
Authentication isn't necessary for V1 GraphQL functionality that has been migrated to V2, however it is probably worth your while to show how many people are using the API. Authentication is necessary for the V2 REST endpoints, and allows slightly deeper GraphQL queries.
+
You can register for an account on the Lift and Escalator API [https://portal.nr-lift-and-escalator.net portal]. Once you've verified your email address, navigate to the "products" tab. Click on "Developer" in the list on this page, then create a new subscription with a name of your choosing. Now, navigate to "Profile", you should be able to see your keys.
−
 
 
−
Register for an account on the Lift and Escalator API [https://portal.nr-lift-and-escalator.net portal]. Once you've verified your email address, you can navigate to the "products" tab. Click on "Developer" in the list on this page, then create a new subscription with a name of your choosing. Now, navigate to "Profile", you should be able to see your keys.
 
  
 
== Access ==
 
== Access ==
−
Despite the wording of the [[#Official documentation|supplied documentation]], it's not necessary to exchange your subscription key for an API key for REST requests, you can simply pass the subscription key in the ''x-lne-api-key'' HTTP header.
+
Official documentation claims that V1 GraphQL functionality migrated to V2 doesn't require authentication, but this isn't entirely true. Some location information (e.g. postcode, toc) was broken out into a ''stations'' table, which is inaccessible while unauthenticated. The inclusion of station CRS codes in the assets table may render this table redundant.
−
 
 
−
The GraphQL endpoint does not necessarily require authentication, as outlined in the above section.
 
  
 
== Data elements (V1) ==
 
== Data elements (V1) ==
Line 83: Line 79:
 
|-
 
|-
 
!Field
 
!Field
 +
!Official description
 
!Description
 
!Description
 
|-
 
|-
 
|id
 
|id
 +
|Unique asset identifier
 
|Unique identifier (of asset?)
 
|Unique identifier (of asset?)
 
|-
 
|-
 
|description
 
|description
 +
|''blank''
 
|e.g. "Colonnade Lift", "Lift 3,Platform 20"
 
|e.g. "Colonnade Lift", "Lift 3,Platform 20"
 
|-
 
|-
 
|displayName
 
|displayName
 +
|Standardised asset name
 
|e.g. "Lift to Colonnade ", "Lift, Platform 20"
 
|e.g. "Lift to Colonnade ", "Lift, Platform 20"
 
|-
 
|-
 
|sensorId
 
|sensorId
−
|A four-digit sensor identifier for the Electronic Monitoring Unit (EMU), left-padded with zeroes if required.
+
|Associated sensor
 +
|A sensor identifier for the Electronic Monitoring Unit (EMU), '''no longer zero-padded'''
 
|-
 
|-
 
|blockId
 
|blockId
 +
|''blank''
 
|An identifier for the location of the asset within a station
 
|An identifier for the location of the asset within a station
 
|-
 
|-
 
|crs
 
|crs
 +
|Associated station
 
|CRS code of the station at which this asset is located
 
|CRS code of the station at which this asset is located
 
|-
 
|-
 
|location
 
|location
 +
|''blank''
 
|Name of the location within the station at which this asset is located (e.g. "Colonnade Lift", "Platform 20")
 
|Name of the location within the station at which this asset is located (e.g. "Colonnade Lift", "Platform 20")
 
|-
 
|-
 
|type
 
|type
 +
|Asset type (i.e Lift or Escalator)
 
|Type of asset, e.g. Lift or Escalator
 
|Type of asset, e.g. Lift or Escalator
 
|-
 
|-
 
|status
 
|status
 +
|''relations not covered''
 
|(Relation) Current status of the asset
 
|(Relation) Current status of the asset
 
|}
 
|}
−
 
  
 
=== Status ===
 
=== Status ===
Line 118: Line 123:
 
|-
 
|-
 
!Field
 
!Field
 +
!Official description
 
!Description
 
!Description
 
|-
 
|-
 
|sensorId
 
|sensorId
 +
|Unique sensor identifier
 
|ID of sensor
 
|ID of sensor
 
|-
 
|-
 
|isolated
 
|isolated
 +
|''blank''
 
|Indicates whether the asset is powered down or disconnected
 
|Indicates whether the asset is powered down or disconnected
 
|-
 
|-
 
|engineerOnSite
 
|engineerOnSite
 +
|''blank''
 
|Indicates if an engineer has logged in to the sensor and is servicing the asset
 
|Indicates if an engineer has logged in to the sensor and is servicing the asset
 
|-
 
|-
 
|independent
 
|independent
 +
|''blank''
 
|('''note that this is now not misspelled'''), indicates if the lift is in independent service mode.
 
|('''note that this is now not misspelled'''), indicates if the lift is in independent service mode.
 +
|-
 +
|status
 +
|last status received
 +
|Current status of the asset (e.g. "Available", "Unknown", "Not Available")
 
|-
 
|-
 
|asset
 
|asset
 +
|''relations not covered''
 
|(Relation) Asset to which this status relates
 
|(Relation) Asset to which this status relates
 
|}
 
|}
 +
 +
=== Stations ===
 +
Note that stations are only available if you've authenticated using your bearer token. If you're not authenticated (this includes using the query builder provided), you'll see an error which makes it look like the table simply doesn't exist.
  
 
== Making a GraphQL request ==
 
== Making a GraphQL request ==
−
 
 
All requests are through the API endpoint (https://nr-lift-and-escalator.azure-api.net/graphql/v2). Requests must be made via an HTTP POST request, navigating to this URL in a web browser will make an HTTP GET request, which will result in the following error:
 
All requests are through the API endpoint (https://nr-lift-and-escalator.azure-api.net/graphql/v2). Requests must be made via an HTTP POST request, navigating to this URL in a web browser will make an HTTP GET request, which will result in the following error:
  
Line 143: Line 160:
  
 
The API uses [https://graphql.org/ 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.
 
The API uses [https://graphql.org/ 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.
 +
 +
== REST API ==
 +
With V2 came the introduction of a handful of REST endpoints, these are
 +
* <code>https://nr-lift-and-escalator.azure-api.net/api/v2/sensors[?num][&offset]</code> - All statuses, essentially equivalent to a graphQL query for statuses with no joins.
 +
 +
Num and offset aren't documented; they're used for paging, with num defining the limit, and offset defining the offset. Both are nominally optional, but num will default to 50 if unset. Instead of paging through these, there's no upper limit to ''num'', if you set it to 20000, you'll get all statuses at once.
 +
 +
* <code>https://nr-lift-and-escalator.azure-api.net/api/v2/sensors/{id}</code> - Statuses by sensor ID, same columns as graphQL status table
 +
* <code>https://nr-lift-and-escalator.azure-api.net/api/v2/stations/{crs}/assets</code> - Assets marked as being at given station CRS
 +
 +
Note that you need to provide bearer authentication for this, since it's passed through to GraphQL.
 +
 +
* <s><code>https://nr-lift-and-escalator.azure-api.net/api/v2/assets/{id}</code></s> - Get asset information by asset ID (broken)
 +
 +
<code>{"error":"field 'uprn' not found in type: 'assets'","path":"$.selectionSet.assets.selectionSet.uprn","code":"validation-failed"}</code>
  
 
== Simple requests ==
 
== Simple requests ==
Line 173: Line 205:
 
   }
 
   }
 
}</pre>
 
}</pre>
 +
 +
=== All assets at a station (V2) ===
 +
<pre>
 +
query {
 +
    assets(where: {crs: {_eq: "EDB"}}) {
 +
        blockId
 +
        crs
 +
        description
 +
        displayName
 +
        id
 +
        location
 +
        sensorId
 +
        status {
 +
            engineerOnSite
 +
            independent
 +
            isolated
 +
            sensorId
 +
            status
 +
        }
 +
        type
 +
    }
 +
}
 +
</pre>
  
 
=== All assets at all stations (V2) ===
 
=== All assets at all stations (V2) ===
Line 200: Line 255:
 
It is supposedly possible to make an API request and receive a stream of updates using the <code>@live</code> directive on the GraphQL query, but does not seem to work on this API.
 
It is supposedly possible to make an API request and receive a stream of updates using the <code>@live</code> directive on the GraphQL query, but does not seem to work on this API.
  
−
== Room for improvement ==
+
== Room for improvement (V1) ==
  
 
There is some room for improvement on the API:
 
There is some room for improvement on the API:

Revision as of 18:54, 8 September 2023

Network Rail's Lift and Escalator API is an API developed for Network Rail in 2020 by rail technology consultancy Hack Partners Ltd (now a rail AI software company, trading as CrossTech), nominally offering the real-time status of lifts and escalators at many locations across the rail network in Great Britain. The official documentation is quite sparse, hence this article was created by Peter in order to document the API unofficially.

Signing up

You can register for an account on the Lift and Escalator API portal. Once you've verified your email address, navigate to the "products" tab. Click on "Developer" in the list on this page, then create a new subscription with a name of your choosing. Now, navigate to "Profile", you should be able to see your keys.

Access

Official documentation claims that V1 GraphQL functionality migrated to V2 doesn't require authentication, but this isn't entirely true. Some location information (e.g. postcode, toc) was broken out into a stations table, which is inaccessible while unauthenticated. The inclusion of station CRS codes in the assets table may render this table redundant.

Data elements (V1)

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

Data elements (V2)

Asset

Field Official description Description
id Unique asset identifier Unique identifier (of asset?)
description blank e.g. "Colonnade Lift", "Lift 3,Platform 20"
displayName Standardised asset name e.g. "Lift to Colonnade ", "Lift, Platform 20"
sensorId Associated sensor A sensor identifier for the Electronic Monitoring Unit (EMU), no longer zero-padded
blockId blank An identifier for the location of the asset within a station
crs Associated station CRS code of the station at which this asset is located
location blank Name of the location within the station at which this asset is located (e.g. "Colonnade Lift", "Platform 20")
type Asset type (i.e Lift or Escalator) Type of asset, e.g. Lift or Escalator
status relations not covered (Relation) Current status of the asset

Status

Field Official description Description
sensorId Unique sensor identifier ID of sensor
isolated blank Indicates whether the asset is powered down or disconnected
engineerOnSite blank Indicates if an engineer has logged in to the sensor and is servicing the asset
independent blank (note that this is now not misspelled), indicates if the lift is in independent service mode.
status last status received Current status of the asset (e.g. "Available", "Unknown", "Not Available")
asset relations not covered (Relation) Asset to which this status relates

Stations

Note that stations are only available if you've authenticated using your bearer token. If you're not authenticated (this includes using the query builder provided), you'll see an error which makes it look like the table simply doesn't exist.

Making a GraphQL request

All requests are through the API endpoint (https://nr-lift-and-escalator.azure-api.net/graphql/v2). Requests must be made via an HTTP POST request, navigating to this URL in a web browser will make an HTTP GET request, which will result 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.

REST API

With V2 came the introduction of a handful of REST endpoints, these are

Num and offset aren't documented; they're used for paging, with num defining the limit, and offset defining the offset. Both are nominally optional, but num will default to 50 if unset. Instead of paging through these, there's no upper limit to num, if you set it to 20000, you'll get all statuses at once.

Note that you need to provide bearer authentication for this, since it's passed through to GraphQL.

{"error":"field 'uprn' not found in type: 'assets'","path":"$.selectionSet.assets.selectionSet.uprn","code":"validation-failed"}

Simple requests

All assets at a station (V1)

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 a station (V2)

query {
    assets(where: {crs: {_eq: "EDB"}}) {
        blockId
        crs
        description
        displayName
        id
        location
        sensorId
        status {
            engineerOnSite
            independent
            isolated
            sensorId
            status
        }
        type
    }
}

All assets at all stations (V2)

query {
	assets {
		blockId
		crs
		description
		displayName
		id
		location
		sensorId
		status {
			engineerOnSite
			independent
			isolated
			sensorId
			status
		}
		type
	}
}

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 (V1)

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

Official documentation

Links to official documentation:

Version 2

Version 1

Retrieved from ‘https://wiki.openraildata.com//index.php?title=Lift_and_Escalator_API&oldid=3223’