NAV Navbar
shell ruby python javascript
  • 1. Introduction
  • 2. Authentication
  • 3. The detect endpoint
  • 4. The stops endpoint
  • 5. Response codes
  • 6. Practical implementation
  • 1. Introduction

    API route URL is as follows:

    https://api.signalbox.io/v2
    

    Signalbox API is a web service that allows mobile devices to detect a passenger's context throughout a journey, enhancing the performance of apps by allowing them to provide real-time information based on exact needs, and enabling new kinds of services, such as advanced route guidance for people with sight loss or hearing difficulties.

    This document describes version 2 of our API, which covers the whole of the UK's national rail network, not including city-based mass transit systems, like the London Underground. Subsequent versions will be extended to include additional areas of coverage.

    The route URL of our API is https://api.signalbox.io/v2. Note, the version number is part of the route URL and must be included in all calls. The API has one endpoint, called detect, used to obtain a context. This document describes the detect endpoint, together with information on authentication, response codes, and best practice for implementation.

    2. Authentication

    You can check you are authenticated by sending a request to the test endpoint:

    GET https://api.signalbox.io/v2/detect
    

    If you are authenticated the following response is returned (from the test endpoint only):

    {
    "message": "Hello, {YOUR_USERNAME}"
    }
    

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

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

    To allow access, we use API keys, which are tokens that a client provides when making API calls. We provide you (the client) with an API key, which must then be included in all calls by adding the key to the header of the request. The format of the header is as follows:

    Parameter Value
    Authorization Bearer {YOUR_API_KEY}

    Where you must replace {YOUR_API_KEY} with your API key. To request an API key please contact us. If your API key is invalid or you forgot to include an authorisation header, a 401 HTTP status is returned, along with a json formatted response shown in the accompanying panel.

    While it is not required, it is possible to check you are authenticated by sending a GET request (with the authentication header) to the test endpoint:

    GET https://api.signalbox.io/v2/detect

    If you are authenticated a 200 HTTP status is returned, along with the json formatted response shown in the accompanying panel.

    3. The detect endpoint

    The detect endpoint is used to obtain a context. A client device sends location information to the endpoint. This information is combined with real-time transport data and map data in our AI-based algorithm. Following this, the computed context is sent in a response to the client.

    The context contains an estimation of the probability the device is on any train. In addition, the context includes details about all the possible trains that the device might be on - each possible train is called a candidate train. For each candidate train, additional information is returned, including the probability that the device is on that particular train, and details of the stops the train calls at.

    To compute a context, Signalbox only requires a shapshot of the device's location information - it does not require a series of measurements collected over time. Therefore, our service can provide a context almost immediately without conducting background tracking of the device's movements. As a result, for the vast majority of applications, no additional app permissions are required beyond those that need be granted for normal operation.

    The format of both the request and response are described as follows.

    3.1 Request

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

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

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

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

    A header must be submited, with the following format:

    Parameter Value
    Content-Type application/json
    Authorization Bearer {YOUR_API_KEY}

    Where {YOUR_API_KEY} must be replaced with your API key.

    Body

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

    require 'uri'
    require 'net/http'
    
    url = URI("https://api.signalbox.io/v2/detect")
    
    http = Net::HTTP.new(url.host, url.port)
    
    request = Net::HTTP::Post.new(url)
    request["Content-Type"] = 'application/json'
    request["Authorization"] = 'Bearer {YOUR_API_KEY}'
    request.body = "{\
                    \"lon\": -0.11731035,\
                    \"lat\": 51.49363,\
                    \"accuracy\": 10,\
                    \"requestDatetime\": \"2018-02-24T15:22:37+01:00\",\
                    \"speed\": 10.25,\
                    \"bearing\": 15.0\
                    }"
    
    response = http.request(request)
    puts response.read_body
    
    import requests
    import json
    
    url = "https://api.signalbox.io/v2/detect"
    
    payload_dict = {
        'lon': -0.11731035, 
        'lat': 51.49363,
        'accuracy': 10,
        'requestDatetime': '2018-02-24T15:22:37+01:00',
        'speed': 10.25,
        'bearing': 15.0
        }
    
    payload = json.dumps(payload_dict)
    
    headers = {
        'Content-Type': "application/json",
        'Authorization': "{YOUR_API_KEY}"
        }
    
    response = requests.request("POST", url, data=payload, headers=headers)
    print(response.text)
    
    
    curl --request POST \
      --url 'https://api.signalbox.io/v2/detect' \
      --header 'Authorization: Bearer {YOUR_API_KEY}' \
      --header 'Content-Type: application/json' \
      --data '{
    "lon": -0.11731035, 
    "lat": 51.49363,
    "accuracy": 10,
    "requestDatetime": "2018-02-24T15:22:37+01:00",
    "speed": 10.25,
    "bearing": 15.0
    }
    '
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://api.signalbox.io/v2/detect",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer {YOUR_API_KEY}"
      },
      "processData": false,
      "data": "{\
                \"lon\": -0.11731035,\
                \"lat\": 51.49363,\
                \"accuracy\": 10,\
                \"requestDatetime\": \"2018-02-24T15:22:37+01:00\",\
                \"speed\": 10.25,\
                \"bearing\": 15.0\
                }"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    

    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.
    requestDatetime
    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 our API.
    bearing
    optional
    Number This is the device's bearing, which is the horizontal direction of travel (note, this is not related to the device's orientation). There is no default value.
    speed
    optional
    Number This is the speed of the device. The units are metres per second. There is no default value.
    altitude
    optional
    Number This is the device's height. The units are metres above the WGS 84 reference ellipsoid. There is no default value.

    Notes:

    3.2 Response

    This is an example of a response:

    {
        "requestDatetime":"2018-02-02T14:30:00+01:00",
        "onTrain": 0.12,    
        "trains":[
        {
            // See the train object section below.  
        }
      ]
    }
    

    The response is a JSON-formatted with the following fields:

    Parameter Type Description
    requestDatetime String This is the datetime that relates to the request. If a datetime field was included by the client in the request, then the associated value will be used. If no datetime field was included in the request, then the default value will be used, which is the datetime the request was received by Signalbox. The format is "YYYY-MM-DDThh:mm:ss+hh:mm", which is the ISO 8601 standard format with the offset from UTC. By default we return the requestDatetime with UTC offset that is equal to UK local time.
    onTrain Number This is the probability, between 0 and 1, that the device is in on a train.
    trains Array This is an an array, where each element in the array contains a train object. An empty array is returned if no possible candidate trains are detected.

    Note, the value of the onTrain field is the probability that the device is on any train within the network covered by Signalbox. This includes trains that are stationary (for example trains that are waiting at a station), and also trains that are moving (for example trains travelling between stations). If the probability is 0 then we are certain that the device is not on a train, and if the probability is 1, then we are certain that the device is on a train.

    The trains array contains details of all the candidate trains that the device could be on - each element in the array represents a candidate train with a train object. If the probability of the device being on a train is greater than 0, then the trains array will have one or more train objects. In contrast, if the probability that the device is on a train is 0, then the trains array will be an empty array. The train object is described in the following section.

    3.2.1 Train object

    This is an example of a trains array:

    {
        trains: [
        {
            "scheduleId" : "37794311-0127-4f14-b390-55f2c30fb838",
            "probability": 0.22,
            "trainOperator": "Great Western Railway",
            "stops": [
            // See the stop object below
            ]
        },
        {
            "scheduleId": "0001c69e-31f6-4fa5-a90d-d14dcf9b7f4a",
            "probability": 0.78,
            "trainOperator": "Greater Anglia",
            "stops": [
            // See the stop object below
            ]
        }
        ]
    }
    
    

    The request body's trains array contains zero or more train objects. A train object represents a train the device could be on, called a candidate train, and contains the following fields:

    Parameter Type Description
    scheduleId String This is a universally unique identifier (UUID) that represents the schedule of the train. Each UUID is unique to a particular schedule and has its standard text-based representation (32 alphanumeric characters and four hyphens).
    probability Number The probability that a device is on the train.
    trainOperator String The name of the train operating company.
    stops Array This is an array, of length two or more, that represents the stops on the train's route. Each element of the array contains a stop object, described in the following section.

    3.2.2 Stop object

    This is an example of a stop object.

    {
      "name": "Alton",
      "crs": "AON",
        "arrival": null,
       "departure": "2018-02-24T15:22:37+01:00",
        "actualArrival": null,
        "actualDeparture": "2018-02-24T15:22:37+01:00"       
    }
    

    The stop object represents a stop on a train's route and contains the following fields:

    Parameter Type Description
    name String The name of the station.
    crs String The computer reservation system (CRS) code of the station, which is a unique three letter code that uniquely identifies the station. A list of CRS codes can be found here.
    arrival String The combined date and time when the train is due, or was due, to arrive at a stop (according to the timetable). The format is "YYYY-MM-DDThh:mm:ss+hh:mm", which is the ISO 8601 standard format with the offset from UTC. By default we return a UTC offset that is equal to UK local time. A null value is returned if there is no arrival time for that particular stop.
    departure String The combined date and time when the train is due, or was due, to arrive at a stop (according to the timetable). The format is "YYYY-MM-DDThh:mm:ss+hh:mm", which is the ISO 8601 standard format with the offset from UTC. By default we return a UTC offset that is equal to UK local time. A null value is returned if there is no departure time for that particular stop.
    actualArrival Number This is the actual arrival time. For stops where the train is yet to arrive from that stop, the actual arrival time is the predicted arrival time that will occur in the future. For stops that the train has already arrived at, then the actual arrival time is the time that occurred in the past. The format is "YYYY-MM-DDThh:mm:ss+hh:mm", which is the ISO 8601 standard format with the offset from UTC. By default we return a UTC offset that is equal to UK local time. A null value is returned if there is no arrival time for that particular stop.
    actualDeparture Number This is the actual departure time. For stops where the train is yet to depart at that stop, the actual departure time is the predicted departure time that will occur in the future. For stops that the train has already departed from, then the departure time is time that actually occurred in the past. The format is "YYYY-MM-DDThh:mm:ss+hh:mm", which is the ISO 8601 standard format with the offset from UTC. By default we return a UTC offset that is equal to UK local time. A null value is returned if there is no departure time for that particular stop.

    4. The stops endpoint

    The stops endpoint is used to obtain a list of stop objects that belong to a schedule, identified by the given schedule ID. The stops object is typically used once the train a device is on has been identified using the detect endpoint. This provides the schedule ID, which is subsequently used to query the stops endpoint.

    4.1 Request

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

    POST https://api.signalbox.io/v2/stops
    

    The stops endpoint uses the POST method and has the URL:

    POST https://api.signalbox.io/v2/stops

    A header must be submitted with the same format as the header used in the detect endpoint.

    Body

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

    {
    "scheduleId": "6fd1246c-e8b4-4e38-9c60-3b055e28e874"
    }
    

    The request body has only one field:

    Parameter Type Description
    scheduleId String This is a universally unique identifier (UUID) that represents the schedule of the train. Each UUID is unique to a particular schedule and has its standard text-based representation (32 alphanumeric characters and four hyphens).

    4.2 Response

    This is an example of a response mady be the stops endpoint:

    {
        "stops": [
            // See the stop object 
            ]
    }
    

    The response is JSON-formatted object with only one field

    Parameter Type Description
    stops Array This is an array, of length two or more, that represents the stops on the train's route. Each element of the array contains a stop object, as described previously.

    5. Response codes

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

    {
        "message": "{EXPLANATION_FOR_RESPONSE}"
    }
    

    Signalbox uses the following HTTP response status codes:

    Code Meaning
    200 Success - A successful response has been delivered by our API.
    400 Bad request - This is normally due to the request JSON not being parsed, for example due to mandatory fields not being included or values being an incorrect type.
    401 Unauthorized - This response can occur when your API key is invalid or when your previous key 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's root URL and the 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 - We had a problem with our server. This may have occurred because we are upgrading or the server has been overloaded. Please try again later.
    512 Algorithm error - An unexpected error has occurred with our algorithm. We will automatically log the problem and implement a fix.

    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.

    6. Practical implementation

    This section contains additional information that you might find useful for the practical implementation of Signalbox.