Sorry, you need to enable JavaScript to visit this website.

Sensor data

Used to retrieve action data from recorded files.

Table of contents

GET /api/<versionNumber>/videos/<video_id>/sensors[?filter=<sensors>][&offset_secs=<offset>][&length_secs=<length>] 

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/sensors[?filter=<sensors>][&offset_secs=<offset>][&length_secs=<length>]

Example:

http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-001-0001/sensors?filter=gnss,accel&offset_sec=3&length_secs=4

Parameters:

If 'filter' parameter is not specified, all sensor data existing in the video is returned. 'Filter' is comma-separated list of sensor names whose values are requested. Possible sensor name values are (at least one has to be specified if 'filter' exists in request):

Parameter Description Req'd?
[gnss] Used to request video's GNSS data in the response. No
[accel] User to request accelerometer data. No
[gyro] Used to request gyro data. No
[magnet] Used to request magnetometer data. No
[temp] Used to request temperature data. No
[pressure] Used to request barometer data. No
[heart_rate] Used to request heart rate data. No
[cadence] Used to request cadence data. No

Other URL parameters are:

Parameter Description Req'd? Type
baseURL Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. Yes 192.168.1.101
versionNumber Service version number. The current value is 2. Yes 2
[offset_secs] Offset (in seconds) from beginning of a video marking the point from which sensor data is delivered. No float
[length_secs] Length (in seconds) of the interval in video which sensor data is requested. No float

Response can be either JSON or binary data. Preferred format will be specified in Accept field of HTTP request header. Possible values:

Accept Description
application/json JSON format of sensor data is requested
binary/octet-stream Raw binary data is requested

Correspondingly, Content-type filed in HTTP response will be set to either application/json or binary/octet-stream.

Description:

Returns JSON array object or raw binary containing action data recorded in a file specified by it's id. This API call will return either all action data from a file or just a filtered subset if it's requested. Action data is sent in the same way in which it was received. Every action data sample is timestamped with 'offset_msecs' attribute, representing time (in milliseconds) from the beginning of the video when particular action data sample occured.

In order to reduce size of response (since it can easily be couple of MB big) instead of full sensor data names, abbreviations are used, especially for frequently sampled sensor who generate a lot of entries, as per following table: 

Parameter Description Req'd? Type
offset_msecs Number of milliseconds from beginning of a file when specified chunk of action data was sampled.
Example value: 1
Yes integer
accel_mg Accelerometer samples for all three axes in form [x,y,z] represented in milli G units.
 Example value: [500,-200,1200]
Yes array of integers
gyro_degsec Gyro samples for all three axes in form [x,y,z]. Each value represents angular rotation speed around given axes in deg/sec units.
Example value: [408,-142,-435]
Yes array of integers
magnet_mt Magnetometer samples for all three axes in form [x,y,z] represented in milli T (Tesla) units.
Example value: [1408,-1242,-3435]
Yes array of integers
temp_mc Temperature in mili-Celsius degrees taken inside of a camera housing.
Example value: [34500,34601]
Yes array of integers
pressure_pa Pressure samples in Pa (pascals).
Example values: [101203]
Yes array of integers
gnss Unix epoch time (number of seconds since Unix epoch). No integer
Mode. Possible values are: "NotSeen", "NoFix", "2D", "3D". No string
Speed in m/s units. No double
Altitude in meters. No double
Latitude in degrees. No double
Longitude in degrees. No double
Course made good (relative to true north) in degrees. No double
Vertical position uncertainty in meters. No double
Latitude position uncertainty in meters. No double
Longitude position uncertainty in meters. No double
Track uncertainty, degrees. No double
heart_rate Heart rate samples.
Example value: [80]
No integer
cadence Distance in meters (m). No integer
Number of revolutions per minute (rpm). No integer

When binary data response is requested, first information that shall be sent out is the version of the binary data output, number of entries in data type description table as well as the table itself (as presented here: Sensor data format).

What it means is that response will be constructed from:

  • Version of the binary data output
  • Number of entries in data type description table (4 bytes)
  • Data type description table (8 bytes * number of entries)
  • Size of the sensor data payload in bytes (4 bytes)
  • Raw sensor data payload

All items will be send as they are stored in the TTAD atom. Description of how sensor data is stored in the TTAD atom can be found on Sensor data format page.

If requested, content of binary data delivered will be filtered based on specified sensors.

Response codes:

Code Description
200 OK
404 Not Found (file with requested video_id not found)
500 Server Error (request can't be processed)

Example request 1:

GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/sensors
Accept: application/json

causes JSON array containing action data from a file specified by it's id to be returned as a response:

[ 
     { 
         "offset_msecs":1000, 
         "accel_mg":[ 
             [0.5,-0.2,1.2] 
         ] 
    }, 
    { 
         "offset_msecs":1050, 
         "gyro_degsec":[ 
             [408,-142,-435] 
         ]
     }, 
    { 
         "offset_msecs":1100, 
         "magnet_mt":[ 
             [2446,-1207,5227] 
         ] 
    }, 
    { 
         "offset_msecs":1150, 
         "temp_mc":[ 
             34.5 
         ] 
    },
    { 
         "offset_msecs":1200, 
         "pressure_pa":[ 
             1045 
         ] 
    }, 
    { 
         "offset_msecs":1250, 
         "gnss":[{ 
             "time_secs":"1436276052",
             "mode":"NotSeen", 
             "speed_mps":"11", 
             "alt_m":"854", 
             "lat_deg":"42.345432", 
             "lon_deg":"25.123456", 
             "track_deg":"120", 
             "range_alt_m":"nan",
             "range_lat_m":"nan", 
             "range_lon_m":"nan", 
             "range_track_deg":"nan" 
         }] 
    }, 
    { 
         "offset_msecs":1300, 
         "heart_rate":[ 
             80 
         ] 
     } 
     ...
]
 

Example request 2:

GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/sensors?filter=gnss,accel
Accept: application/json

causes JSON array containing only GNSS and accelerometer part of action data from a file specified by it's id to be returned as a response:

[ 
     { 
         "offset_msecs":1000, 
         "accel_mg":[ 
             [0.5,-0.2,1.2] 
        ] 
}, 
{ 
             "offset_msecs":1050, 
             "gnss":[{ 
             "time_secs":"1436276052", 
             "mode":"NotSeen", 
             "speed_mps":"11", 
             "alt_m":"854", 
             "lat_deg":"42.345432", 
             "lon_deg":"25.123456", 
             "track_deg":"120", 
             "range_alt_m":"nan", 
             "range_lat_m":"nan", 
             "range_lon_m":"nan", 
             "range_track_deg":"nan" 
         }] 
     } 
     ... 
] 

GET /api/<versionNumber>/videos/<video_id>/tags/<tag_id>/sensors[?filter=<sensors>]

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags/<tag_id>/sensors[?filter=<sensors>]

Example:

http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags/7666a33a-6275-4549-836b-4f8d00281233/sensors

Parameters:

If 'filter' parameter is not specified, all sensor data existing in the video is returned. 'Filter' is comma-separated list of sensor names whose values are requested. Possible sensor name values are (at least one has to be specified if 'filter' exists in request):

Parameter Description Req'd?
[gnss] Used to request video's GNSS data in the response. No
[accel] User to request accelerometer data. No
[gyro] Used to request gyro data. No
[magnet] Used to request magnetometer data. No
[temp] Used to request temperature data. No
[pressure] Used to request barometer data. No
[heart_rate] Used to request heart rate data. No
[cadence] Used to request cadence data. No

Other URL parameters are:

Parameter Description Req'd? Type
baseURL Fixed address, Bandit acts like an access point with this addres. TomTom Bandit's WiFi has to be turned on. Yes 192.168.1.101
versionNumber Service version number. The current value is 2. Yes 2
video_id Video id. Yes
tag_id Tag id. Yes

Response can be either JSON or binary data. Preferred format will be specified in Accept field of HTTP request header. Possible values:

Accept Description
application/json JSON format of sensor data is requested
binary/octet-stream Raw binary data is requested

Correspondingly, Content-type filed in HTTP response will be set to either application/json or binary/octet-stream.

Description:

Returns JSON array object or raw binary containing action data recording for a tag specified by it's tag_id from a video file specified by it's video_id. This API call will return either all action data from a file or just a filtered subset if it's requested. 

Every action data sample is timestamped with 'offset_msecs' attribute, representing time (in milliseconds) from the beginning of the video when particular action data sample occured.

When binary data response is requested, first information that shall be sent out is number of entries in data type description table as well as the table itself (as presented here: Sensor data format).

What it means is that response will be constructed from:

  • Version of the binary data output
  • Number of entries in data type description table (4 bytes)
  • Data type description table (8 bytes * number of entries)
  • Size of the sensor data payload in bytes (4 bytes)
  • Raw sensor data payload

All items will be send as they are stored in the TTAD atom. Description of how sensor data is stored in the TTAD atom can be found on Sensor data format page. If requested, content of binary data delivered will be filtered based on specified sensors.

Response codes:

 

Code Description
200 OK
404 Not Found (file with requested video_id or tag with requested tag_id not found)
500 Server Error (request can't be processed)

Example request 1:

GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags/7666a33a-6275-4549-836b-4f8d00281233/sensors
Accept: application/json

causes JSON array containing action data from a file specified by it's id to be returned as a response (given that tag requested starts at 4s):

[ 
     { 
         "offset_msecs":1000, 
         "accel_mg":[ 
             [0.5,-0.2,1.2] 
         ] 
}, 
{ 
         "offset_msecs":1050, 
         "gyro_degsec":[ 
             [408,-142,-435] 
         ] 
}, 
{ 
         "offset_msecs":1100, 
         "magnet_mt":[ 
           [2446,-1207,5227]
         ] 
}, 
{ 
         "offset_msecs":1150, 
         "temp_mc":[ 
             34.5 
         ] 
}, 
{ 
         "offset_msecs":1200, 
         "pressure_pa":[ 
             1045 
         ] 
}, 
{ 
         "offset_msecs":1250, 
         "gnss":[{ 
             "time_secs":"1436276052", 
             "mode":"NotSeen", 
             "speed_mps":"11", 
             "alt_m":"854", 
             "lat_deg":"42.345432", 
             "lon_deg":"25.123456", 
             "track_deg":"120", 
             "range_alt_m":"nan", 
             "range_lat_m":"nan", 
             "range_lon_m":"nan", 
             "range_track_deg":"nan" 
         }] 
}, 
{ 
         "offset_msecs":1300, 
         "heart_rate":[ 
             80 
         ] 
     } 
     ... 
] 

Example request 2:

GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags/7666a33a-6275-4549-836b-4f8d00281233/sensors?filter=gnss,accel
Accept: application/json

causes JSON array containing GNSS and accelerometer portion of action data from a file specified by it's id to be returned as a response (given that tag requested starts at 4s):

[
    {
        "offset_msecs":4000,
        "accel_mg":[
            [0.5,-0.2,1.2]
        ]
},
{
         "offset_msecs":4100,
         "gnss":[{
            "time_secs":"1436276052",
            "mode":"NotSeen",
            "speed_mps":"11",
            "alt_m":"854",
            "lat_deg":"42.345432",
            "lon_deg":"25.123456",
            "heading_deg":"120",
            "track_deg":"nan",
            "range_alt_m":"nan",
            "range_lat_m":"nan",
            "range_lon_m":"nan",
            "range_track_deg":"nan"
        }]
    }
    ...
]

You are here