Get /vehicles/{vehicleId}/streams
Return a collection of consecutive images or a video from a specified vehicle at specified time.
Syntax
/vehicles/{vehicleId}/streams?time={date}&limit={integer}&offset={integer}&realtime={boolean}&format={string}&password={string}
URL Parameters
| Name | Type | Description |
|---|---|---|
| vehicleId | string |
The unique identifier of a vehicle.
Note: Streams can only be returned when a Drive is currently online. |
Query Parameters
| Name | Type | Description |
|---|---|---|
| time | date | A historical time in UTC. To retrieve a stream successfully, time must match the time returned in GET /drives. |
| limit | integer |
Optional. The stream length in seconds to return, up to a maximum of 10 for MJPEG streams, or 60 for MPEG-TS streams.
Note: the number of seconds returned may be less than the number of seconds in the Drive if the vehicle speed falls to 10kph or lower partway through the Drive. Note: setting limit to less than the maximum value will not significantly reduce the time to retrieve a stream. |
| offset | integer |
Optional. The offset in seconds from the start of the stream to begin the returned stream.
Note: If the vehicle speed falls to 10kph or lower partway through a Drive, the Drive is truncated, and the maximum possible value for offset will reduce accordingly. |
| realtime | boolean |
Optional. If set to true, streams will be returned at the correct framerate.
If set to false, streams will be downloaded as fast as possible, and framerate information will be lost. Defaults to true.
Note: MPEG-TS streams do not currently support realtime=false. |
| format | string |
Optional. Either “mjpeg” or “mpeg-ts”.
Note: Drive streams may not be available in all formats. |
| password | string | Unique password supplied to you previously. |
Return Value
Type: multipart/x-mixed-replace
When the stream is in MJPEG format, each image is in JPEG format and will contain EXIF data as follows.
| Name | Type | Description |
|---|---|---|
| DateTimeOriginal (Tag 0x9003) | date | The time that image was taken, in UTC. |
| GPSLatitude (Tag 0x0002 under IFD 0x8825) | double | Longitude of the vehicle when the image was taken. |
| GPSLongitude (Tag 0x0004 under IFD 0x8825) | double | Longitude of the vehicle when the image was taken. |
| GPSSpeed (Tag 0x000d under IFD 0x8825) | integer | Speed of the vehicle when the image was taken, in kph. |
| GPSImgDirection (Tag 0x0011 under IFD 0x8825) | integer | Heading of the vehicle when the image was taken, in degrees. Heading is expressed as a value greater or equal than 0 and less than 360 measured clockwise from north. i.e., 0 is north, 90 is east, 180 is south, 270 is west. |
Drive stream images are stored directly on the vehicle. This endpoint can fail if:
- the vehicle goes offline (immediate HTTP error 400, “Vehicle is not online” or delayed HTTP error 500, “Vehicle is offline”). To minimize offline vehicle errors, only request drive streams from drive data that was retrieved within the last 15 minutes. Retry once GET /drives reports the drive is online again.
- the vehicle loses a good cellular connection (delayed HTTP error 500, “Could not retrieve image stream”). Retry once GET /drives reports the drive is online again.
- the vehicle loses a good GPS connection (delayed HTTP error 500, "Bad or missing GPS data"). Retries will also fail.
- the vehicle recycles storage space to store newer drive streams (delayed HTTP error 500, "Image stream not found").
- the offset is greater than the length of the Drive (immediate HTTP error 400, “Offset exceeds the length of Drive").
- the vehicle is too busy with other requests (immediate HTTP error 503, “Vehicle is busy"). Retry after a few minutes.
The API will try to retrieve a drive stream from the vehicle for up to 5 minutes. Concurrent requests will not be released in the API until the full 5 minutes has passed, even if the Drive stream request timeout in your application is less than 5 minutes.
Any request which exceeds the concurrent request limit will produce an immediate HTTP 429 ("Too many requests") error. Note that an API request for a 10 second stream in MJPEG format counts as 10 concurrent requests. An API request for a 10 second stream in MPEG-TS format counts as 1 concurrent request.
Example
| Request |
|---|
| https://www.vizzion.com/api/vehicles/12345/streams?time=2022-07-23T15:33:03Z&limit=10&offset=0&password=<password> |
| Response |
|---|
... --boundary Content-Type: image/jpeg Content-Length: 271437 |
EXIF:
DateTimeOriginal 2022:07:23 15:33:03
GPSLatitude 43.761971
GPSLongitude 79.392647
GPSSpeed 104
GPSImgDirection 70
--boundary
Content-Type: image/jpeg
Content-Length: 272192
EXIF:
DateTimeOriginal 2022:07:23 15:33:04
GPSLatitude 43.762058
GPSLongitude 79.392311
GPSSpeed 104
GPSImgDirection 71
--boundary
Content-Type: image/jpeg
Content-Length: 271100
EXIF:
DateTimeOriginal 2022:07:23 15:33:05
GPSLatitude 43.762138
GPSLongitude 79.391968
GPSSpeed 105
GPSImgDirection 72
--boundary
Content-Type: image/jpeg
Content-Length: 272011
EXIF:
DateTimeOriginal 2022:07:23 15:33:06
GPSLatitude 43.762218
GPSLongitude 79.391632
GPSSpeed 105
GPSImgDirection 72
--boundary
Content-Type: image/jpeg
Content-Length: 270986
EXIF:
DateTimeOriginal 2022:07:23 15:33:07
GPSLatitude 43.762291
GPSLongitude 79.391281
GPSSpeed 104
GPSImgDirection 73
--boundary
Content-Type: image/jpeg
Content-Length: 271084
EXIF:
DateTimeOriginal 2022:07:23 15:33:08
GPSLatitude 43.762371
GPSLongitude 79.390938
GPSSpeed 104
GPSImgDirection 73
--boundary
Content-Type: image/jpeg
Content-Length: 269812
EXIF:
DateTimeOriginal 2022:07:23 15:33:09
GPSLatitude 43.76244
GPSLongitude 79.390587
GPSSpeed 104
GPSImgDirection 74
--boundary
Content-Type: image/jpeg
Content-Length: 270043
EXIF:
DateTimeOriginal 2022:07:23 15:33:10
GPSLatitude 43.76252
GPSLongitude 79.390251
GPSSpeed 104
GPSImgDirection 74
--boundary
Content-Type: image/jpeg
Content-Length: 271656
EXIF:
DateTimeOriginal 2022:07:23 15:33:11
GPSLatitude 43.762589
GPSLongitude 79.3899
GPSSpeed 104
GPSImgDirection 74
--boundary
Content-Type: image/jpeg
Content-Length: 271090
EXIF:
DateTimeOriginal 2022:07:23 15:33:12
GPSLatitude 43.762661
GPSLongitude 79.389557
GPSSpeed 104
GPSImgDirection 74
| Request |
|---|
| https://www.vizzion.com/api/vehicles/54321/streams?time=2022-09-21T09:12:34Z&limit=20&offset=0&format=mpeg-ts&password=<password> |
| Response |
|---|
|
|
