Trips API⚓︎
The Trips API is part of the INVERS Events API. It provides information about the movement of vehicles in your fleet.
Trip⚓︎
A trip describes a connected vehicle’s movement from a start position to an end position. It contains information about where and when the movement began and stopped as well as aggregated metrics based on data recorded during this timespan.
Trigger⚓︎
There are three options to trigger a trip.
Driving Enabled (default)⚓︎
When the DRIVING_ENABLED property changes from false to true, a trip is started and a TripStarted event generated. When DRIVING_ENABLED switches to false again, the trip is ended and a TripEnded event generated. If the duration between those events is less than one minute, the trip is considered too short to be plausible and discarded. Vehicles require the DRIVING_ENABLED-capability.
Ignition⚓︎
When the IGNITION property changes from OFF to ON, a trip is started and a TripStarted event generated. When IGNITION switches to OFF again, the trip is ended and a TripEnded event generated. If the duration between those events is less than one minute, the trip is considered too short to be plausible and discarded. Vehicles require the IGNITION-capability.
Rental Status⚓︎
When the RENTAL_STATUS property changes from NOT_IN_RENTAL to IN_RENTAL, a trip is started and a TripStarted event generated. When RENTAL_STATUS switches to NOT_IN_RENTAL again, the trip is ended and a TripEnded event generated. This trigger requires integration of the Vehicle Management API.
Lifecycle⚓︎
sequenceDiagram
Vehicle->>Trips API: Trip Start Trigger
Trips API-->>Event: TripStarted
loop Trip
Vehicle->>Vehicle: Driving continuing
end
Vehicle->>Trips API: Trip End Trigger
Trips API-->>Event: TripEnded
Trips API->>Trips API: Metrics calculation
Trips API-->>Event: TripMetricsReady / TripDiscardedTripMetricsReady and TripDiscarded⚓︎
When a trip is finished and the TripEnded event has been generated, the trip’s metrics are calculated. When this step succeeds, a TripMetricsReady event is created to indicate that this trip is complete and contains all data. If the trip duration is less than one minute, the trip is discarded and a TripDiscarded event sent.
Metrics⚓︎
Trip metrics are calculated after a trip is finished and sent in the TripMetricsReady event. If you would like to know exactly which metrics can be stored, check out the API specifications in the box on the top right or the example of a TripMetricsReady event below.
Example
This example shows what TripMetricsReady events can look like.
{
"metadata": {
"id": "01F1FHJ7SHQK5MGF69B8K2346E",
"type": "TripMetricsReady",
"schema_major_version": 2,
"occurred_at": "2022-01-30T13:22:05.321Z",
"flow_id": "804f2161-a15c-420f-8f21-61a15c320f68"
},
"data": {
"occurred_at": "2020-01-30T13:22:05.321Z",
"vehicle_id": "JQ7RP",
"trip": {
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"key": "H5XAV",
"is_flagged": false,
"data_completion_status": "FINISHED",
"trigger": "DRIVING_ENABLED",
"start": {
"timestamp": "2020-10-08T10:29:00.321Z",
"position": {
"timestamp": "2021-03-08T10:29:00.321Z",
"value": {
"lat": 50.123,
"lon": 7.321
}
}
},
"metrics": {
"speeding_events": 2,
"maximum_speeding_in_kilometers_per_hour": 10.4,
"driving_analysis_events": 5,
"telematics_unit_turned_on_events": 1,
"telematics_unit_turned_off_events": 1,
"telematics_unit_power_supply_failed_events": 1,
"crash_detected_events": 3,
"crash_detected_events_per_kilometer": 0.35,
"harsh_cornering_started_events": 1,
"harsh_cornering_started_events_per_kilometer": 0.12,
"heavy_braking_started_events": 2,
"heavy_braking_started_events_per_kilometer": 0.22,
"state_of_charge_or_fuel_level_below_threshold_events": 3,
"telematics_unit_supply_voltage_below_threshold_events": 2,
"duration_in_seconds": 1800,
"time_since_last_trip_in_seconds": 14400,
"distance_in_kilometers": 23.4,
"state_of_charge_or_fuel_level_at_trip_start_in_percent": 35,
"state_of_charge_or_fuel_level_at_trip_end_in_percent": 42,
"doors_status_at_trip_end": "OPEN",
"windows_status_at_trip_end": "OPEN"
},
"end": {
"timestamp": "2020-10-08T10:29:00.321Z",
"position": {
"timestamp": "2021-03-08T10:29:00.321Z",
"value": {
"lat": 50.123,
"lon": 7.321
}
}
}
}
}
}