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 also 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",
}