Trips API

Insights API

API Reference

API Changelog

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