Timeline

The Vehicle Timeline Service offers an overview of a vehicle's statistics, formatted as a vector with chronologically sorted data.

This information is available in two time scales (weekly and monthly) and is generated by averaging and summarizing trip details over the selected period. The same statistics are retrieved for each individual road context.

The timeline updates automatically with the analysis of each new trip.

If you have your admin API key, you can try the API via this link.

Get vehicle timeline

get

Authorizations

api-key

DriveKit-Admin-API-KeystringRequired

Path parameters

vehicleIdstringRequired

The vehicle's identifier

Query parameters

dateFormatstring · enumOptional

Date format in the response:

• timestamp: number of milliseconds since January 1, 1970, 00:00:00 GMT (e.g., 1685625600000)
• isodate: ISO 8601 date format (e.g., '2023-06-01T13:20:00.168Z')

Default: isodatePossible values:

Header parameters

DriveKit-Admin-API-KeystringRequired

Drivekit Admin API key

Responses

200

OK

application/json

401

Unauthorized

application/json

404

Vehicle or Timeline Not Found

application/json

get

/drivekit/admin/vehicles/{vehicleId}/timeline

HTTPcURLJavaScriptPython

GET /v3/drivekit/admin/vehicles/{vehicleId}/timeline HTTP/1.1
Host: service.drivequant.com
DriveKit-Admin-API-Key: text
Accept: */*

{
  "month": {
    "allContext": {
      "date": [
        "2023-06-01T12:00:00.000+0000",
        "2023-07-01T12:00:00.000+0000",
        "2024-02-01T12:00:00.000+0000",
        "2024-05-01T12:00:00.000+0000",
        "2024-09-01T12:00:00.000+0000",
        "2025-02-01T12:00:00.000+0000",
        "2026-01-01T12:00:00.000+0000",
        "2026-03-01T12:00:00.000+0000"
      ],
      "numberTrip": [
        26,
        16,
        2,
        32,
        8,
        8,
        73,
        10
      ],
      "distance": [
        43.04199999999999,
        291.63199999999995,
        2.044,
        25.156000000000002,
        7.422000000000001,
        18.052,
        715.3809999999992,
        67.23
      ],
      "duration": [
        96,
        269,
        4,
        72,
        26,
        56,
        682,
        111
      ],
      "fuelVolume": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    "roadContexts": [
      {
        "date": [
          "2023-06-01T12:00:00.000+0000",
          "2023-07-01T12:00:00.000+0000",
          "2024-02-01T12:00:00.000+0000",
          "2024-05-01T12:00:00.000+0000",
          "2024-09-01T12:00:00.000+0000",
          "2025-02-01T12:00:00.000+0000",
          "2026-01-01T12:00:00.000+0000",
          "2026-03-01T12:00:00.000+0000"
        ],
        "numberTrip": [
          18,
          2,
          0,
          12,
          6,
          2,
          4,
          0
        ],
        "distance": [
          14.026000000000002,
          5.718000000000001,
          0,
          9.855999999999998,
          4.034000000000001,
          5.248,
          8.73,
          2.16
        ],
        "duration": [
          30,
          12,
          0,
          22,
          10,
          14,
          21,
          3
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "HEAVY_URBAN_TRAFFIC"
      },
      {
        "date": [
          "2023-06-01T12:00:00.000+0000",
          "2023-07-01T12:00:00.000+0000",
          "2024-02-01T12:00:00.000+0000",
          "2024-05-01T12:00:00.000+0000",
          "2024-09-01T12:00:00.000+0000",
          "2025-02-01T12:00:00.000+0000",
          "2026-01-01T12:00:00.000+0000",
          "2026-03-01T12:00:00.000+0000"
        ],
        "numberTrip": [
          6,
          10,
          2,
          20,
          2,
          4,
          57,
          10
        ],
        "distance": [
          16.712,
          52.472,
          1.946,
          11.396000000000003,
          2.3100000000000005,
          3.8240000000000003,
          163.2690000000001,
          40.49
        ],
        "duration": [
          25,
          82,
          4,
          24,
          4,
          8,
          281,
          70
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "CITY"
      },
      {
        "date": [
          "2023-06-01T12:00:00.000+0000",
          "2023-07-01T12:00:00.000+0000",
          "2024-02-01T12:00:00.000+0000",
          "2024-05-01T12:00:00.000+0000",
          "2024-09-01T12:00:00.000+0000",
          "2025-02-01T12:00:00.000+0000",
          "2026-01-01T12:00:00.000+0000",
          "2026-03-01T12:00:00.000+0000"
        ],
        "numberTrip": [
          2,
          0,
          0,
          0,
          0,
          2,
          0,
          0
        ],
        "distance": [
          8.780000000000001,
          41.472,
          0,
          0,
          0,
          6.984,
          94.57899999999991,
          22.169999999999998
        ],
        "duration": [
          7,
          40,
          0,
          0,
          0,
          4,
          106,
          23
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "SUBURBAN"
      },
      {
        "date": [
          "2023-06-01T12:00:00.000+0000",
          "2023-07-01T12:00:00.000+0000",
          "2024-02-01T12:00:00.000+0000",
          "2024-05-01T12:00:00.000+0000",
          "2024-09-01T12:00:00.000+0000",
          "2025-02-01T12:00:00.000+0000",
          "2026-01-01T12:00:00.000+0000",
          "2026-03-01T12:00:00.000+0000"
        ],
        "numberTrip": [
          0,
          4,
          0,
          0,
          0,
          0,
          12,
          0
        ],
        "distance": [
          0,
          188.832,
          0,
          0,
          0,
          0,
          439.3919999999999,
          0
        ],
        "duration": [
          0,
          95,
          0,
          0,
          0,
          0,
          206,
          0
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "EXPRESSWAYS"
      }
    ]
  },
  "week": {
    "allContext": {
      "date": [
        "2023-06-26T12:00:00.000+0000",
        "2023-07-03T12:00:00.000+0000",
        "2024-02-05T12:00:00.000+0000",
        "2024-05-20T12:00:00.000+0000",
        "2024-09-02T12:00:00.000+0000",
        "2025-02-24T12:00:00.000+0000",
        "2026-01-12T12:00:00.000+0000",
        "2026-01-19T12:00:00.000+0000",
        "2026-01-26T12:00:00.000+0000",
        "2026-02-23T12:00:00.000+0000"
      ],
      "numberTrip": [
        36,
        6,
        2,
        32,
        8,
        8,
        12,
        9,
        52,
        10
      ],
      "distance": [
        329.17600000000004,
        5.497999999999999,
        2.044,
        25.156000000000002,
        7.422000000000001,
        18.052,
        439.3919999999999,
        31.481,
        244.50800000000004,
        67.23
      ],
      "duration": [
        351,
        14,
        4,
        72,
        26,
        56,
        204,
        61,
        414,
        111
      ],
      "fuelVolume": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    "roadContexts": [
      {
        "date": [
          "2023-06-26T12:00:00.000+0000",
          "2023-07-03T12:00:00.000+0000",
          "2024-02-05T12:00:00.000+0000",
          "2024-05-20T12:00:00.000+0000",
          "2024-09-02T12:00:00.000+0000",
          "2025-02-24T12:00:00.000+0000",
          "2026-01-12T12:00:00.000+0000",
          "2026-01-19T12:00:00.000+0000",
          "2026-01-26T12:00:00.000+0000",
          "2026-02-23T12:00:00.000+0000"
        ],
        "numberTrip": [
          18,
          2,
          0,
          12,
          6,
          2,
          0,
          4,
          0,
          0
        ],
        "distance": [
          17.684000000000005,
          2.06,
          0,
          9.855999999999998,
          4.034000000000001,
          5.248,
          0,
          4.41,
          4.320000000000002,
          2.16
        ],
        "duration": [
          39,
          3,
          0,
          22,
          10,
          14,
          0,
          11,
          10,
          3
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "HEAVY_URBAN_TRAFFIC"
      },
      {
        "date": [
          "2023-06-26T12:00:00.000+0000",
          "2023-07-03T12:00:00.000+0000",
          "2024-02-05T12:00:00.000+0000",
          "2024-05-20T12:00:00.000+0000",
          "2024-09-02T12:00:00.000+0000",
          "2025-02-24T12:00:00.000+0000",
          "2026-01-12T12:00:00.000+0000",
          "2026-01-19T12:00:00.000+0000",
          "2026-01-26T12:00:00.000+0000",
          "2026-02-23T12:00:00.000+0000"
        ],
        "numberTrip": [
          12,
          4,
          2,
          20,
          2,
          4,
          0,
          5,
          52,
          10
        ],
        "distance": [
          66.558,
          2.626,
          1.946,
          11.396000000000003,
          2.3100000000000005,
          3.8240000000000003,
          0,
          16.273000000000003,
          146.9960000000001,
          40.49
        ],
        "duration": [
          104,
          4,
          4,
          24,
          4,
          8,
          0,
          27,
          252,
          70
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "CITY"
      },
      {
        "date": [
          "2023-06-26T12:00:00.000+0000",
          "2023-07-03T12:00:00.000+0000",
          "2024-02-05T12:00:00.000+0000",
          "2024-05-20T12:00:00.000+0000",
          "2024-09-02T12:00:00.000+0000",
          "2025-02-24T12:00:00.000+0000",
          "2026-01-12T12:00:00.000+0000",
          "2026-01-19T12:00:00.000+0000",
          "2026-01-26T12:00:00.000+0000",
          "2026-02-23T12:00:00.000+0000"
        ],
        "numberTrip": [
          2,
          0,
          0,
          0,
          0,
          2,
          0,
          0,
          0,
          0
        ],
        "distance": [
          50.251999999999995,
          0,
          0,
          0,
          0,
          6.984,
          0,
          9.215,
          85.36399999999992,
          22.169999999999998
        ],
        "duration": [
          47,
          0,
          0,
          0,
          0,
          4,
          0,
          9,
          96,
          23
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "SUBURBAN"
      },
      {
        "date": [
          "2023-06-26T12:00:00.000+0000",
          "2023-07-03T12:00:00.000+0000",
          "2024-02-05T12:00:00.000+0000",
          "2024-05-20T12:00:00.000+0000",
          "2024-09-02T12:00:00.000+0000",
          "2025-02-24T12:00:00.000+0000",
          "2026-01-12T12:00:00.000+0000",
          "2026-01-19T12:00:00.000+0000",
          "2026-01-26T12:00:00.000+0000",
          "2026-02-23T12:00:00.000+0000"
        ],
        "numberTrip": [
          4,
          0,
          0,
          0,
          0,
          0,
          12,
          0,
          0,
          0
        ],
        "distance": [
          188.832,
          0,
          0,
          0,
          0,
          0,
          439.3919999999999,
          0,
          0,
          0
        ],
        "duration": [
          95,
          0,
          0,
          0,
          0,
          0,
          206,
          0,
          0,
          0
        ],
        "fuelVolume": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0
        ],
        "roadContext": "EXPRESSWAYS"
      }
    ]
  }
}

Note

Use the dateFormat query parameter to control the format of the date fields in the response. Accepted values are:

• timestamp : returns dates as a 64-bit integer representing the number of milliseconds elapsed since the Unix epoch (January 1, 1970, 00:00:00 UTC). Example: 1685625600000

• isodate : returns dates as a string conforming to the ISO 8601 standard. Example: 2023-06-01T13:20:00.168Z

If the dateFormat parameter is not specified, the response defaults to isodate format.

Response

The table below summarizes the list of timeline data.

Field	Type	Description
month	Timeline	Monthly statistics
week	Timeline	Weekly statistics

Timeline

The table below summarizes the content of a timeline object.

Field	Type	Description
allContext	GlobalTimelineItemVehicle	Average statistics for all contexts
roadContext	array[object]	Average statistics for each context (see TimelineItemVehicle)

GlobalTimelineItemVehicle

The table below summarizes the content of a globalTimelineItemVehicle object.

Field	Type	Description
date	array[string]	First date of the period Default date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
numberTrip	array[integer]	Number of trips during the period
distance	array[number]	Distance driven during the period (in km)
distanceLoss	array[number]	Estimated loss distance during the period at the beginning of the trips (in km). Requires the route start completion feature to be enabled.
duration	array[number]	Trip duration during the period (in min)
fuelVolume	array[number]	Amount of fuel used during the period (in L)
fuelConsumption	array[number]	Fuel consumption during the period (in L/100km)
co2	array[number]	Consumption during the period (in gCO2/km)
co2Opti	array[number]	Optimal consumption during the period (in gCO2/km)
energyKWh	array[number]	Energy during the period (in kWh)
energyKWhOpti	array[number]	Optimal Energy during the period (in kWh)
energyConsumption	array[number]	Energy consumption during the period (in kWh/100km)
energyOptiConsumption	array[number]	Optimal Energy during the period (in kWh/100km)

TimelineItemVehicle

The table below summarizes the content of a timelineItemVehicle object.

Field	Type	Description
date	array[string]	First date of the period Default date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
roadContext	array[string]	Type of RoadContext. Allowed values: HEAVY_URBAN_TRAFFIC, CITY, SUBURBAN, EXPRESSWAYS
numberTrip	array[integer]	Number of trips for which this road context was the major one
distance	array[number]	Distance driven in this context (in km)
distanceLoss	array[number]	Estimated loss distance during the period at the beginning of the trips (in km). Requires the route start completion feature to be enabled.
duration	array[number]	Trip duration in this context (in min)
fuelVolume	array[number]	Amount of fuel used in this context (in L)
fuelConsumption	array[number]	Fuel consumption in this context (in L/100km)
co2	array[number]	Consumption in this context (in gCO2/km)
co2Opti	array[number]	Optimal consumption in this context (in gCO2/km)
energyKWh	array[number]	Energy in this context (in kWh)
energyKWhOpti	array[number]	Optimal Energy in this context (in kWh)
energyConsumption	array[number]	Energy consumption in this context (in kWh/100km)
energyOptiConsumption	array[number]	Optimal Energy in this context (in kWh/100km)

RoadContext

Road contexts are calculated from the GPS velocity. They are not based on map data.

Value	Description
HEAVY_URBAN_TRAFFIC	Speed below 30 km/h and distance between two stops greater than 100m
CITY	30 km/h < Speed < 65 km/h
SUBURBAN	65 km/h < Speed < 96 km/h
EXPRESSWAYS	Speed > 96 km/h