Get /drives
Returns a collection of Drives matching a specified query, ordered by ascending date and time.
Syntax
/drives?after={date}&before={date}&limit={integer}&offset={integer}&box={float[]}&polygon={float[]}&linestring={float[]}&online={boolean}&minimumImageHeight={int}&password={string}
Parameters
| Name | Type | Description |
|---|---|---|
| after | date |
Optional. Restricts Drives to those collected after the given time in UTC.
Note: Timespans of a day or more can take several minutes to return. Consider using a shorter timespan and making additional calls for other timespans if the desired data is not found. Note: Drives data is currently removed from Vizzion’s API no later than 10 days after creation. |
| before | date |
Optional. Restricts Drives to those collected before the given time in UTC.
Note:Drives are added to the database at the time when the Drive ends, but are queried based on the time when the drive starts. A real-time application that queries Drives that started in the last 5 minutes, and performs the same query at 5 minute intervals, will miss Drives that were still in progress at each 5 minute interval. |
| limit | integer | Optional. The number of Drives to return per page, up to a maximum of 10,000. |
| offset | integer |
Optional. The offset of the first Drive in the collection to return, used to return additional pages of drives when the number of drives exceeds the “limit” parameter.
Note: queries will be slower as offset increases. To retrieve the same data faster, use shorter timespans with a zero offset. |
| box | float[] |
In this example, only the Drives inside the blue box will be returned
Note: only one geometry parameter is permitted per call. Note: if images are needed for a specific location, ensure the box is large enough to include the start or end of the drive that may pass through that location. In extreme cases, a drive may start or end 1,000 meters from the desired location. |
| polygon | float[] |
A list of comma-separated latitude/longitude coordinates of a simple polygon (non-self-intersecting) in parentheses delimited by commas,
ordered in the clockwise or counter-clockwise direction. Each coordinate must be unique within the list,
and therefore the last coordinate should not be the same as the first.
Coordinates must not be collinear, whereby 3 or more consecutive coordinates lie on a single straight line. 3 coordinates are collinear if: p1.X * (p2.Y — p3.Y) + p2.X * (p3.Y — p1.Y) + p3.X * (p1.Y — p2.Y) = 0 (±0.0000001) The required minimum number of coordinates is 3, and the maximum is 1,000. If intending to use 2 coordinates, see the linestring filter below. Note: only one geometry parameter is permitted per call. Note: While the method allows up to 1,000 coordinates, the maximum number that can be listed in a URL query string in a browser is limited. |
| linestring | float[] |
In this example, only the Drives within 10 meters of the blue route will be returned
Note: only one geometry parameter is permitted per call. Note: While the method allows up to 1,000 coordinates, the maximum number that can be listed in a URL query string in a browser is limited. |
| online | boolean |
Optional. If set to true, restricts drives to those from vehicles that have been online within the last 5 minutes. If set to |
| minimumImageHeight | int | Optional. Restricts Drives to those collected by vehicle cameras with at least the given height, for example 720 pixels high or 1080 pixels high. |
| password | string | Unique password supplied to you previously. |
Return Value
Type: GeoJSON FeatureCollection
The FeatureCollection is made up of features. Each feature represents a single Drive and contains a "geometry" and "properties" member.
The “geometry” member is a multipoint object containing two or more pairs of coordinates, which represent the start locations, intermediate locations (if available), and end locations of the Drive.
Note: Coordinate pairs are ordered with longitude first, followed by latitude, in accordance with the official GeoJSON specification.
Note: Intermediate locations will always be available after retrieving the drive stream.
The “properties” member of the returned GeoJSON will include:
| Name | Type | Description |
|---|---|---|
| VehicleId | integer | Unique vehicle identifier. |
| Waypoints | string, integer, integer | The time, speed, and heading for intermediate locations. One waypoint is provided for each intermediate location. |
| Time | string |
The time that the Drive was collected in UTC.
Note: Drives will be returned in date/time order, beginning with the first available Drive from the specified timespan. |
| Online | boolean |
True if the vehicle was online within the last 5 minutes.
Note: Image streams can only be returned when the vehicle is online. |
| Seconds | integer | The duration of the Drive. Also, the maximum number of images available for the Drive. |
| Speed | integer | Speed of the vehicle at the start of the Drive, in kph |
| Heading | integer | Heading of the vehicle at the start of the Drive, 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. |
Example
| Request (Box) |
|---|
| https://www.vizzion.com/api/drives?after=2022-01-26T00:00:00Z&before=2022-01-26T01:00:00Z&limit=2&offset=0&box=-123.070165,49.262025,-123.056176,49.27686&password=<password> |
| Request (Linestring) |
|---|
| https://www.vizzion.com/api/drives?after=2022-01-26T00:00:00Z&before=2022-01-26T01:00:00Z&limit=2&offset=0&linestring=(23.3413,-124.56),(23.3675,-124.56)&password=<password> |
| Response |
|---|
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "MultiPoint",
"coordinates": [
[
-123.06955,
49.27184
],
[
-123.06946,
49.27304
]
]
},
"properties": {
"VehicleId": 1234567,
"Time": "2022-01-26T14:51:18.000Z",
"Online": false,
"Seconds": 15,
"Speed": 41,
"Heading": 1
}
},
{
"type": "Feature",
"geometry": {
"type": "MultiPoint",
"coordinates": [
[
-123.06805,
49.27307
],
[
-123.06794,
49.27377
],
[
-123.06783,
49.27367
],
[
-123.06772,
49.27357
],
[
-123.06761,
49.27347
]
]
},
"properties": {
"VehicleId": 1234567,
"Time": "2022-01-26T16:26:45.000Z",
"Online": false,
"Seconds": 5,
"Speed": 20,
"Heading": 88,
"Waypoints": [
{
"Time": "2022-01-26T16:26:46.000Z",
"Speed": 21,
"Heading": 89
},
{
"Time": "2022-01-26T16:26:47.000Z",
"Speed": 22,
"Heading": 90
},
{
"Time": "2022-01-26T16:26:48.000Z",
"Speed": 23,
"Heading": 91
},
{
"Time": "2022-01-26T16:26:49.000Z",
"Speed": 24,
"Heading": 92
}
]
}
}
]
}
|