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

Tags

Used to access, post and manipulate tags in video files. Tags cannot be shorter than 1s and can be as long as the whole video.

Table of contents

More information on how tag/highlight structure looks like and how it's stored into MP4 container can be found here.

GET /api/<versionNumber>/videos/<video_id>/tags

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags

Example:

http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags

Parameters:

Parameter Description Req'd? Type / Values
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

Description:

Returns JSON array of objects containing all tags from requested MP4 file identified by it's id:

Parameter Description Type
id Unique id of a tag. string, max. 36 characters
offset_secs Offset from beginning of a video marking moment in time when highlight occurred. float
highlight_offset_secs Offset from beginning of a video marking tag start. float
highlight_length_secs  Length of a tag. float
delivered_offset_secs Offset from beginning of a video from where actual highlight can be delivered. float
delivered_length_secs Length of a highlight that can be delivered. float

Apart from that, response can also contain one of the following attributes:

Parameter Description Type
tag_button When true, means that tagging by pressing the button on the camera occurred. 'False' will be ignored. boolean
tag_mobile When true, means that tagging by pressing the button in the mobile application occurred. 'False' will be ignored. boolean
tag_remote When true, means that tagging by pressing the button on the remote occurred. 'False' will be ignored. boolean
max_speed_mps Max. speed detected (in m/h). float
max_heartrate_bpm Max. heart rate detected (in beats per minute). integer
max_acceleration Max. resulting acceleration (over 3 axis) detected. float
max_deceleration Max. resulting deceleration (over 3 axis) detected. float
max_vertical_speed_mps Max. vertical speed detected, could be positive or negative (in m/s). float
max_g_force Max. resulting G-force detected (in mG). float
max_rotation Max. resulting rotation detected (in deg/s). integer

Response codes:

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

Example request:

GET http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags

and example response:

[ 
     { 
         "id":"7666a33a-6275-4549-836b-4f8d00281233", 
         "offset_secs":8.2, 
         "highlight_offset_secs":3.2, 
         "highlight_length_secs":13.2, 
         "delivered_offset_secs":3.0, 
         "delivered_length_secs":13.4, 
         "max_speed":15.5 
     }, 
     { 
         "id":"09615314-eb75-4813-b36e-aed6b4aa12bc", 
         "offset_secs":15.5, 
         "highlight_offset_secs":10.5, 
         "highlight_length_secs":17.5, 
         "delivered_offset_secs":10.0, 
         "delivered_length_secs":18.0, 
         "tag_button":true 
     } 
] 

 

POST /api/<versionNumber>/record/tag

Format:

http://<baseURL>/api/<versionNumber>/record/tag

Example:

http://192.168.1.101/api/2/record/tag

Parameters

Parameter Description Req'd? Type / Values
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

JSON Parameters:

Parameter in request body is a JSON object containing one of the fields described in GET /api/<versionNumber>/videos/<video_id>/tags under 'Description'.

Description:

Inserts tag into video which is currently being recorded. 

Response codes:

 

Code Description
200 OK
400 Bad Request (video is not being recorded at the moment, can't tag because max. number of tags is reached...)
500 Server Error (request can't be processed)

Example request:

POST http://192.168.1.101/api/2/record/tag

Parameters:

{
    "tag_mobile":true
}

 

POST /api/<versionNumber>/videos/<video_id>/tags

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags

Example:

http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags

Parameters

Parameter Description Req'd? Type / Values
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

JSON Parameters:

Parameters in request body are defined as array of JSON objects. The first attribute in every object will be one of the fields described in GET /api/<versionNumber>/videos/<video_id>/tags under 'Description'.

Remaining attributes will be:

Parameter Description Req'd? Type
offset_secs Float value defining time (as offset from beginning of a video) at which tag was detected/occurred.
Example value: 8.2
Yes float
highlight_offset_secs Offset from beginning of a video, expressed as float, marking beginning of highlight
Example value: 3.6
Yes float
highlight_length_secs Duration of a highlight, expressed as float
Example value: 10.7
Yes float

Description:

Inserts tags into video specified by it's file_hash and returns it's UUID(s) in the same order in which tags were sent. Video application will calculate id for each tag before it's stored into MP4 container of the video file.

Response will contain JSON array of objects containing generated tag ids.

Response codes:

 

Code Description
200 OK
400 Bad Request (offset/length out of range)
404 Not Found (file with requested id not found)
500 Server Error (request can't be processed)

Example request:

POST http://192.168.1.101/api/2/videos/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags

Parameters:

[ 
     { 
         "tag_button":true, 
         "offset_secs":8.2, 
         "highlight_offset_secs":3.2, 
         "highlight_length_secs":13.2 
     }, 
     { 
         "max_speed":123.5, 
         "offset_secs":15.5, 
         "highlight_offset_secs":10.5, 
         "highlight_length_secs":17.5 
     } 
] 

and example response:

[ 
     { 
         "id":"7666a33a-6275-4549-836b-4f8d00281233", 
         "delivered_offset_secs":3.0, 
         "delivered_length_secs":13.4 
     }, 
     { 
         "id":"09615314-eb75-4813-b36e-aed6b4aa12bc", 
         "delivered_offset_secs":10.0, 
         "delivered_length_secs":18.0 
     } 
] 

 

DELETE /api/<versionNumber>/videos/<video_id>/tags

Format:

http://<baseURL>/api/<versionNumber>/video/<video_id>/tags

Example:

http://192.168.1.101/api/2/video/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags

Parameters:

Parameter Description Req'd? Type / Values
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

Description:

Deletes all tags from video specified by it's id.

Response codes:

 

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

Example request:

DELETE http://192.168.1.101/api/2/video/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags

 

GET /api/<versionNumber>/videos/<video_id>/tags/<tag_id>

Format:

http://<baseURL>/api/<versionNumber>/video/<video_id>/tags/<tag_id>

Example:

http://192.168.1.101/api/2/video/1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags/92836a33a-2345-8949-a66b-bcedaa289586-100-111-2241

Parameters:

Parameter Description Req'd? Type / Values
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

Description:

Returns JSON object containing specific tag data (identified by tag_id) from requested MP4 file identified by it's id.

For response format, take a look at GET /api/<versionNumber>/videos/<video_id>/tags.

Response codes:

 

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

Example request:

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

and example response:

{ 
     "id":"7666a33a-6275-4549-836b-4f8d00281233", 
     "offset_secs":8.2, 
     "highlight_offset_secs":3.2, 
     "highlight_length_secs":13.2, 
     "delivered_offset_secs":3.0, 
     "delivered_length_secs":13.4, 
     "tag_button":true 
} 

 

PUT /api/<versionNumber>/videos/<video_id>/tags/<tag_id>

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags/<tag_id>

Example:

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

Parameters

Parameter Description Req'd? Type / Values
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

JSON Parameters:

Parameters in request body are defined as JSON object. The first attribute in this object will be one of the fields described in GET /api/<versionNumber>/videos/<video_id>/tags under 'Description'.

Remaining attributes will be:

Parameter Description Req'd? Type
offset_secs Float value defining time (as offset from beginning of a video) at which tag was detected/occurred.
Example value: 8.2
Yes float
highlight_offset_secs Offset from beginning of a video, expressed as float, marking beginning of highlight
Example value: 3.6
Yes float
highlight_length_secs Duration of a highlight, expressed as float
Example value: 10.7
Yes float

Response is a JSON object containing following attributes:

Parameter Description Req'd? Type
delivered_offset_secs Float value defining time (as offset from beginning of a video) from which tag was will be delivered.
Example value: 8.2
Yes float
delivered_length_secs Duration of the highlight that will be delivered from the camera.
Example value: 3.6
Yes float

Description:

Updates specified tag (identified by it's tag_id) in the video specified by it's id. 

Response codes:

 

Code Description
200 OK
400 Bad Request (length of the updated highlight is bigger than maximum allowed size)
404 Not Found (video with requested video_id not found or tag with specified tag_id was not found)
500 Server Error (request can't be processed)

Example request:

PUT http://192.168.1.101/api/2/videos/<span class="nolink">1236a33a-5375-4549-836b-d4ed00289586-100-000-0001/tags/</span>7666a33a-6275-4549-836b-4f8d00281233

Parameters:

{ 
     "offset_secs":8.2, 
     "highlight_offset_secs":3.2, 
     "highlight_length_secs":13.2, 
     "max_speed":87.5 
}

and example response:

{
    "delivered_offset_secs":3.0,
    "delivered_length_secs":13.4
}

 

DELETE /api/<versionNumber>/videos/<video_id>/tags/<tag_id>

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags/<tag_id>

Example:

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

Parameters:

Parameter Description Req'd? Type / Values
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

Description:

Deletes specified tag (identified by it's tag_id) from video specified by it's video_id.

Response codes:

 

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

Example request:

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

 

GET /api/<versionNumber>/videos/<video_id>/tags/<tag_id>/thumb

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags/<tag_id>/thumb

Example:

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

Parameters:

Parameter Description Req'd? Type / Values
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

Description:

Returns thumbnail (in JPEG format) for tag (identified by tag_id) from requested MP4 file identified by it's video_id. Thumbnail is taken at the exact time when tag was registered.

Content-type: image/jpeg

Response codes:

 

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

Example request:

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

causes JPEG picture representing selected thumbnail to be sent as a response.

Content-type field in HTTP header of a response will be set to image/jpeg.

GET /api/<versionNumber>/videos/<video_id>/tags/<tag_id>/contents[?resolution=<resolution>&framerate=<framerate>]

Format:

http://<baseURL>/api/<versionNumber>/videos/<video_id>/tags/<tag_id>/contents[?resolution=<resolution>][&framerate=<framerate>]

Example:

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

Parameters:

If query string parameters are omitted this API call will return MP4 video, as it was recorded, which corresponds to tag identified by tag_id parameter. Otherwise, if query string parameters are specified and valid, MP4 tag video will be delivered with requested resolution and framerate.

Note that, if query parameters are present, both query parameters should be defined. Defining only one parameter will cause camera to return error status code.

Possible values for 'resolution' parameter are '4k', '2.7k', '1080p', '720p' and 'wvga'. For 'framerate' it's '180fps', '120fps', '60fps', '30fps' and '15fps'.  To get a matrix of possible options for any given video resolution/framerate, take a look at response of GET /api/<versionNumber>/capabilities/transcoding method.

Description:

Returns MP4 video for tag (identified by tag_id) from requested MP4 file identified by it's video_id. File is send as form data and content type will be set to video/mp4.

Client can request tag video in different resolution and framerate. If different resolution and framerate than origin ones are selected, camera will have to perform transcoding before delivering that video so response will take longer time to finish. Not every resolution and framerate can be selected and client should first check for valid options, depending on a resolution and framerate of original file/tag. This list can be obtained by calling the GET /api/<versionNumber>/capabilities method (look at 'transcoder' section).

NOTE: Since exact time at which tag occurred (offset_secs), start (highlight_offset_secs) and it's length (highlight_length_secs) are all defined as float values and, at the moment, camera is not able to cut on sub-second intervals, video delivered with this API will be cut on seconds interval, start offset rounded down (floor) and end offset rounded up (ceil).

IMPORTANT: If tag requested is in different resolution/framerate than original video, tag will be transcoded on the camera into requested resolution/framerate. During that time, only Status API will be accessible and 'transcoding_progress' backchannel message will be sent periodically to the client, informing it about current progress of the transcoding. In case tag requested is in the same resolution/framerate as original video, delivered tag will be just a trimmed portion of original video and no transcoding will take place.

Another constraint is that it's only possible to download one tag at a time, parallel downloads are not supported.

Response codes:

 

Code Description
200 OK
400 Bad Request (resolution and framerate parameters are not set correctly or only one of those parameters is defined)
404 Not Found (video with requested video_id not found or tag with specified tag_id was 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/contents

causes MP4 file representing selected tag to be send to the client as form data.

Content-type will be set to video/mp4.

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/contents?resolution=1080p&amp;framerate=30fps

causes MP4 file representing selected tag to be first transcoded to requested resolution and framerate and then send to the client as form data.

Content-type will be set to video/mp4.

You are here