# Timeline

The Driver Timeline Service offers an overview of a driver's score history and related 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 scores and summarizing trip details over the selected period. 

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/847bcca5b766a-get-driver-timeline).
{% endhint %}

## Timeline of driver's scores

<mark style="color:blue;">`GET`</mark> `https://service.drivequant.com/v3/drivekit/admin/drivers/{userId}/timeline`

Get monthly and weekly averages of DriveQuant scores for a specified driver:

#### Path Parameters

| Name   | Type   | Description                |
| ------ | ------ | -------------------------- |
| userId | string | Driver's unique identifier |

#### Headers

| Name                   | Type   | Description   |
| ---------------------- | ------ | ------------- |
| DriveKit-Admin-API-Key | string | Admin API Key |

{% tabs %}
{% tab title="200 " %}
{% code fullWidth="false" expandable="true" %}

```json
{
  "month": {
    "allContext": {
      "date": [
        1680350400000
      ],
      "numberTripScored": [
        15
      ],
      "numberTripTotal": [
        21
      ],
      "distance": [
        318.70099999999996
      ],
      "duration": [
        382
      ],
      "efficiency": [
        8.259999999999998
      ],
      "safety": [
        9.026666666666666
      ],
      "acceleration": [
        5
      ],
      "braking": [
        45
      ],
      "adherence": [
        14
      ],
      "co2Mass": [
        47.962410999999996
      ],
      "fuelVolume": [
        20.673453017241382
      ],
      "efficiencyAcceleration": [
        -1.3599999999999997
      ],
      "efficiencyBrake": [
        -0.33999999999999997
      ],
      "efficiencySpeedMaintain": [
        0.8
      ],
      "phoneDistraction": [
        6.949583402655184
      ],
      "speeding": [
        6.893809523809523
      ],
      "unlock": [
        43
      ],
      "lock": [
        46
      ],
      "callAuthorized": [
        0
      ],
      "callForbidden": [
        2
      ],
      "callAuthorizedDuration": [
        0
      ],
      "callForbiddenDuration": [
        888
      ],
      "numberTripWithForbiddenCall": [
        1
      ],
      "speedingDistance": [
        22981
      ],
      "speedingDuration": [
        939
      ],
      "tripCategory": [
        [
          6,
          7,
          6,
          2,
          0
        ]
      ],
      "tripCategoryDistance": [
        [
          4.132,
          46.333,
          85.149,
          183.087,
          0
        ]
      ],
      "weather": [
        [
          0,
          10,
          10,
          0,
          1,
          0,
          0
        ]
      ],
      "weatherDistance": [
        [
          0,
          63.721,
          240.348,
          0,
          14.632,
          0,
          0
        ]
      ],
      "dayDistance": [
        262.143
      ],
      "weekDayDistance": [
        86.47699999999999
      ]
    },
    "roadContexts": [
      {
        "date": [
          1680350400000
        ],
        "numberTripScored": [
          0
        ],
        "numberTripTotal": [
          1
        ],
        "distance": [
          4.7589999999999995
        ],
        "duration": [
          8
        ],
        "efficiency": [
          0
        ],
        "safety": [
          0
        ],
        "acceleration": [
          0
        ],
        "braking": [
          0
        ],
        "adherence": [
          1
        ],
        "co2Mass": [
          0.856937
        ],
        "fuelVolume": [
          0.3693693965517241
        ],
        "efficiencyAcceleration": [
          0
        ],
        "efficiencyBrake": [
          0
        ],
        "efficiencySpeedMaintain": [
          0
        ],
        "roadContext": "HEAVY_URBAN_TRAFFIC"
      },
      {
        "date": [
          1680350400000
        ],
        "numberTripScored": [
          5
        ],
        "numberTripTotal": [
          10
        ],
        "distance": [
          66.637
        ],
        "duration": [
          109
        ],
        "efficiency": [
          7.4799999999999995
        ],
        "safety": [
          8.539999999999997
        ],
        "acceleration": [
          3
        ],
        "braking": [
          35
        ],
        "adherence": [
          8
        ],
        "co2Mass": [
          10.166557
        ],
        "fuelVolume": [
          4.382136637931034
        ],
        "efficiencyAcceleration": [
          -2.4
        ],
        "efficiencyBrake": [
          0.4571428571428572
        ],
        "efficiencySpeedMaintain": [
          0.5428571428571429
        ],
        "roadContext": "CITY"
      },
      {
        "date": [
          1680350400000
        ],
        "numberTripScored": [
          6
        ],
        "numberTripTotal": [
          6
        ],
        "distance": [
          99.348
        ],
        "duration": [
          81
        ],
        "efficiency": [
          8.55
        ],
        "safety": [
          9.266666666666667
        ],
        "acceleration": [
          2
        ],
        "braking": [
          7
        ],
        "adherence": [
          5
        ],
        "co2Mass": [
          13.166667
        ],
        "fuelVolume": [
          5.6752875
        ],
        "efficiencyAcceleration": [
          -1.1600000000000001
        ],
        "efficiencyBrake": [
          0.26
        ],
        "efficiencySpeedMaintain": [
          0.76
        ],
        "roadContext": "SUBURBAN"
      },
      {
        "date": [
          1680350400000
        ],
        "numberTripScored": [
          4
        ],
        "numberTripTotal": [
          4
        ],
        "distance": [
          139.94
        ],
        "duration": [
          81
        ],
        "efficiency": [
          9.2
        ],
        "safety": [
          9.925
        ],
        "acceleration": [
          0
        ],
        "braking": [
          3
        ],
        "adherence": [
          0
        ],
        "co2Mass": [
          21.970996999999997
        ],
        "fuelVolume": [
          9.470257327586209
        ],
        "efficiencyAcceleration": [
          -1.15
        ],
        "efficiencyBrake": [
          0.125
        ],
        "efficiencySpeedMaintain": [
          1.175
        ],
        "roadContext": "EXPRESSWAYS"
      }
    ]
  },
  "week": {
    "allContext": {
      "date": [
        1680523200000,
        1681128000000,
        1681732800000
      ],
      "numberTripScored": [
        8,
        6,
        1
      ],
      "numberTripTotal": [
        11,
        6,
        4
      ],
      "distance": [
        73.182,
        225.71399999999997,
        19.805
      ],
      "duration": [
        138,
        225,
        19
      ],
      "efficiency": [
        8.100000000000001,
        8.416666666666668,
        8.6
      ],
      "safety": [
        8.8375,
        9.133333333333335,
        9.9
      ],
      "acceleration": [
        3,
        1,
        1
      ],
      "braking": [
        17,
        27,
        1
      ],
      "adherence": [
        5,
        7,
        2
      ],
      "co2Mass": [
        10.776477,
        34.293447,
        2.8924869999999996
      ],
      "fuelVolume": [
        4.645033189655173,
        14.781658189655172,
        1.2467616379310344
      ],
      "efficiencyAcceleration": [
        -1.6199999999999999,
        -1.2333333333333334,
        -0.8999999999999999
      ],
      "efficiencyBrake": [
        0.11000000000000003,
        -0.5166666666666667,
        -1.2
      ],
      "efficiencySpeedMaintain": [
        0.64,
        1.0666666666666667,
        0.7999999999999999
      ],
      "phoneDistraction": [
        7.488176687810716,
        5.4330047686564,
        7.743319819475644
      ],
      "speeding": [
        7.6909090909090905,
        6.623333333333334,
        5.1075
      ],
      "unlock": [
        12,
        30,
        1
      ],
      "lock": [
        15,
        29,
        2
      ],
      "callAuthorized": [
        0,
        0,
        0
      ],
      "callForbidden": [
        0,
        2,
        0
      ],
      "callAuthorizedDuration": [
        0,
        0,
        0
      ],
      "callForbiddenDuration": [
        0,
        888,
        0
      ],
      "numberTripWithForbiddenCall": [
        0,
        1,
        0
      ],
      "speedingDistance": [
        3173,
        14816,
        4992
      ],
      "speedingDuration": [
        181,
        539,
        219
      ],
      "tripCategory": [
        [
          3,
          5,
          3,
          0,
          0
        ],
        [
          0,
          2,
          2,
          2,
          0
        ],
        [
          3,
          0,
          1,
          0,
          0
        ]
      ],
      "tripCategoryDistance": [
        [
          2.9979999999999998,
          34.281,
          35.903000000000006,
          0,
          0
        ],
        [
          0,
          12.052,
          30.575,
          183.087,
          0
        ],
        [
          1.134,
          0,
          18.671,
          0,
          0
        ]
      ],
      "weather": [
        [
          0,
          4,
          7,
          0,
          0,
          0,
          0
        ],
        [
          0,
          2,
          3,
          0,
          1,
          0,
          0
        ],
        [
          0,
          4,
          0,
          0,
          0,
          0,
          0
        ]
      ],
      "weatherDistance": [
        [
          0,
          31.863999999999997,
          41.318,
          0,
          0,
          0,
          0
        ],
        [
          0,
          12.052,
          199.03,
          0,
          14.632,
          0,
          0
        ],
        [
          0,
          19.805,
          0,
          0,
          0,
          0,
          0
        ]
      ],
      "dayDistance": [
        35.565,
        225.71399999999997,
        0.864
      ],
      "weekDayDistance": [
        36.097,
        30.575,
        19.805
      ]
    },
    "roadContexts": [
      {
        "date": [
          1680523200000,
          1681128000000,
          1681732800000
        ],
        "numberTripScored": [
          0,
          0,
          0
        ],
        "numberTripTotal": [
          1,
          0,
          0
        ],
        "distance": [
          2.99,
          1.626,
          0.143
        ],
        "duration": [
          5,
          3,
          0
        ],
        "efficiency": [
          0,
          0,
          0
        ],
        "safety": [
          0,
          0,
          0
        ],
        "acceleration": [
          0,
          0,
          0
        ],
        "braking": [
          0,
          0,
          0
        ],
        "adherence": [
          1,
          0,
          0
        ],
        "co2Mass": [
          0.52567,
          0.30138,
          0.029886999999999997
        ],
        "fuelVolume": [
          0.22658189655172412,
          0.1299051724137931,
          0.012882327586206894
        ],
        "efficiencyAcceleration": [
          0,
          0,
          0
        ],
        "efficiencyBrake": [
          0,
          0,
          0
        ],
        "efficiencySpeedMaintain": [
          0,
          0,
          0
        ],
        "roadContext": "HEAVY_URBAN_TRAFFIC"
      },
      {
        "date": [
          1680523200000,
          1681128000000,
          1681732800000
        ],
        "numberTripScored": [
          3,
          2,
          0
        ],
        "numberTripTotal": [
          5,
          2,
          3
        ],
        "distance": [
          26.372,
          37.969,
          2.296
        ],
        "duration": [
          46,
          61,
          2
        ],
        "efficiency": [
          7.233333333333333,
          7.85,
          0
        ],
        "safety": [
          8.233333333333333,
          9,
          0
        ],
        "acceleration": [
          2,
          0,
          1
        ],
        "braking": [
          15,
          19,
          1
        ],
        "adherence": [
          3,
          3,
          2
        ],
        "co2Mass": [
          4.126842,
          5.643057,
          0.396658
        ],
        "fuelVolume": [
          1.778811206896552,
          2.432352155172414,
          0.170973275862069
        ],
        "efficiencyAcceleration": [
          -2.08,
          -1.4,
          -5
        ],
        "efficiencyBrake": [
          -0.03999999999999998,
          -1.6,
          5
        ],
        "efficiencySpeedMaintain": [
          0.5199999999999999,
          0.6,
          0.6
        ],
        "roadContext": "CITY"
      },
      {
        "date": [
          1680523200000,
          1681128000000,
          1681732800000
        ],
        "numberTripScored": [
          5,
          1,
          0
        ],
        "numberTripTotal": [
          5,
          1,
          0
        ],
        "distance": [
          35.495999999999995,
          57.397,
          6.455
        ],
        "duration": [
          29,
          47,
          5
        ],
        "efficiency": [
          8.74,
          7.6,
          0
        ],
        "safety": [
          9.6,
          7.6,
          0
        ],
        "acceleration": [
          1,
          1,
          0
        ],
        "braking": [
          2,
          5,
          0
        ],
        "adherence": [
          1,
          4,
          0
        ],
        "co2Mass": [
          4.689247,
          7.605994999999999,
          0.8714250000000001
        ],
        "fuelVolume": [
          2.021227155172414,
          3.278446120689655,
          0.3756142241379311
        ],
        "efficiencyAcceleration": [
          -1.1600000000000001,
          0,
          0
        ],
        "efficiencyBrake": [
          0.26,
          0,
          0
        ],
        "efficiencySpeedMaintain": [
          0.76,
          0,
          0
        ],
        "roadContext": "SUBURBAN"
      },
      {
        "date": [
          1680523200000,
          1681128000000,
          1681732800000
        ],
        "numberTripScored": [
          0,
          3,
          1
        ],
        "numberTripTotal": [
          0,
          3,
          1
        ],
        "distance": [
          4.088,
          125.428,
          10.424
        ],
        "duration": [
          2,
          73,
          6
        ],
        "efficiency": [
          0,
          9.266666666666666,
          9
        ],
        "safety": [
          0,
          9.9,
          10
        ],
        "acceleration": [
          0,
          0,
          0
        ],
        "braking": [
          0,
          3,
          0
        ],
        "adherence": [
          0,
          0,
          0
        ],
        "co2Mass": [
          0.489416,
          19.980525,
          1.5010559999999997
        ],
        "fuelVolume": [
          0.21095517241379314,
          8.61229525862069,
          0.647006896551724
        ],
        "efficiencyAcceleration": [
          0,
          -1.2,
          -1
        ],
        "efficiencyBrake": [
          0,
          0.10000000000000002,
          0.2
        ],
        "efficiencySpeedMaintain": [
          0,
          1.1666666666666667,
          1.2
        ],
        "roadContext": "EXPRESSWAYS"
      }
    ]
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="401 " %}

```
Unauthorized
```

{% endtab %}

{% tab title="404 " %}

```
User Not Found
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}

## Note&#x20;

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 `timestamp` format.
{% endhint %}

## Response

The table below summarizes the list of timeline data.

<table><thead><tr><th width="137.66666666666666">Field</th><th width="209">Type</th><th>Description</th></tr></thead><tbody><tr><td>month</td><td><a href="#timeline">Timeline</a></td><td>Monthly averages of scores</td></tr><tr><td>week</td><td><a href="#timeline">Timeline</a></td><td>Weekly averages of scores</td></tr></tbody></table>

### Timeline

Averages of scores for all context and each road context.

<table><thead><tr><th width="159.33333333333331">Field</th><th width="167">Type</th><th>Description</th></tr></thead><tbody><tr><td>allContext</td><td><a href="#alltimelineitem">AllTimelineItem</a></td><td>Averages of scores for all contexts</td></tr><tr><td>roadContext</td><td><code>array[object]</code></td><td>Averages of scores for each context <em>(see</em> <a href="#roadtimelineitem"><em>RoadTimelineItem</em></a><em>)</em></td></tr></tbody></table>

### AllTimelineItem

Average of scores for all contexts

<table><thead><tr><th width="250.2735182088026">Field</th><th width="176.21484375">Type </th><th>Description</th></tr></thead><tbody><tr><td>date</td><td><code>array[date]</code></td><td><p>Vector of dates (first day of the period)</p><p><em>Default date format: unix timestamp</em></p></td></tr><tr><td>numberTripScored</td><td><code>array[int]</code></td><td>Vector of trips number (scored)</td></tr><tr><td>numberTripTotal</td><td><code>array[int]</code></td><td>Vector of trips number (total)</td></tr><tr><td>distance</td><td><code>array[double]</code></td><td>Vector of driving distances (in km)</td></tr><tr><td>duration</td><td><code>array[double]</code></td><td>Vector of driving durations (in min)</td></tr><tr><td>safety</td><td><code>array[double]</code></td><td>Vector of average safety scores</td></tr><tr><td>acceleration</td><td><code>array[int]</code></td><td>Vector of total hard accelerations</td></tr><tr><td>braking</td><td><code>array[int]</code></td><td>Vector of total hard brakings</td></tr><tr><td>adherence</td><td><code>array[int]</code></td><td>Vector of total adherence limits</td></tr><tr><td>efficiency</td><td><code>array[double]</code></td><td>Vector of average ecodriving scores</td></tr><tr><td>co2Mass</td><td><code>array[double]</code></td><td>Vector of total CO2 mass (in kg)</td></tr><tr><td>fuelVolume</td><td><code>array[double]</code></td><td>Vector of total fuel volume (in l)</td></tr><tr><td>efficiencyAcceleration</td><td><code>array[double]</code></td><td>Vector of efficiency subscores related to acceleration phase</td></tr><tr><td>efficiencyBrake</td><td><code>array[double]</code></td><td>Vector of efficiency subscores related to brake phases</td></tr><tr><td>efficiencySpeedMaintain</td><td><code>array[double]</code></td><td>Vector of efficiency subscores related to speed maintain phases</td></tr><tr><td>phoneDistraction</td><td><code>array[double]</code></td><td>Vector of average phone distraction scores</td></tr><tr><td>unlock</td><td><code>array[int]</code></td><td>Vector of tot unlocks <em>- only for allContext</em></td></tr><tr><td>lock</td><td><code>array[int]</code></td><td>Vector of total locks <em>- only for allContext</em></td></tr><tr><td>callAuthorized</td><td><code>array[int]</code></td><td>Vector of total authorized calls <em>- only for allContext</em></td></tr><tr><td>callForbidden</td><td><code>array[int]</code></td><td>Vector of total unauthorized calls <em>- only for allContext</em></td></tr><tr><td>callAuthorizedDuration</td><td><code>array[int]</code></td><td>Vector of authorized calls duration (in sec) <em>- only for allContext</em></td></tr><tr><td>callForbiddenDuration</td><td><code>array[int]</code></td><td>Vector of unauthorized calls duration (in sec) <em>- only for allContext</em></td></tr><tr><td>numberTripWithForbiddenCall</td><td><code>array[int]</code></td><td>Vector of number of trips with one or more forbidden call</td></tr><tr><td>speeding</td><td><code>array[double]</code></td><td>Vector of average speeding scores</td></tr><tr><td>speedingDuration</td><td><code>array[double]</code></td><td>Vector of duration over speed limits</td></tr><tr><td>speedingDistance</td><td><code>array[double]</code></td><td>Vector of distance travelled over speed limits</td></tr><tr><td>tripCategory</td><td><code>array[array[int]]</code></td><td><a href="#tripcategory">TripCategory</a></td></tr><tr><td>tripCategoryDistance</td><td><code>array[array[int]]</code></td><td><a href="#tripcategory">TripCategory</a></td></tr><tr><td>weather</td><td><code>array[array[int]]</code></td><td><a href="#weather">Weather</a></td></tr><tr><td>weatherDistance</td><td><code>array[array[int]]</code></td><td><a href="#weather">Weather</a></td></tr><tr><td>dayDistance</td><td><code>array[double]</code></td><td>Distance travelled during the daylight</td></tr><tr><td>weekDayDistance</td><td><code>array[double]</code></td><td>Distance travelled during week days (monday to friday)</td></tr></tbody></table>

### RoadTimelineItem

Average of scores for each contexts

<table><thead><tr><th width="238.6250807088026">Field</th><th width="169">Type </th><th>Description</th></tr></thead><tbody><tr><td>roadContext</td><td><code>string</code></td><td>Road context <em>(see</em> <a href="#roadcontext"><em>below</em></a><em>)</em></td></tr><tr><td>date</td><td><code>array[date]</code></td><td><p>Vector of dates (first day of the period)</p><p><em>Default date format: unix timestamp</em></p></td></tr><tr><td>numberTripScored</td><td><code>array[int]</code></td><td>Vector of trips number (scored)</td></tr><tr><td>numberTripTotal</td><td><code>array[int]</code></td><td>Vector of trips number (total)</td></tr><tr><td>distance</td><td><code>array[double]</code></td><td>Vector of driving distances (in km)</td></tr><tr><td>duration</td><td><code>array[double]</code></td><td>Vector of driving durations (in min)</td></tr><tr><td>safety</td><td><code>array[double]</code></td><td>Vector of average safety scores</td></tr><tr><td>acceleration</td><td><code>array[int]</code></td><td>Vector of total hard accelerations</td></tr><tr><td>braking</td><td><code>array[int]</code></td><td>Vector of total hard brakings</td></tr><tr><td>adherence</td><td><code>array[int]</code></td><td>Vector of total adherence limits</td></tr><tr><td>efficiency</td><td><code>array[double]</code></td><td>Vector of average ecodriving scores</td></tr><tr><td>co2Mass</td><td><code>array[double]</code></td><td>Vector of total CO2 mass (in kg)</td></tr><tr><td>fuelVolume</td><td><code>array[double]</code></td><td>Vector of total fuel volume (in l)</td></tr><tr><td>efficiencyAcceleration</td><td><code>array[double]</code></td><td>Vector of efficiency subscore related to acceleration phas</td></tr><tr><td>efficiencyBrake</td><td><code>array[double]</code></td><td>Vector of efficiency subscore related to brake phases</td></tr><tr><td>efficiencySpeedMaintain</td><td><code>array[double]</code></td><td>Vector of efficiency subscore related to speed maintain phases</td></tr></tbody></table>

### RoadContext

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

<table><thead><tr><th width="242">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>HEAVY_URBAN_TRAFFIC</code></td><td>Speed below 30 km/h and distance between two stops greater than 100m</td></tr><tr><td><code>CITY</code></td><td>30 km/h &#x3C; Speed &#x3C; 65 km/h</td></tr><tr><td><code>SUBURBAN</code></td><td>65 km/h &#x3C; Speed &#x3C; 96 km/h</td></tr><tr><td><code>EXPRESSWAYS</code></td><td>Speed > 96 km/h</td></tr></tbody></table>

### TripCategory

Category of trips by distance

<table><thead><tr><th width="205">Index</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>Less than 2 km</td></tr><tr><td>1</td><td>From 2 to 10 km</td></tr><tr><td>2</td><td>From 10 to 50 km</td></tr><tr><td>3</td><td>From 50 to 100 km</td></tr><tr><td>4</td><td>More than 100 km</td></tr></tbody></table>

### Weather

Type of weather

<table><thead><tr><th width="204">Index</th><th>Description</th></tr></thead><tbody><tr><td>0</td><td>Unknown</td></tr><tr><td>1</td><td>Sunny</td></tr><tr><td>2</td><td>Cloudy</td></tr><tr><td>3</td><td>Foggy</td></tr><tr><td>4</td><td>Rainy</td></tr><tr><td>5</td><td>Snowy </td></tr><tr><td>6</td><td>Ice</td></tr></tbody></table>


---

# 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/driver/timeline-of-scores.md?ask=<question>
```

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.