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 IGNITION
-capability. 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.
Note
When not using the OneAPI but instead integrating directly with the CloudBoxx API, trips may be triggered based on IMMOBILIZER LOCKED
and IMMOBILIZER UNLOCKED
events.
Lifecycle⚓︎
sequenceDiagram
Vehicle->>Trips API: Ignition On
Trips API-->>Event: TripStarted
loop Trip
Vehicle->>Vehicle: Driving continuing
end
Vehicle->>Trips API: Ignition Off
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"
}
}
}
}