Sensor data
Used to retrieve action data from recorded files.
Table of contents
- GET /api/<versionNumber>/videos/<video_id>/sensors
- GET /api/<versionNumber>/videos/<video_id>/tags/<tag_id>/sensors
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" }] } ... ]