Signalbox REST API - Version 2.5

1. Introduction

Signalbox REST API v2.5 root URL:

https://api.signalbox.io/v2.5/

Signalbox is a web service enabling the automatic identification of which train service a device is travelling on. This enables mobile applications and internet of things devices to know which train service they are currently travelling on using only the sensor data available from the device and a simple call to the Signalbox API. Alongside this core functionality, Signalbox provides a number of ancillary functions to support the many use cases it enables.

Signalbox provides a simple, versioned REST API.

The root URL of version 2.5 of the API is https://api.signalbox.io/v2.5/. All API endpoints that are part of this version of the API start with this URL.

The Signalbox REST API returns all responses encoded as JSON.

Signalbox customers will find additional detail and best practices in the Enterprise docs.

2. Authentication

The authenticated endpoint uses the GET method and has the URL https://api.signalbox.io/v2.5/authenticated:

GET https://api.signalbox.io/v2.5/authenticated

Check you are authenticated by sending a GET request to the authenticated endpoint:

curl --request GET \
  --url 'https://api.signalbox.io/v2.5/authenticated' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

import requests

url = "https://api.signalbox.io/v2.5/authenticated"
headers = {
    'Authorization': "Bearer {YOUR_API_KEY}"
}

response = requests.get(url, headers=headers)

print(response.text)

If you are authenticated the following response is returned:

{
    "message":"Authentication Successful"
}

If you are not authenticated the following response is returned from all endpoints that require authentication:

{
    "message": "Unauthorised. Please check your credentials."
}

Access to the Signalbox REST API is restricted using API keys. When signing up for access to the Signalbox API, you will have been provided with an API key. This must be included in all requests to the Signalbox REST API.

Your API key must be sent in the Authorization header of all HTTP requests as a Bearer Token as follows (replacing {YOUR_API_KEY} with your API key):

Header Name	Value
`Authorization`	`Bearer {YOUR_API_KEY}`

If you do not have an API key please contact us to request one.

If your API key is invalid or you forgot to include an authorisation request header, a 401 HTTP status code is returned, along with a JSON response indicating an authorization failure.

You may optionally check you are authenticated by sending a GET request (including the Authorization header) to the authenticated endpoint.

3. The detect endpoint

The detect endpoint is used to match the location of a device to a particular train service.

The detect takes as input the location measurement as reported by the underlying operating system of the device, and returns the train service (or multiple train services) the device is estimated to be on.

For each train service in the returned results, a probability field is included. Where a single train service is returned, this will always be 1.0. Where multiple possible matching train services are returned, this probability across all returned train services will sum to 1.0.

At a minimum, requests to the detect endpoint must contain a device’s location measurement. Additional fields can be included where available to improve the accuracy of the returned results as outlined below.

3.1. Request

The detect endpoint uses the POST method and has the URL https://api.signalbox.io/v2.5/detect:

POST https://api.signalbox.io/v2.5/detect

The detect endpoint accepts a POST request with the body encoded as the content type application/json.

POST https://api.signalbox.io/v2.5/detect

Note that the authorisation header must be included in all requests to this endpoint, as described in the authentication section.

Body

Below is an example of a request made to the detect endpoint.

curl --request POST \
  --url 'https://api.signalbox.io/v2.5/detect' \
  --header 'Authorization: Bearer {YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
"lon": -0.11731035,
"lat": 51.49363,
"accuracy": 10,
"ts": "2020-02-24T15:22:37+01:00",
"speed": 10.25,
"bearing": 15.0,
"include_on_network_probability": true,
"include_nearby_stops": true,
"include_rsid": true
}'

import json
import requests

url = 'https://api.signalbox.io/v2.5/detect'
payload = {
    'lon': -0.11731035,
    'lat': 51.49363,
    'accuracy': 10,
    'ts': '2020-02-24T15:22:37+01:00',
    'speed': 10.25,
    'bearing': 15.0,
    'include_on_network_probability': True,
    'include_nearby_stops': True,
    'include_rsid': True,
}
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_API_KEY}',
}

response = requests.post(url, data=json.dumps(payload), headers=headers)
print(response.text)

The request body has the following fields:

Parameter	Type	Description
`lon` required	Number	The longitude of the device’s location. The units are decimal degrees. There is no default value.
`lat` required	Number	The latitude of the device’s location. The units are decimal degrees. There is no default value.
`accuracy` required	Number	The accuracy of the device’s location, which represents the radius of a circle surrounding the estimated location. The units are metres. There is no default value.
`ts` optional	String	The combined date and time when the request measurements were obtained. The required format is `"YYYY-MM-DDThh:mm:ss+hh:mm"`, which is the ISO 8601 standard format with the offset from UTC. The default value is the date and time when the request was received by the Signalbox REST API.
`bearing` optional	Number	The device’s bearing, which is the horizontal direction of travel (note, this is not related to the device’s orientation). The units are decimal degrees, measured clockwise from geographic north. There is no default value.
`speed` optional	Number	This is the speed at which the device is currently moving. The units are metres per second. There is no default value.
`include_nearby_stops` optional	Boolean	If set to `true`, for each train detected, Signalbox will calculate the previous, current and next passenger stops, based on the assumption that the user is on the train. This information is returned in the response, and stops are represented using their Computer Reservation System (CRS) code.
`include_on_network_probability` optional	Boolean	If set to `true`, the probability that the user is on the rail network at the time of making the request will be included in the response. If not provided, this parameter defaults to `false`.
`include_rsid` optional	Boolean	If set to `true`, Retail Service IDs will be included in the results of this API call for all train services where they are available. If not provided, this parameter defaults to `false`. Note, there are circumstances in which a train without a RSID may be returned by Signalbox. Therefore, applications must be able to handle result sets where the RSID field may be `null`, either by ignoring those trains or by reverting to their Darwin RID, which is always included.
`multiping` optional	Boolean	If set to `true`, the response will include a field called `multiping_data`. The multiping data is required for the Multiping feature, which improves the accuracy train matching results (see section 3.5). If not provided, this parameter defaults to `false`.
`last_multiping_data` optional	String	This field forms part of the optional Multiping feature, described in detail in Section 3.5. This field should be populated with the `multiping_data` value from the previous detect request in the same user session to improve the accuracy of the results.

The include_nearby_stops functionality is currently considered to be in Beta and may change in future releases.

Notes:

Required fields - The fields lon, lat and accuracy are required, meaning they must be included in all requests to this endpoint.
Optional fields - The fields ts, bearing and speed are optional, which means they can be omitted. However, for the best possible detection accuracy, whenever available these values should be submitted.
Optional fields to request additional data - The optional fields include_on_network_probability and include_nearby_stops will result in additional calculations being carried out before the response is returned. For the fastest possible responses, you should avoid setting any of these parameters to true unless you specifically need to use the additional data provided by them.

3.2. Response

This is an example of a response:

{
  "trains": [
    {
      "rid": "37794311",
      "probability": 0.22,
      "rsid": "AB123455",
      "nearby_stops": {
        "previous_stop": "WAT",
        "current_stop": "CLJ",
        "next_stop": "WOK"
      }
    },
    {
      "rid": "37794311",
      "probability": 0.78,
      "rsid": "AB123456",
      "nearby_stops": {
        "previous_stop": "QRB",
        "current_stop": null,
        "next_stop": "CLJ"
      }
    }
  ],
  "on_network_probability": 0.94
}

The response is JSON-formatted with the following fields:

Parameter	Type	Description
`trains`	Array	This is an an array, where each element in the array contains a json with the rid of a candidate train and its probability.
`rid`	String	This is the unique ID for the train. It is the same ID that is used by Darwin, which is the UK rail industry’s official real-time train information source. The rid is a string, typically 15 characters long.
`rsid`	String	This is the Retail Service ID for the train. It will be included where available for all trains in the results set if `include_rsid` was specified in the request. As it is occasionally possible for Signalbox to return results including trains without an RSID, this may be `null` and applications must be able to handle this scenario gracefully, either by excluding those trains from use or identifying them by their Darwin `rid`, which will always be present.
`probability`	Number	The probability that a device is on this train service. If more than one possible train service is included in the response, the probabilities across all included services will sum to `1.0`.
`nearby_stops`	Object	An object consisting of three elements: `previous_stop`, `current_stop` and `next_stop`. For each of these elements, the value may either be `null` or the CRS code of a station. For each element, the values may be `null` depending on the progress on the service’s journey and the location data submitted with the request. Note, the `nearby_stops` object is only included in the response if `include_nearby_stops` was included and set to `true` in the request.
`on_network_probability`	Number	A decimal value between `0` and `1` indicating the probability that the user making the request is located on the GB National Rail network at the time of making the request. Only included in the response if `include_on_network_probability` was included and set to `true` in the request.
`multiping_data`	String	A String that contains encoded data required for the Multiping feature (see section 3.5). This may be saved and sent with the next request from the user in this session to improve the train detection accuracy.

The nearby_stops data is currently considered to be in Beta and may change in future releases.

Note, a 200 success response will be returned in all cases where the detect endpoint executes successfully, even if it identifies that the device is not on a train service and thus returns an empty list of trains in the results.

The HTTP Response headers received with a response from the /detect endpoint include a Request ID in the `X-Signalbox-Request-ID` header. This Request ID is used in the /feedback endpoint to identify the detect request to which the feedback relates.

3.3. Sample responses for testing

To facilitate testing software developed against the Signalbox REST API, the detect endpoint can accept a set of three special, fixed inputs which will always trigger the same fixed response.

The following latitude/longitude pairs, if provided as input to the detect endpoint, will always generate the exact same response as shown in the following table:

Longitude	Latitude	HTTP Status Code	Response Data
`1.0`	`1.0`	`200`	`{"trains": []}`
`2.0`	`1.0`	`200`	`{"trains": [{"rid": "200012131234567", "probability": 1.0}]}`
`3.0`	`1.0`	`200`	`{"trains": [ {"rid": "200012131234568", "probability": 0.78},` `{"rid": "200012131234569", "probability": 0.22}]}`

When sending a request containing any of these special longitude/latitude pairs, any numerical value will be accepted for the mandatory accuracy field, and the value of all optional request fields will be ignored.

3.4. Useful real locations for testing

Some useful real-world locations which we recommend for testing signalbox are included in the table below. They cover a range of activity levels from very busy routes into major stations to quiet rural backwater stations.

Longitude	Latitude	Activity Level	Description
`-0.117678`	`51.493184`	Very High	Approach to London Waterloo.
`-1.139679`	`53.527338`	High	Approximately 0.5km North of Doncaster.
`-3.54348`	`50.729523`	Medium	Approximately 1km north of Exeter St Davids.
`-4.137345`	`50.380575`	Low	Approach to Plymouth from the East.
`-1.549484`	`53.112921`	Very Low	Cromford station.

3.5 Multiping

Below is an example of a MultiPing request made to the detect endpoint.

curl --request POST \
  --url 'https://api.signalbox.io/v2.5/detect' \
  --header 'Authorization: Bearer {YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
"lon": -0.11731035,
"lat": 51.49363,
"accuracy": 10,
"ts": "2020-02-24T15:22:37+01:00",
"speed": 10.25,
"bearing": 15.0,
"multiping": true,
"last_multiping_data": "ewogICAgInRyYWlucyI6WwogICAgewogICAgICAgICJyaW"
}'

import json
import requests

url = 'https://api.signalbox.io/v2.5/detect'
payload = {
    'lon': -0.11731035,
    'lat': 51.49363,
    'accuracy': 10,
    'ts': '2020-02-24T15:22:37+01:00',
    'speed': 10.25,
    'bearing': 15.0,
    'multiping': true,
    'last_multiping_data': 'ewogICAgInRyYWlucyI6WwogICAgewogICAgICAgICJyaW',
}
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_API_KEY}',
}

response = requests.post(url, data=json.dumps(payload), headers=headers)
print(response.text)

This is an example of a MultiPing response:

{
  "trains": [
    {
      "rid": "37794311",
      "probability": 0.22
    },
    {
      "rid": "37794311",
      "probability": 0.78
    }
  ],
  "multiping_data": "ewogICAgInRyYWlucyI6WwogICAgewogICAgICAgICJyaW"
}

The Multiping feature of the detect endpoint allows for data from a previous detect request to be used to improve the estimation accuracy of subsequent requests. Use of this feature substantially increases the likelihood of a single correct train service being identified.

Multiping can be activated by:

Setting the multiping field to true in all detect requests,
Saving the multiping_data value returned between requests,
Sending the previous multiping_data value in the last_multiping_data field of the request payload of any subsequent detect request by that user within a reasonable time period.

Usage recommendations

For real-time end-user facing applications, such as passenger information apps, we recommend using Multiping to maximise the likelihood of a single matching train being identified by the detect end point. In order to maximise the effectiveness but minimise any delay in response to user interaction, we recommend making an initial request to the detect endpoint prior to the user explicitly requesting their train to be identified, for example, when checking their location on first load of the application, or when entering into the live running information section of the application. This means that when the user requests their train to be identified, a second detect request may be sent taking advantage of the encoded_estiamte data from the first request to increase its accuracy and specificity.

Multiping should also be used to provide the best possible user experience in any situation where the user is presented with the opportunity to re-trigger the detect request manually, or when the user interface allows them to trigger detect requests multiple times in a single journey.

4. The feedback endpoint

The feedback endpoint is used to provide automatic feedback on detect results to the Signalbox algorithm to allow it to learn and improve the detection accuracy.

The feedback endpoint can be used to indicate any of the following outcomes:

The results from the detect endpoint correctly included the train the user was travelling on.
The results from then detect endpoint did not correctly include the train the user was travelling on, but the user was able to identify their train manually through a search.
The results from the detect endpoint did not correctly include the train the user was travelling on, and the user retried searching for their train through the detect endpoint again.
The user has indicated that the results from the detect endpoint did not correctly include the train the user was travelling on.

In situations where you use the detect endpoint to identify the train service a user is travelling on, and then allow the user to manually overrule the selection in the case where the wrong train service is suggested, this endpoint can be used to increase the accuracy of future detect calls by sending the rid of the train service the user actually indicates they are travelling on to Signalbox.

If you make use of this endpoint, you should always send the “correct” train service as identified by the user when it is known, including when they accept the train service suggested by the detect endpoint (true positives) as well as when they manually specify a different train service (false positives/negatives). This is very important - if feedback is only provided where the detect endpoint provides the incorrect service, the feedback is not effective in helping the Signalbox algorithm to learn.

4.1 Request

The feedback endpoint uses the POST method and has the URL https://api.signalbox.io/v2.5/feedback:

POST https://api.signalbox.io/v2.5/feedback

The feedback endpoint accepts a POST request with the body encoded as the content type application/json.

POST https://api.signalbox.io/v2.5/feedback

Note that the authorisation header must be included in all requests to this endpoint, as described in the authentication section.

Body

Below is an example of a request made to the feedback endpoint.

curl --request POST \
  --url 'https://api.signalbox.io/v2.5/feedback' \
  --header 'Authorization: Bearer {YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
"detect_request_id": "eddb4ee8-7a45-42f0-af32-b1517f2a031d",
"chosen_rid": "37794311"
}'

import json
import requests

url = 'https://api.signalbox.io/v2.5/feedback'
payload = {
	'detect_request_id': 'eddb4ee8-7a45-42f0-af32-b1517f2a031d',
    'chosen_rid': '37794311',
}
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {YOUR_API_KEY}',
}

response = requests.post(url, data=json.dumps(payload), headers=headers)
print(response.text)

The request body has the following fields:

Parameter	Type	Description
`detect_request_id` required	String	The Request ID (value of the `X-Signalbox-Request-ID` HTTP header in the response) of the `detect` endpoint request to which this feedback relates.
`chosen_rid` optional	String	The Darwin `rid` of the service that the user has indicated is the one on which they are travelling (which may or may not have been included in the `detect` response to which this feedback relates). This should always be provided where know, as without it the accuracy of future Signalbox `detect` calls will not be increased.
`user_retry` optional	Boolean	A boolean indicating that the users' response to being presented with the response to a `detect` request was to retry the process by running a fresh `/detect` request, due to not seeing the train they are travelling on in the results.
`user_search` optional	Boolean	A boolean indicating that the users' response to being presented with the response to a `detect` request was to abandon the `detect` results due to not seeing the train they are travelling on in those results, and instead to attempt a manual search for their train.
`user_train_not_found` optional	Boolean	A boolean indicating that the user has indicated that the `detect` results they were presented with did not include the train on which they are currently travelling.

4.2 Response

The feedback endpoint returns an empty JSON object, with the HTTP status code 200 if the feedback is received successfully.

5. The trains endpoint

The trains endpoint is used to look up the details of an individual train service.

Trains may be looked up using the Darwin RID, which is the primary unique identifier for train services throughout the Signalbox API. Alternatively, trains may also be looked up using their Timetable UID. This provides a means of integrating Signalbox API calls with data from other industry APIs which use Timetable UIDs as their primary identifier for train services and do not make use of Darwin RIDs.

5.1. Request

The trains endpoint uses the GET method and has the URL https://api.signalbox.io/v2.5/trains/{rid}

GET https://api.signalbox.io/v2.5/trains/2020010112345678

Alternatively, the trains endpoint may be queried with a Timetable UID at the URL https://api.signalbox.io/v2.5/trains/uid/{uid}

GET https://api.signalbox.io/v2.5/trains/uid/G123456

The trains endpoint accepts a GET request with the Darwin RID as part of the path.

GET https://api.signalbox.io/v2.5/trains/{rid}

The alternative formulation of the trains endpoint accepts a GET request with the Timetable UID as part of the path.

GET https://api.signalbox.io/v2.5/trains/uid/{uid}

Note that the authorisation header must be included in all requests to this endpoint, as described in the authentication section.

Below is an example of a request made to the trains endpoint to look up a train by Darwin RID.

curl --request GET \
  --url 'https://api.signalbox.io/v2.5/trains/{rid}' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

import requests

url = "https://api.signalbox.io/v2.5/trains/{}".format("{rid}")
headers = {
    'Authorization': "Bearer {YOUR_API_KEY}"
}

response = requests.get(url, headers=headers)

print(response.text)

And here is an example of a request made to the trains endpoint to look up a train by Timetable UID.

curl --request GET \
  --url 'https://api.signalbox.io/v2.5/trains/uid/{uid}' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

import requests

url = "https://api.signalbox.io/v2.5/trains/uid/{}".format("{uid}")
headers = {
    'Authorization': "Bearer {YOUR_API_KEY}"
}

response = requests.get(url, headers=headers)

print(response.text)

5.2. Response

This is an example of a response:

{
  "delay": 3.0,
  "destination_name": "London Waterloo",
  "headcode": "2P94",
  "origin_name": "Portsmouth Harbour",
  "rid": "202201127656450",
  "stops": [
    {
      "actual_arrival": null,
      "actual_departure": "2022-01-12T07:34:00+00:00",
      "arrival": null,
      "crs": "PMH",
      "departure": "2022-01-12T07:31:00+00:00",
      "name": "Portsmouth Harbour",
      "platform": "4"
    },
    {
      "actual_arrival": "2022-01-12T09:21:00+00:00",
      "actual_departure": "2022-01-12T09:22:00+00:00",
      "arrival": "2022-01-12T09:14:00+00:00",
      "crs": "WOK",
      "departure": "2022-01-12T09:15:00+00:00",
      "name": "Woking",
      "platform": "2"
    },
    {
      "actual_arrival": "2022-01-12T09:47:00+00:00",
      "actual_departure": null,
      "arrival": "2022-01-12T09:44:00+00:00",
      "crs": "WAT",
      "departure": null,
      "name": "London Waterloo",
      "platform": "16"
    }
  ],
  "toc_code": "SW",
  "train_operator": "South Western Railway",
  "uid": "L56450"

}

The response is JSON-formatted with the following fields:

Parameter	Type	Description
`delay`	Number	The number of minutes delayed the train is currently running.
`destination_name`	String	The name of the train service’s destination station.
`headcode`	String	The headcode (or Train ID) the train service is running under.
`origin_name`	String	The name of the train service’s origin station.
`rid`	String	The Darwin RID of the train service.
`toc_code`	String	The two letter ATOC code for the train operating company.
`train_operator`	String	The human-readable name of the train operating company.
`uid`	String	The Timetable UID of the train service.
`stops`	Array	An array of calling points of the train.
`arrival`	String	An ISO datetime representing the time the train is scheduled to arrive at the stop, or null if there is no scheduled arrival time.
`departure`	String	An ISO datetime representing the time the train is scheduled to depart from the stop, or null if there is no scheduled departure time.
`actual_arrival`	String	An ISO datetime. If the time is in the future, it is the time the train is forecast to arrive at the stop. If the time is in the past, it is the time the train was actually recorded as arriving at the stop. If there is no scheduled arrival, this field will be null.
`actual_departure`	String	An ISO datetime. If the time is in the future, it is the time the train is forecast to depart from the stop. If the time is in the past, it is the time the train was actually recorded as departing from the stop. If there is no scheduled departure, this field will be null.
`crs`	String	The three-letter CRS code for the station at which this stop occurs.
`name`	String	The human-readable name of the station at which this stop occurs.
`platform`	String	The platform at which the service will stop.

6. The train-locations endpoint

The train-locations endpoint is used to look up the geospatial locations of one or several trains.

This endpoint is typically used to provide live map visualisations of a single train, trains in a given geographical area or trains around a particular location. As well as providing the current location of trains, it can also optionally provide a predicted location for a configurable period into the future to allow for visually engaging animations in live map displays.

This is a new endpoint that is currently being tested and access is not generally available. While we aim to make this endpoint available in the future this is subject to ongoing testing. BETA

6.1. Single train request

The train-locations endpoint uses the GET method and has the URL https://api.signalbox.io/v2.5/train-locations/{rid}

GET https://api.signalbox.io/v2.5/train-locations/2020010112345678

To retrieve the location of a single train, the train-locations endpoint accepts a GET request with the Darwin RID as part of the path.

GET https://api.signalbox.io/v2.5/train-locations/{rid}

The following URL parameters are available for this endpoint.

Parameter	Type	Description
`predict`	Number	Optional. If specified, Signalbox API will additionally include a prediction of the future location of the train the specified number of seconds in the future in the response data. Acceptable values are in the range from 5 to 60 inclusive.

Notes:

The authorisation header must be included in all requests to this endpoint, as described in the authentication section.
If you only have the timetable UID of the train you wish to know the location of, but do not have it’s RID, you should first use the trains endpoint to look up the train RID before passing the returned RID to this endpoint to request the train’s location.

Below is an example of a request made to the train-locations endpoint to look up the location of a single train by RID.

curl --request GET \
  --url 'https://api.signalbox.io/v2.5/train-locations/{rid}?predict=15' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

import requests

url = "https://api.signalbox.io/v2.5/train-locations/{}?predict=15".format("{rid}")
headers = {
    'Authorization': "Bearer {YOUR_API_KEY}"
}

response = requests.get(url, headers=headers)

print(response.text)

6.2. Single train response

This is an example of a response:

{
  "delay": 0,
  "location": {
    "lat": 50.79643768657117,
    "lon": -1.077466859523418
  },
  "predicted_location": {
    "lat": 50.79730465116109,
    "lon": -1.0814230844743684
  },
  "predicted_ts": "2020-01-02T10:03:54+00:00",
  "rid": "202001127652863",
  "ts": "2020-01-02T10:03:24+00:00"
}

The response is JSON-formatted with the following fields:

Parameter	Type	Description
`delay`	Number	The number of minutes delayed the train is currently running.
`location`	Object	An object describing the geographical location of the train service at the time of the request.
`predicted_location`	Object	An object describing the predicted geogrphical location of the train service the number of seconds in the future specified in the `predict` request parameter. Not present if the `predict` parameter was not provided with the request.
`ts`	String	Timestamp in ISO format indicating the time at which the location was requested.
`predicted_ts`	String	Timestamp in ISO format indicating the time at which the predicted location is predicted for. Only included if the `predicted` request parameter was set.
`rid`	String	The Darwin RID for the train service this location information relates to.
`lat`	Number	Latitude component of a location object.
`lon`	Number	Longitude component of a location object.

6.3 Multiple trains request

The train-locations endpoint uses the GET method and has the URL https://api.signalbox.io/v2.5/train-locations

GET https://api.signalbox.io/v2.5/train-locations?crs=WAT

To retrieve the location of all the trains calling at a given location, the train-locations endpoint accepts a GET request with the mandatory URL parameter crs specifying the CRS code of the station which all the returned trains must call at.

GET https://api.signalbox.io/v2.5/train-locations?crs=WAT

The following URL parameters are available for this endpoint.

Parameter	Type	Description
`crs` required	String	The CRS code of the station which all of the trains in the result set must call at.
`bbox`	String	Optional. If specified, limit the trains returned to those appearing within the provided bounding box, which is specified in the URL parameter in the following format: `lon_min,lat_min,lon_max,lat_max`.

Notes:

The authorisation header must be included in all requests to this endpoint, as described in the authentication section.

Below is an example of a request made to the train-locations endpoint to look up the location of all trains calling at a given station and currently within a given bounding box.

curl --request GET \
  --url 'https://api.signalbox.io/v2.5/train-locations?crs={crs}&bbox={lon_min,lat_min,lon_max,lat_max}' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

import requests

url = "https://api.signalbox.io/v2.5/train-locations?crs={crs}&bbox={},{},{},{}".
    format(
        "{crs}",
        "{lon_min}",
        "{lat_min}",
        "{lon_max}",
        "{lat_max}",
    )
headers = {
    'Authorization': "Bearer {YOUR_API_KEY}"
}

response = requests.get(url, headers=headers)

print(response.text)

6.4 Multiple trains response

This is an example of a response:

{
  "trains": [
    {
      "delay": 0,
      "location": {
        "lat": 50.19063084014832,
        "lon": -5.399869140660271
      },
      "rid": "202001127688381"
    },
    {
      "delay": 0,
      "location": {
        "lat": 51.35031552018705,
        "lon": -2.9335016499333686
      },
      "rid": "202001127687718"
    }
  ],
  "ts": "2020-01-12T10:28:09+00:00"
}

The response is JSON-formatted with the following fields:

Parameter	Type	Description
`ts`	String	Timestamp in ISO format indicating the timestamp to which the location data corresponds.
`trains`	Array	List containing an object ofr each of the trains matching the provided query parameters.
`rid`	String	The Darwin RID for the train service this object describes.
`delay`	Number	The number of minutes delayed the train is currently running.
`location`	Object	An object describing the geographical location of the train service at the time of the request.
`lat`	Number	Latitude component of a location object.
`lon`	Number	Longitude component of a location object.

7. The stations endpoint

The stations endpoint is used to look up the list of train services departing from a given station (identified by its 3-letter CRS code) in the near future - the services which would appear on a departure board at that station.

Responses from this endpoint include some basic details of the individual train services, but extra detail required for sophisticated departure board use cases should be looked up from alternative API endpoints using the Darwin RID.

This is a new endpoint that is currently being tested and access is not generally available. While we aim to make this endpoint available in the future this is subject to ongoing testing. BETA

7.1. Request

The station endpoint uses the GET method and has the URL https://api.signalbox.io/v2.5/stations/{crs}

GET https://api.signalbox.io/v2.5/stations/YVJ

The stations endpoint accepts a GET request with a station’s three-letter CRS code as part of the path.

GET https://api.signalbox.io/v2.5/stations/{crs}

Note that the authorisation header must be included in all requests to this endpoint, as described in the _ authentication_ section.

Below is an example of a request made to the stations endpoint to look up the upcoming departures for a given station.

curl --request GET \
  --url 'https://api.signalbox.io/v2.5/stations/{crs}' \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

import requests

url = "https://api.signalbox.io/v2.5/stations/{}".format("{crs}")
headers = {
    'Authorization': "Bearer {YOUR_API_KEY}"
}

response = requests.get(url, headers=headers)

print(response.text)

The following URL parameters are available for this endpoint.

Parameter	Type	Description
`horizon`	Number	Optional. How far (in minutes) into the future departures should go in the response. Defaults to `180` (3 hours).

7.2. Response

This is an example of a response:

{
  "trains": [
    {
      "rid": "202205178966785",
      "toc_code": "SW",
      "train_operator": "South Western Railway",
      "delay": 0,
      "departure": "2022-05-17T16:30:00+00:00",
      "actual_departure": "2022-05-17T16:36:00+00:00",
      "platform": "1",
      "cancelled": false,
      "origin_name": "Exeter St Davids",
      "destination_name": "London Waterloo"
    },
    {
      "rid": "202205178966733",
      "toc_code": "SW",
      "train_operator": "South Western Railway",
      "delay": 10,
      "departure": "2022-05-17T16:39:30+00:00",
      "actual_departure": "2022-05-17T16:54:00+00:00",
      "platform": "2",
      "cancelled": false,
      "origin_name": "London Waterloo",
      "destination_name": "Exeter St Davids"
    },
    {
      "rid": "202205178966743",
      "toc_code": "SW",
      "train_operator": "South Western Railway",
      "delay": 0,
      "departure": "2022-05-17T17:41:00+00:00",
      "actual_departure": "2022-05-17T17:41:00+00:00",
      "platform": "2",
      "cancelled": false,
      "origin_name": "London Waterloo",
      "destination_name": "Exeter St Davids"
    }
  ]
}

The response is JSON-formatted with the following fields:

Parameter	Type	Description
`trains`	Array	An array of trains which will depart from the requested location.
`rid`	String	The Darwin RID of the train service.
`toc_code`	String	The two letter ATOC code for the train operating company.
`train_operator`	String	The human-readable name of the train operating company.
`delay`	Number	The number of minutes behind schedule the train is forecast to depart the station.
`departure`	String	An ISO datetime representing the time the train is scheduled to depart from the stop.
`actual_departure`	String	An ISO datetime representing the time the train is forecast to depart from the stop.
`platform`	String	The platform at which the service will stop.
`cancelled`	Boolean	`true` if the train service has been cancelled at this station, otherwise `false`.
`origin_name`	String	The name of the train service’s origin station.
`destination_name`	String	The name of the train service’s destination station.

A. Response codes

For response codes other than 200 a json object is returned that has the following format:

{
    "message": "{EXPLANATION_FOR_RESPONSE}"
}

The Signalbox REST API uses the following HTTP response status codes:

Code	Meaning
`200`	Success - Indicates the request has been successfully processed and a response returned.
`400`	Bad request - Indicates an invalid request was received, typically caused by missing mandatory fields in the request, incorrect types of request parameters or an incorrectly encoded request body.
`401`	Unauthorized - This response indicates your API key was not included in the request header, is invalid or has expired. If necessary, contact Signalbox for a new key.
`404`	Not Found - The requested resource could not be found. Please check that the endpoint URL is correct (including the Signalbox root URL and the API version number).
`429`	Too many requests – There have been too many requests because you have exceeded the rate limit for your current plan. If necessary, contact Signalbox to upgrade your plan.
`500`	Internal server error - An unexpected internal error occurred in the Signalbox API. Such errors are often transient in nature and so requests failing with this error code may be retried after a short time.
`512`	Algorithm error - An unexpected error occurred in the core Signalbox algorithm. The error has automatically been logged for investigation. The request should not be automatically retried.

For responses with codes other than 200, a json formatted object is returned with the format shown in the accompanying panel. Note that {EXPLANATION_FOR_RESPONSE} is replaced with a message explaining the reason for the unsuccessful response.

B. Practical implementation

This section contains additional guidelines and best practices for practical implementation of solutions making use of the Signalbox REST API.

Obtaining request values - Signalbox version 2.5 detect endpoint is designed to use information that is provided by the standard location providers of mobile operating systems such as Google Play Services (Android) and the Core Location Framework (iPhone). In general, a high accuracy location should be used, which is typically obtained from the device’s GNSS receiver. Note, the timestamp belonging to the device’s location object can also be used, but this must first be converted to the correct format as accepted by the Signalbox API.
Last known location - Signalbox version 2.5 detect endpoint is designed to operate with only one set of measurements. In general, this should be the device’s current location. However, in some circumstances, there may be a degradation in positioning performance due to poor ambient conditions, meaning the device’s current location cannot be obtained. In this situation, for some applications it may be acceptable to use the last known location, provided that the time elapsed since this was obtained is sufficiently small that a change of context is unlikely to have occurred.
App permissions - For standard operation, Signalbox version 2.5 detect endpoint is designed to be called while the app is being operated by the user. In this situation, an app requires permission to access location during foreground operation only. Because a data connection is required to call the API, internet permissions are also required. For some applications, background context tracking may be desired, in which case additional app permissions must be obtained.
Rate limiting - The Signalbox REST API is rate limited to prevent abuse and to ensure a high quality service to all users. Your rate limit depends on the pricing plan you are using. Please contact us if you require information about your rate limit. If your requests are being rate limited, HTTP response code 429 will be returned.
Response time - The response time of the detect endpoint depends on the complexity of the computation, which in turn depends on multiple factors, such as how many transport services are nearby and the accuracy of the sensor information provided.
Historical queries - Signalbox version 2.5 detect endpoint is designed for real-time applications and designed to operate for no more than twenty minutes old locations. For requests older than this, the endpoint will return a no-train response.