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

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

{% endtab %}

{% tab title="401 " %}

```
Unauthorized
```

{% endtab %}

{% tab title="404 " %}

```
User Not Found
```

{% endtab %}
{% endtabs %}

## 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="282.6250807088026">Field</th><th width="226">Type </th><th>Description</th></tr></thead><tbody><tr><td>date</td><td><code>array[date]</code></td><td>Vector of dates (first day of the week/month): date format (YYYY-MM-dd’T’HH:mm:ss.SSSZ)</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>Vector of dates (first day of the week/month): date format (YYYY-MM-dd’T’HH:mm:ss.SSSZ)</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>