# 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. {% hint style="info" %} If you have your **admin API key**, you can try the API via this[ **link**](https://drivequant.stoplight.io/docs/drivequant-public/6ab221a5bc452-get-vehicle-timeline). {% endhint %} ## GET /drivekit/admin/vehicles/{vehicleId}/timeline > Get vehicle timeline ```json {"openapi":"3.0.3","info":{"title":"DKAdminVehiclesV3","version":"1.0"},"servers":[{"url":"https://service.drivequant.com/v3","description":"Prod"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"name":"DriveKit-Admin-API-Key","type":"apiKey","in":"header"}},"schemas":{"TimelineVehicle":{"title":"TimelineVehicle","type":"object","properties":{"month":{"$ref":"#/components/schemas/TimelineVehicleLists"},"week":{"$ref":"#/components/schemas/TimelineVehicleLists"}}},"TimelineVehicleLists":{"title":"TimelineVehicleLists","type":"object","properties":{"allContext":{"$ref":"#/components/schemas/TimelineVehicleItem"},"roadContexts":{"type":"array","items":{"$ref":"#/components/schemas/RoadTimelineVehicleItem"}}}},"TimelineVehicleItem":{"title":"TimelineVehicleItem","type":"object","properties":{"date":{"type":"array","description":"First day of the timeline period","items":{"type":"string","format":"date-time"}},"numberTrip":{"type":"array","description":"Total number of trips","items":{"type":"integer","minimum":0}},"distance":{"type":"array","description":"Total distance (in km)","items":{"type":"number","minimum":0}},"duration":{"type":"array","description":"Total duration (in min)","items":{"type":"integer","minimum":0}},"fuelVolume":{"type":"array","description":"Total fuel volume (in L)","items":{"type":"number","minimum":0}}}},"RoadTimelineVehicleItem":{"title":"RoadTimelineVehicleItem","type":"object","allOf":[{"$ref":"#/components/schemas/TimelineVehicleItem"},{"type":"object","properties":{"roadContext":{"type":"string","description":"Road context","enum":["HEAVY_URBAN_TRAFFIC","CITY","SUBURBAN","EXPRESSWAYS"]}}}]},"ErrorResponse":{"title":"ErrorResponse","type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"},"messageKey":{"type":"string"}}}}},"paths":{"/drivekit/admin/vehicles/{vehicleId}/timeline":{"get":{"summary":"Get vehicle timeline","tags":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimelineVehicle"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Vehicle or Timeline Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"operationId":"get-drivekit-admin-vehicles-vehicleId-timeline","parameters":[{"schema":{"type":"string"},"in":"header","name":"DriveKit-Admin-API-Key","description":"Drivekit Admin API key","required":true}],"description":""}}}} ``` {% hint style="info" %} ## 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. {% endhint %} ## Response The table below summarizes the list of timeline data. | Field | Type | Description | | ----- | --------------------- | ------------------ | | month | [Timeline](#timeline) | Monthly statistics | | week | [Timeline](#timeline) | Weekly statistics | ### Timeline The table below summarizes the content of a timeline object.
FieldTypeDescription
allContextGlobalTimelineItemVehicleAverage statistics for all contexts
roadContextarray[object]Average statistics for each context (see TimelineItemVehicle)
### GlobalTimelineItemVehicle The table below summarizes the content of a globalTimelineItemVehicle object.
FieldTypeDescription
datearray[string]First date of the period
Default date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
numberTriparray[integer]Number of trips during the period
distancearray[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.

durationarray[number]Trip duration during the period (in min)
fuelVolumearray[number]Amount of fuel used during the period (in L)
fuelConsumptionarray[number]Fuel consumption during the period (in L/100km)
co2array[number]Consumption during the period (in gCO2/km)
co2Optiarray[number]Optimal consumption during the period (in gCO2/km)
energyKWharray[number]Energy during the period (in kWh)
energyKWhOptiarray[number]Optimal Energy during the period (in kWh)
energyConsumptionarray[number]Energy consumption during the period (in kWh/100km)
energyOptiConsumptionarray[number]Optimal Energy during the period (in kWh/100km)
### TimelineItemVehicle The table below summarizes the content of a timelineItemVehicle object.
FieldTypeDescription
datearray[string]First date of the period
Default date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
roadContextarray[string]

Type of RoadContext.

Allowed values: HEAVY_URBAN_TRAFFIC, CITY, SUBURBAN, EXPRESSWAYS

numberTriparray[integer]Number of trips for which this road context was the major one
distancearray[number]Distance driven in this context (in km)
distanceLossarray[number]

Estimated loss distance during the period at the beginning of the trips (in km).

Requires the route start completion feature to be enabled.

durationarray[number]Trip duration in this context (in min)
fuelVolumearray[number]Amount of fuel used in this context (in L)
fuelConsumptionarray[number]Fuel consumption in this context (in L/100km)
co2array[number]Consumption in this context (in gCO2/km)
co2Optiarray[number]Optimal consumption in this context (in gCO2/km)
energyKWharray[number]Energy in this context (in kWh)
energyKWhOptiarray[number]Optimal Energy in this context (in kWh)
energyConsumptionarray[number]Energy consumption in this context (in kWh/100km)
energyOptiConsumptionarray[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.
ValueDescription
HEAVY_URBAN_TRAFFICSpeed below 30 km/h and distance between two stops greater than 100m
CITY30 km/h < Speed < 65 km/h
SUBURBAN65 km/h < Speed < 96 km/h
EXPRESSWAYSSpeed > 96 km/h
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.drivequant.com/backend/vehicle/timeline.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.