The API and Raw Data
Accessing Raw Telemetries
Raw Data Export
To satisfy advanced use-cases, Vianova's API provides access to raw, unaggregated fleet data through the /zones/<zone_id>/events endpoint.
The events endpoint returns a time-ordered series of events across all devices in the city's fleet. Each event record contains the following fields:
- event_time: timestamp of the event
- position: [longitude, latitude]of the device
- device_type: type of the device (e.g. “bicycle”, “scooter”)
- device_state: state of the device (e.g. “available”, “non_operational”)
- event_type: type of the event (e.g. “user_pick_up”, “low_battery”)
- provider: API link to the provider (e.g. /providers/<provider_id>)
- provider_device_id: external id of the device, unique per provider
- next_position, next_event_time, next_device_state, next_event_type: Subsequent event produced by the device
- trip_trajectory: the full-resolution telemetry of the event's trip in GeoJSON format, null if not a trip-event
Several of these fields correspond to the GBFS and MDS standards (e.g., device_type, device_state, event_type,...), which can be found respectively
By default, all events from the requested time-range are returned. To select specific events, you can review the API documentation on events. As an example, and to get started playing with mobility data quickly using Python, the user could take some inspiration from our tutorial.
POST Body examples
Retrieve events in July 2021 without telemetries
{
"subfleet": {
"start_time": "2021-07-01T08:21:13.972Z",
"end_time": "2021-07-31T23:21:13.972Z"
},
"distinct_devices": false,
"include_telemetries": false
}
Retrieve events for the past week with telemetries
{
"subfleet": {
"start_time_from_now": "week"
},
"distinct_devices": false,
"include_telemetries": true
}
Retrieve events for scooters of provider 20 on Mondays between 9pm and 10 pm with event_type user_pick_up.
{
"subfleet": {
"start_time": "2021-08-05T16:21:13.972Z",
"end_time": "2021-08-15T16:21:13.972Z",
"device_types": ["scooter"],
"providers": ["/providers/20"],
"days_of_week": [1],
"hours_of_day": [21],
"event_types": ["user_pick_up"]
},
"distinct_devices": false,
"include_telemetries": false
}
Full Curl example
curl -X 'POST' \
'https://api.vianova.dev/zones/YOUR_ZONE/events/' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"subfleet": {
"start_time": "2021-08-05T16:21:13.972Z",
"end_time": "2021-08-15T16:21:13.972Z",
"device_types": ["scooter"],
"providers": ["/providers/PROVIDER_ID"],
"days_of_week": [1],
"hours_of_day": [21],
"event_types": ["user_pick_up"]
},
"distinct_devices": false,
"include_telemetries": false
}'
Known limitations
Quality
The number of telemetries for the route depends on the operator choice or implementation to let Vianova access the full route, please have a look on our other article https://support.vianova.io/en/articles/5154219-telemetry-quality
GDPR
Trip trajectories can only be retrieved for events occurring within the last 10 days to remain GDPR-compliant and are available minimum at the end of each hour for privacy reasons.
We are also protecting trip start and end position to not disclose individual location that could potentially lead to personal address by applying a 50 meters privacy buffer to strip telemetries.
Important considerations
Timestamps from the API are provided in ISO Format, with Timezone information included
Updated almost 3 years ago