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