Knowledge Center
Roadmap

The events endpoint

How to get raw individual data from device events

Suggest Edits

Why events ?

On the Vianova API, you have basically 2 major endpoints which are /metrics and /events

Metrics are for hourly aggregated statistics that Vianova computes at the top of each hour.

In this article we will cover the Events endpoint, that gives individual, located and timestamped informations. We have 3 main categories of events that we will cover article so you can get the most out of it.

Events endpoint

The events endpoint is a generic endpoint which can serve multiple purposes, based on the parameters that are sent :

  • Realtime events
  • Historical events
  • Historical infringements

We listed the main API requests parameters for each use case :

  • Subfleet
  • Include_infringements
  • Distinct_devices
  • Include_telemetries
  • Use_cached

Each parameter, according to the use case, will follow the RFC convention to describe the requirement level of the param

  • MUST = It must be set up in the context of this use case
  • MUST NOT = It must not be set up in the context of this use case
  • MAY = Not mandatory to use, but is an option that will change the end result
  • SHOULD NOT = Can be set, but will have no impact on the result, useless to set

We have listed the default limits for each use case, and if they’re tweaked by some params :

  • Limit (How many rows returned in the response)
  • Time limit (Until when can we request the data)
  • Freshness (How fresh is the data)

We also put an example of the response payload for each use case of the events endpoint.

Use case 1 - Realtime data :

This part will describe how to get the latest know vehicle position and status, it's closely coupled to the concept of search horizon described here

  • API parameters :

    • Subfleet : MUST NOT be used
      • If set, it will automatically be historical data and not realtime anymore (see use case below)
    • Include_infrigements : MAY be used
      • Will include a list of regulations that the device is infringing
    • Distinct_devices: SHOULD NOT be used
    • Include_telemetries : SHOULD NOT be used
    • Use_cached: SHOULD NOT be used

  • Default limits :

    • Limit : 2k rows
    • Time limit : 7 days
      • Can be 14 days, but it’s up to customers to request it
    • Freshness : 1 minute old

  • Response structure : 

{
   "position" : {
       "lat":0.0,
       "lng":0.0
   },
   "device_type": "string",
   "event_time": "string",
   "device_state": "string",
   "event_type": "string",
   "provider": "string", // provider url
   "provider_device_id": "string",
   "infringements" : [
       "string" // regulation url that made occur the infringement
   ]
}

Use case 2 - Historical events :

This part will describe how to get historical data, include trips trajectory. We only provide a limited timeframe with blurred start and stop for privacy reasons. You can follow our recipe with code exemple here

  • API parameters :

    • Subfleet : MUST be used
      • If not set, it will fetch realtime events (see above)
      • Subfleet.regulations : MUST NOT be used
        • If set, will fetch historical infringements (see below)
    • Include_infrigements : SHOULD NOT be used
    • Distinct_devices: MAY be used
      • If set :
        • It’ll fetch only one event per device (the most recent event for the device)
        • Limit : 15k rows
    • Include_telemetries : MAY be used
      • If set :
        • Returns the trips event times and trip trajectories
        • Time limit : 10 days max, not available before
    • Use_cached: MAY be used
      • If set :
        • Uses cached data
        • Freshness : 1 hour old data

  • Default limits :

    • Limit : 2k
    • Time limit : As long as you’ve data ingested in the scope
    • Freshness : 1 minute old

  • Response structure 

{
   "position" : {
       "lat":0.0,
       "lng":0.0
   },
   "device_type": "string",
   "event_time": "string",
   "device_state": "string",
   "event_type": "string",
   "provider": "string", // provider url
   "provider_device_id": "string",
   "trip_trajectory": {} // if include telemetries
}

Use case 3 - Historical infringements :

This part will describe who you can get historical raw infringement from the event based policies (you can read this article to understand more about the difference)

  • API parameters :

    • Subfleet : MUST be used, otherwise it’ll fetch realtime events (see below)
      • Subfleet.regulations : MUST be used, otherwise it’ll fetch historical events, and not historical infringements
      • Subfleet.regulations.unique_infringements : MAY be used
        • If set : Only unique infringements => If an infringement happens for 12 hours, there will be only one infringement, instead of having 12 distinct infringements in the list (one per hour)
    • Include_infrigements : SHOULD NOT be used
    • Distinct_devices: SHOULD NOT be used
    • Include_telemetries : SHOULD NOT be used
    • Use_cached: SHOULD NOT be used

  • Default limits :

    • Limit : 15k
    • Time limit : As long as you’ve data ingested in the scope
    • Freshness : 1 minute old

  • Response structure 

{
   "position" : {
       "lat":0.0,
       "lng":0.0
   },
   "regulation": "string", //Url of the regulation
   "device_type": "string",
   "event_time": "string",
   "next_event_time": "string", // Only for unique infringements => Matches the end of the infringement
   "provider": "string", // provider url
   "provider_device_id": "string",
}

👍

Avoiding the limits

Our recommendation when you hit the maximum number of items is to either reduce the query timeline (asking less days) or reduce the area (focusing on custom zone or subdistrict)

Updated almost 2 years ago