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⚓︎
Trips can only be recognized on vehicles with the DRIVING_ENABLED
-capability. 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.
Note
When not using the OneAPI but instead integrating directly with the CloudBoxx API, trips are triggered based on IMMOBILIZER LOCKED
and IMMOBILIZER UNLOCKED
events which are the equivalent to the DRIVING_ENABLED
changes in the OneAPI.
Lifecycle⚓︎
sequenceDiagram
Vehicle->>Trips API: DrivingEnabled true
Trips API-->>Event: TripStarted
loop Trip
Vehicle->>Vehicle: Driving continuing
end
Vehicle->>Trips API: DrivingEnabled false
Trips API-->>Event: TripEnded
Trips API->>Trips API: Metrics calculation
Trips API-->>Event: TripDataReady / TripDiscarded
TripDataReady 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 TripDataReady
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 TripDataReady
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 TripDataReady
event below.
Example
This example shows what TripDataReady
events can look like.
{
"metadata": {
"id": "01F1FHJ7SHQK5MGF69B8K2346E",
"type": "TripDataReady",
"schema_major_version": 1,
"occurred_at": "2022-01-30T13:22:05Z",
"flow_id": "804f2161-a15c-420f-8f21-61a15c320f68"
},
"data": {
"occurred_at": "2020-01-30T13:22:05Z",
"trip": {
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"key": "H5XAV",
"is_flagged": false,
"data_completion_status": "FINISHED",
"vehicle_id": "JQ7RP",
"telematics_unit": {
"id": "2A2440843B02F704",
"brand": "CLOUDBOXX"
},
"start": {
"timestamp": "2020-10-08T10:29:00Z",
"position": {
"timestamp": "2021-03-08T10:29:00Z",
"value": {
"lat": 50.123,
"lon": 7.321
}
}
},
"end": {
"timestamp": "2020-10-08T10:29:00Z",
"position": {
"timestamp": "2021-03-08T10:29:00Z",
"value": {
"lat": 50.123,
"lon": 7.321
}
}
},
"metrics": {
"duration_in_ms": 65432,
"time_since_last_trip_in_ms": 7654321,
"distance_in_km": 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": "CLOSED",
"windows_status_at_trip_end": "CLOSED"
}
}
}
}