API usage and schema

The API uses the GraphQL query language. As an emerging standard this allows a consumer to not only selectively query the lift and escalator status’ but also subscribe to changes in data. An introduction to which can be found here:

https://graphql.org/

Example GraphQL query

Endpoint

https://nr-lift-and-escalator.azure-api.net/gateway/v1/

Note: If making a http request directly a query can be made by sending a POST request to this endpoint.

The following example we will be using a simple filtering technique, you can find more complex filtering examples here:

https://hasura.io/docs/1.0/graphql/manual/queries/query-filters.html

Query

query MyQuery {
status(where: {station: {_eq: "London Waterloo"}}) {
blockTitle
branch
engineerOnSite
independant
isolated
lat
location
long
postCode
route
sensorId
station
status
territory
toc
type
updatedTime
uprn
blockId
}
}

Response

{
"station": null,
"sensorId": "6156",
"location": null,
"postCode": null,
"status": "Available",
"updatedTime": "2020-03-27T13:22:48.1384847+00:00",
"type": "Lift",
"isolated": true,
"engineerOnSite": false,
"independant": false,
"lat": null,
"long": null,
"branch": null
}

Status codes

The status field can have the following three string values:

Unknown – We do not know whether the lift/escalator is running as the Site is Out of Commission/EMU has communication issues

Available - Lift/Escalator is OK to be used

Not Available – Lift/Escalator cannot be used i.e. broken down

If the Lift is “Not Available” the following fields may be true, indicating different states:

Isolated – Lift is switched off but can be put back into service if required

Engineer On Site – Engineer working on the Lift/Escalator

Independent – Lift is on independent service i.e. key switch

CRS codes

CRS codes are a unique three letter code for each station. It is a popular key used for stations in systems using UK rail data. We can also get the assets status’ at a particular station using a more complex query that filters on this code:

Query

query MultiTableQuery {
portfolio(where: {status: {status: {_is_null: false}}, crs: {_eq: "PAD"}}) {
status {
status
engineerOnSite
independant
isolated
}
type
location
}
}

Response

{
"data": {
"portfolio": [
{
"status": {
"status": "Unknown",
"engineerOnSite": false,
"independant": false,
"isolated": false
},
"type": "Lift",
"location": "Platform 10"
},
{
"status": {
"status": "Available",
"engineerOnSite": false,
"independant": false,
"isolated": false
},
"type": "Lift",
"location": "Platform 1 ISA Lift"
},
{
"status": {
"status": "Unknown",
"engineerOnSite": false,
"independant": false,
"isolated": false
},
"type": "Lift",
"location": "Platform 12 Lift 1"
},
{
"status": {
"status": "Unknown",
"engineerOnSite": false,
"independant": false,
"isolated": false
},
"type": "Lift",
"location": "Platform 12 Lift 2"
},
{
"status": {
"status": "Available",
"engineerOnSite": false,
"independant": false,
"isolated": false
},
"type": "Lift",
"location": "Northern Entrance Lift 5"
}
]
}
}

Rate Limits

Currently the api is running a maximum of 15 requests per minute per ip connection, we expect to increase this in future as we make our starter and unlimited packages available. The expected behaviour when this limit is reached is documented below.

Expected Exceeded Limit Response (Http 200)

{
"errors": [
{
"extensions": {
"path": "$",
"code": "rate-limit-exceeded"
},
"message": "rate limit of 15 exceeded"
}
]
}

Schema

Status

{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "http://example.com/example.json",
"type": "object",
"title": "The Status Table Schema",
"description": "The root schema comprises the entire JSON document.",
"required": [
"uprn",
"sensorId",
"blockId",
"blockTitle",
"station",
"location",
"lat",
"long",
"postCode",
"route",
"territory",
"toc",
"branch",
"type",
"status",
"isolated",
"engineerOnSite",
"independant",
"updatedTime"
],
"properties": {
"uprn": {
"$id": "#/properties/uprn",
"type": "string",
"title": "The Uid Schema",
"description": "The unique identifier for the asset in the system as a whole.",
"default": null,
"examples": [
"263729000028"
]
},
"sensorId": {
"$id": "#/properties/sensorId",
"type": "string",
"title": "The Sensorid Schema",
"description": "The unique 4 digit EMU Code which is prefixed with zeros.",
"default": null,
"examples": [
"5176"
]
},
"blockId": {
"$id": "#/properties/blockId",
"type": "string",
"title": "The Blockid Schema",
"description": "The unique identifier for the location of the asset within a station.",
"default": null,
"examples": [
"22181"
]
},
"blockTitle": {
"$id": "#/properties/blockTitle",
"type": "string",
"title": "The Blocktitle Schema",
"description": "The name of the block within the station.",
"default": null,
"examples": [
"London Waterloo Stn Lift/Escalator 06"
]
},
"station": {
"$id": "#/properties/station",
"type": "string",
"title": "The Station Schema",
"description": "The station name.",
"default": null,
"examples": [
"London Waterloo"
]
},
"location": {
"$id": "#/properties/location",
"type": "string",
"title": "The Location Schema",
"description": "The location within the station of the asset.",
"default": null,
"examples": [
"Mepham Street Goods No. 2"
]
},
"lat": {
"$id": "#/properties/lat",
"type": "string",
"title": "The Lat Schema",
"description": "The Latitude (WGS84 standard).",
"default": null,
"examples": [
"51.502706"
]
},
"long": {
"$id": "#/properties/long",
"type": "string",
"title": "The Long Schema",
"description": "The Longitude (WGS84 standard).",
"default": null,
"examples": [
"-0.113277"
]
},
"postCode": {
"$id": "#/properties/postCode",
"type": "string",
"title": "The Postcode Schema",
"description": "The postcode of the station that the asset is in",
"default": null,
"examples": [
"SE1 8SW"
]
},
"route": {
"$id": "#/properties/route",
"type": "string",
"title": "The Route Schema",
"description": "The route that the asset is on.",
"default": null,
"examples": [
"Wessex"
]
},
"territory": {
"$id": "#/properties/territory",
"type": "string",
"title": "The Territory Schema",
"description": "The territory the asset is in.",
"default": null,
"examples": [
"Southern"
]
},
"toc": {
"$id": "#/properties/toc",
"type": "string",
"title": "The Toc Schema",
"description": "The toc type",
"default": null,
"examples": [
"Managed Stations"
]
},
"branch": {
"$id": "#/properties/branch",
"type": "string",
"title": "The Branch Schema",
"description": "The branch of the asset",
"default": null,
"examples": [
"Dartford"
]
},
"type": {
"$id": "#/properties/type",
"type": "string",
"enum": [
"Lift",
"Escalator"
],
"title": "The Type Schema",
"description": "The type of asset.",
"default": null,
"examples": [
"Lift"
]
},
"status": {
"$id": "#/properties/status",
"type": "string",
"enum": [
"Unknown",
"Available",
"Not Available"
],
"title": "The Status Schema",
"description": "The status of the asset.",
"default": "Unknown",
"examples": [
"Not Available"
]
},
"isolated": {
"$id": "#/properties/isolated",
"type": "boolean",
"title": "The Isolated Schema",
"description": "Indicates whether the asset is isolated.",
"default": false,
"examples": [
false
]
},
"engineerOnSite": {
"$id": "#/properties/engineerOnSite",
"type": "boolean",
"title": "The Engineeronsite Schema",
"description": "Indicates whether an engineer is logged into the sensor.",
"default": false,
"examples": [
false
]
},
"independant": {
"$id": "#/properties/independant",
"type": "boolean",
"title": "The Independent Schema",
"description": "Indicates whether the asset is currently operating in independent mode.",
"default": false,
"examples": [
false
]
},
"updatedTime": {
"$id": "#/properties/updatedTime",
"type": "string",
"title": "The Updatedtime Schema",
"description": "The data & time (ISO 8601 format) that the status was updated.",
"default": null,
"examples": [
"2020-07-23T07:23:21.2470197+00:00"
]
}
}
}

Portfolio

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",

"title": "The Portfolio Table Schema",
"properties": {
"status": {
"type": "object",

"description": "Nested object containing status table attributes for asset"
},
"address": {
"type": "string",

"description": "Address of station containing asset"
},
"branch": {
"type": "string"
},
"crs": {
"type": "string",

"description": "CRS code identifier of station containing asset",

"examples": [
"WAT"
]
},
"lat": {
"type": "string"
},
"location": {
"type": "string"
},
"long": {
"type": "string"
},
"postcode": {
"type": "string",

"description": "The postcode of the station that the asset is in"
},
"route": {
"type": "string"
},
"sensorId": {
"type": "string"
},
"station": {
"type": "string"
},
"territory": {
"type": "string"
},
"toc": {
"type": "string"
},
"type": {
"type": "string"
},
"uprn": {
"type": "string",

"description": "The unique identifier for the asset in the system as a whole.",

"examples": [
"u263729000028"
]

}
}