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