# References (Android)

## DKDriverTimeline

`DKDriverTimeline` is an object that contains timeline data for the given period.

```kotlin
data class DKDriverTimeline(
    val period: DKPeriod,
    val allContext: List<DKAllContextItem>,
    val roadContexts: Map<RoadContext, List<DKRoadContextItem>>
) : Serializable
```

<table data-header-hidden><thead><tr><th>Attribute</th><th width="255.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Description</td></tr><tr><td>period</td><td><a href="#dkperiod">DKPeriod</a></td><td>The kind of aggregation period for this timeline</td></tr><tr><td>allContext</td><td>List&#x3C;<a href="#dkallcontextitem">DKAllContextItem</a>></td><td>The list of all global context sorted by date</td></tr><tr><td>roadContexts</td><td>Map&#x3C;<a href="#roadcontext">RoadContext</a>, List&#x3C;<a href="#dkroadcontextitem">DKRoadContextItem</a>>></td><td>The map of all road context and their associated list of context data sorted by date</td></tr></tbody></table>

## DKPeriod

`DKPeriod` indicates the aggregation size of each timeline object. It is an enum with the following values:

| WEEK  | Timeline data is aggregated week by week   |
| ----- | ------------------------------------------ |
| MONTH | Timeline data is aggregated month by month |
| YEAR  | Timeline data is aggregated year by year   |

```kotlin
enum class DKPeriod: Serializable {
    WEEK, MONTH, YEAR
}
```

## DKAllContextItem

`DKAllContextItem` is an object that contains data for global context for the given period.

```kotlin
data class DKAllContextItem(
        override val date: Date,
        val numberTripScored: Int,
        val numberTripTotal: Int,
        val distance: Double,
        val duration: Int,
        val safety: DKSafety?,
        val ecoDriving: DKEcoDriving?,
        val phoneDistraction: DKDistraction?,
        val speeding: DKSpeeding?,
        val drivingConditions: DKDrivingConditions?
) : Serializable, DatedContextItem
```

<table data-header-hidden><thead><tr><th width="223.33333333333331">Attribute</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Attribute</td><td>Type</td><td>Description</td></tr><tr><td>date</td><td>Date</td><td>Start date of the given period</td></tr><tr><td>numberTripTotal</td><td>Int</td><td>Total number of trips made during the given period</td></tr><tr><td>numberTripScored</td><td>Int</td><td>Number of trips made that were long enough to have a score during the given period</td></tr><tr><td>distance</td><td>Double</td><td>Total distance travelled during the given period (in kilometers)</td></tr><tr><td>duration</td><td>Int</td><td>Total trip duration during the given period (in minutes)</td></tr><tr><td>safety</td><td><a href="#dksafety">DKSafety</a>?</td><td>Safety's score and sub scores for the given period (present only if safety score is configured and the period has some scored trips)</td></tr><tr><td>ecoDriving</td><td><a href="#dkecodriving">DKEcoDriving</a>?</td><td>Eco-driving's score and sub scores for the given period (present only if eco-driving score is configured and the period has some scored trips)</td></tr><tr><td>phoneDistraction</td><td><a href="#dkdistraction">DKDistraction</a>?</td><td>Distraction's score and sub scores for the given period (present only if distraction score is configured)</td></tr><tr><td>speeding</td><td><a href="#dkspeeding">DKSpeeding</a>?</td><td>Speeding's score and sub scores for the given period (present only if speeding score is configured)</td></tr><tr><td>drivingConditions</td><td><a href="#dkdrivingconditions">DKDrivingConditions</a>?</td><td>Advanced informations for a given period (total trip and distance for a specific DKDrivingCategory and by DKWeather, distance travelled by day/night and by weekdays/weekend)</td></tr></tbody></table>

## DKSafety

`DKSafety` is an object that contains data for safety's score and sub scores.

```kotlin
data class DKSafety(
        val score: Double,
        val acceleration: Int,
        val braking: Int,
        val adherence: Int
) : Serializable
```

| Attribute    | Type   | Description                                                     |
| ------------ | ------ | --------------------------------------------------------------- |
| score        | Double | Global safety score for the given period (ranging from 3 to 10) |
| acceleration | Int    | Number of harsh accelerations during the given period           |
| braking      | Int    | Number of hard breakings during the given period                |
| adherence    | Int    | Number of adherence limits during the given period              |

## DKEcoDriving

`DKEcoDriving` is an object that contains data for eco-driving's score and sub scores.

```kotlin
data class DKEcoDriving(
        val score: Double,
        val efficiencyBrake: Double,
        val efficiencyAcceleration: Double,
        val efficiencySpeedMaintain: Double,
        val co2Mass: Double,
        val fuelVolume: Double,
        val fuelSaving: Double
) : Serializable
```

| Attribute               | Type   | Description                                                                       |
| ----------------------- | ------ | --------------------------------------------------------------------------------- |
| score                   | Double | Global eco-driving score for the given period (ranging from 4 to 10)              |
| efficiencyAcceleration  | Double | Sub score of acceleration efficiency for the given period (ranging from -5 to 5)  |
| efficiencyBrake         | Double | Sub score of braking efficiency for the given period (ranging from -5 to 5)       |
| efficiencySpeedMaintain | Double | Sub score of speed maintain efficiency for the given period (ranging from 0 to 5) |
| fuelVolume              | Double | Fuel consumption during the given period (in liters)                              |
| fuelSaving              | Double | Achievable fuel savings during the given period (in liters)                       |
| co2Mass                 | Double | CO₂ mass consumed during the given period (in kilograms)                          |

## DKDistraction

`DKDistraction` is an object that contains data for distraction's score and sub scores.

```kotlin
data class DKDistraction(
        val score: Double,
        val unlock: Int,
        val lock: Int,
        val callAuthorized: Int,
        val callForbidden: Int,
        val callAuthorizedDuration: Int,
        val callForbiddenDuration: Int,
        val numberTripWithForbiddenCall: Int
) : Serializable
```

| Attribute                   | Type   | Description                                                                          |
| --------------------------- | ------ | ------------------------------------------------------------------------------------ |
| score                       | Double | Global distraction score for the given period (ranging from 0 to 10)                 |
| unlock                      | Int    | Number of screen unlocks during the given period                                     |
| lock                        | Int    | Number of screen locks during the given period                                       |
| callForbiddenDuration       | Int    | Duration of forbidden calls during the given period (in seconds)                     |
| numberTripWithForbiddenCall | Int    | Number of trips during which the driver made forbidden calls during the given period |
| callForbidden               | Int    | Number of forbidden calls during the given period                                    |
| callAuthorizedDuration      | Int    | Duration of authorised calls during the given period (in seconds)                    |
| callAuthorized              | Int    | Number of authorised calls during the given period                                   |

## DKSpeeding

`DKSpeeding` is an object that contains data for speeding's score and sub scores.

```kotlin
data class DKSpeeding(
    val score: Double,
    val speedingDuration: Int,
    val speedingDistance: Double,
) : Serializable
```

<table><thead><tr><th>Attribute</th><th width="255.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>score</td><td>Double</td><td>Global speeding score for the given period (ranging from 0 to 10)</td></tr><tr><td>speedingDuration</td><td>Int</td><td>Overspeeding duration during the given period (in seconds)</td></tr><tr><td>speedingDistance</td><td>Double</td><td>Overspeeding distance travelled during the given period (in meters)</td></tr></tbody></table>

## DKDrivingConditions

`DKDrivingConditions` is an object that contains advanced driving information for the given period.

```kotlin
data class DKDrivingConditions (
    val tripCountByCategory: Map<DKDrivingCategory, Int>,
    val distanceByCategory: Map<DKDrivingCategory, Double>,
    val tripCountByWeatherType: Map<DKWeather, Int>,
    val distanceByWeatherType: Map<DKWeather, Double>,
    val dayDistance: Double,
    val nightDistance: Double,
    val weekdaysDistance: Double,
    val weekendDistance: Double
) : Serializable
```

<table><thead><tr><th width="245">Attribute</th><th width="270.3333333333333">Type</th><th>Description</th></tr></thead><tbody><tr><td>tripCountByCategory</td><td><code>Map&#x3C;</code><a href="#dkdrivingcategory"><code>DKDrivingCategory</code></a><code>, Int></code></td><td>Total trips count by driving category</td></tr><tr><td>distanceByCategory</td><td><code>Map&#x3C;</code><a href="#dkdrivingcategory"><code>DKDrivingCategory</code></a><code>, Double></code></td><td>Total distance in km by driving category</td></tr><tr><td>tripCountByWeatherType</td><td><code>Map&#x3C;</code><a href="../../../get-started-drivekit/android/references#dkweather"><code>DKWeather</code></a><code>, Int></code></td><td>Total trips count by weather category</td></tr><tr><td>distanceByWeatherType</td><td><code>Map&#x3C;</code><a href="../../../get-started-drivekit/android/references#dkweather"><code>DKWeather</code></a><code>, Double></code></td><td>Total distance in km count by weather category</td></tr><tr><td>dayDistance</td><td><code>Double</code></td><td>Total distance traveled by the day in km </td></tr><tr><td>nightDistance</td><td><code>Double</code></td><td>Total distance traveled by night in km</td></tr><tr><td>weekdaysDistance</td><td><code>Double</code></td><td>Total distance traveled during weekdays in km</td></tr><tr><td>weekendDistance</td><td><code>Double</code></td><td>Total distance traveled during weekend in km</td></tr></tbody></table>

## DKDrivingCategory

```kotlin
enum class DKDrivingCategory(val index: Int) {
    LESS_THAN_2_KM(0),
    FROM_2_TO_10_KM(1),
    FROM_10_TO_50_KM(2),
    FROM_50_TO_100_KM(3),
    MORE_THAN_100_KM(4);
}
```

<table><thead><tr><th width="242">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><code>LESS_THAN_2_KM</code></td><td>Trip distance strictly below <code>2</code> km</td></tr><tr><td><code>FROM_2_TO_10_KM</code></td><td>Trip distance in <code>[2, 10[</code> km</td></tr><tr><td><code>FROM_10_TO_50_KM</code></td><td>Trip distance in <code>[10, 50[</code> km</td></tr><tr><td><code>FROM_50_TO_100_KM</code></td><td>Trip distance in <code>[50, 100[</code> km</td></tr><tr><td><code>MORE_THAN_100_KM</code></td><td>Trip distance is equals or above <code>100</code> km</td></tr></tbody></table>

## DKRoadContextItem

`DKRoadContextItem` is an object that contains data for the given road context and given period.

```kotlin
data class DKRoadContextItem(
        val type: RoadContext,
        override val date: Date,
        val numberTripTotal: Int,
        val numberTripScored: Int,
        val distance: Double,
        val duration: Int,
        val safety: DKSafety?,
        val ecoDriving: DKEcoDriving?
) : Serializable, DatedContextItem
```

<table><thead><tr><th width="223.33333333333331">Attribute</th><th width="192">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td><a href="#roadcontext">RoadContext</a></td><td>Road context for the given period</td></tr><tr><td>date</td><td>Date</td><td>Start date of the given period</td></tr><tr><td>numberTripTotal</td><td>Int</td><td>Total number of trips made during the given period and road context</td></tr><tr><td>numberTripScored</td><td>Int</td><td>Number of trips made that were long enough to have a score during the given period and road context</td></tr><tr><td>distance</td><td>Double</td><td>Total distance travelled during the given period and road context (in kilometers)</td></tr><tr><td>duration</td><td>Int</td><td>Total trip duration during the given period and road context (in minutes)</td></tr><tr><td>safety</td><td><a href="#dksafety">DKSafety</a>?</td><td>Safety's score and sub scores for the given period and road context (present only if safety score is configured and the period has some scored trips)</td></tr><tr><td>ecoDriving</td><td><a href="#dkecodriving">DKEcoDriving</a>?</td><td>Eco-driving's score and sub scores for the given period and road context (present only if eco-driving score is configured and the period has some scored trips)</td></tr></tbody></table>

## RoadContext

`RoadContext` indicates the kind of roads where the data was gathered. It is an enum with the following values:

<table><thead><tr><th width="286">Value</th><th>Description</th></tr></thead><tbody><tr><td>TRAFFIC_JAM</td><td>The targeted driver was in traffic jams</td></tr><tr><td>HEAVY_URBAN_TRAFFIC</td><td>The targeted driver was in dense city roads</td></tr><tr><td>CITY</td><td>The targeted driver was in light traffic city roads</td></tr><tr><td>SUBURBAN</td><td>The targeted driver was in suburban or countryside roads</td></tr><tr><td>EXPRESSWAYS</td><td>The targeted driver was in express ways</td></tr></tbody></table>

```kotlin
enum class RoadContext : Serializable {
    EXPRESSWAYS, HEAVY_URBAN_TRAFFIC, CITY, SUBURBAN, TRAFFIC_JAM
}
```

***

## DKDriverProfile

`DKDriverProfile` is the object describing the driver profile.

| Attribute                    | Type                                                                      | Description                                              |
| ---------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------- |
| distance                     | [DKDistanceProfile](#dkdistanceprofile)                                   | Distance class                                           |
| activity                     | [DKActivityProfile](#dkactivityprofile)                                   | Activity class                                           |
| regularity                   | [DKRegularityProfile](#dkregularityprofile)                               | Regularity class                                         |
| mainRoadContext              | [RoadContext](#roadcontext)                                               | Main road context                                        |
| mobility                     | [DKMobilityProfile](#dkmobilityprofile)                                   | Mobility class                                           |
| statistics                   | [DKDriverStatistics](#dkdriverstatistics)                                 | Statistics about the driver                              |
| weekRegularity               | [DKDriverRegularity](#dkdriverregularity)                                 | Information about driver’s week regularity               |
| monthRegularity              | [DKDriverRegularity](#dkdriverregularity)                                 | Information about driver’s month regularity              |
| distanceEstimation           | [DKDriverDistanceEstimation](#dkdriverdistanceestimation)                 | Distance estimation by week, month or year               |
| roadContextInfoByRoadContext | Map<[RoadContext](#roadcontext), [DKRoadContextInfo](#dkroadcontextinfo)> | Contains information about road contexts                 |
| commonTripByType             | Map<[DKCommonTripType](#dkcommontriptype), [DKCommonTrip](#dkcommontrip)> | Provides information about common trips, by type of trip |
| mobilityAreaRadiusByType     | Map<[DKMobilityAreaType](#dkmobilityareatype), Int>                       | Provides radius of mobility area by type of mobility     |

```java
@Keep
data class DKDriverProfile(
    val distance: DKDistanceProfile,
    val activity: DKActivityProfile,
    val regularity: DKRegularityProfile,
    val mainRoadContext: RoadContext,
    val mobility: DKMobilityProfile,
    val statistics: DKDriverStatistics,
    val weekRegularity: DKDriverRegularity,
    val monthRegularity: DKDriverRegularity,
    val distanceEstimation: DKDriverDistanceEstimation,
    val roadContextInfoByRoadContext: Map<RoadContext, DKRoadContextInfo>,
    val commonTripByType: Map<DKCommonTripType, DKCommonTrip>,
    val mobilityAreaRadiusByType: Map<DKMobilityAreaType, Int>
)
```

## DKDistanceProfile

`DKDistanceProfile` indicates the distance class of the driver.

| Value       | Description                | Estimated yearly distance (in km) |
| ----------- | -------------------------- | --------------------------------- |
| VERY\_SHORT | Very short distance driver | less than 5000                    |
| SHORT       | Short distance driver      | 5000 to 10000                     |
| MEDIUM      | Medium distance driver     | 10000 to 20 000                   |
| LONG        | Long distance driver       | 20 000 to 40 000                  |
| VERY\_LONG  | Professional driver        | more than 40 000                  |

```java
@Keep
enum class DKDistanceProfile {
    VERY_SHORT,
    SHORT,
    MEDIUM,
    LONG,
    VERY_LONG
}
```

## DKActivityProfile

`DKActivityProfile` indicates the activity class of the driver.

| Value  | Description            | Percentage of active weeks |
| ------ | ---------------------- | -------------------------- |
| LOW    | Low activity driver    | less than 30 %             |
| MEDIUM | Medium activity driver | 30 to 60 %                 |
| HIGH   | High activity driver   | more than 60 %             |

```java
@Keep
enum class DKActivityProfile {
    LOW,
    MEDIUM,
    HIGH
}
```

## DKRegularityProfile

`DKRegularityProfile` indicates the regularity class of the driver.

| Value        | Description         |
| ------------ | ------------------- |
| REGULAR      | Regular driver      |
| INTERMITTENT | Intermittent driver |

```java
@Keep
enum class DKRegularityProfile {
    REGULAR,
    INTERMITTENT
}
```

## DKMobilityProfile

`DKMobilityProfile` indicates the mobility class of the driver.

<table><thead><tr><th width="225">Value</th><th>Description</th></tr></thead><tbody><tr><td>NARROW</td><td>90% of trips are within a radius of less than 10 km</td></tr><tr><td>SMALL</td><td>90% of trips are within a radius of less than 20 km</td></tr><tr><td>MEDIUM</td><td>90% of trips are within a radius of less than 30 km</td></tr><tr><td>LARGE</td><td>90% of trips are within a radius of less than 50 km</td></tr><tr><td>WIDE</td><td>90% of trips are within a radius of less  than 100 km</td></tr><tr><td>VAST</td><td>90% of trips are within a radius of 100 km or more</td></tr></tbody></table>

```java
@Keep
enum class DKMobilityProfile {
    NARROW,
    SMALL,
    MEDIUM,
    LARGE,
    WIDE,
    VAST
}
```

## DKDriverStatistics

`DKDriverStatistics` is an object providing statistics about the driver.

| Attribute         | Type   | Description                                     |
| ----------------- | ------ | ----------------------------------------------- |
| tripsNumber       | Int    | Total number of trips                           |
| totalDistance     | Int    | Total distance (in km)                          |
| totalDuration     | Int    | Total driving duration (in min)                 |
| weekNumber        | Int    | Number of weeks since user registration         |
| activeWeekNumber  | Int    | Number of active weeks since user registration  |
| monthNumber       | Int    | Number of months since user registration        |
| activeMonthNumber | Int    | Number of active months since user registration |
| peakTime          | DKTime | Peak time trip starts                           |
| peakDay           | DKDay  | Weekday with most trips completed               |

```java
@Keep
data class DKDriverStatistics(
    val tripsNumber: Int,
    val totalDistance: Int,
    val totalDuration: Int,
    val weekNumber: Int,
    val activeWeekNumber: Int,
    val monthNumber: Int,
    val activeMonthNumber: Int,
    val peakTime: DKTime,
    val peakDay: DKDay
)
```

## DKDriverRegularity

`DKDriverRegularity` is an object providing information about driver’s regularity.

<table><thead><tr><th width="280.3333333333333">Attribute</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td>periodNumber</td><td>Int</td><td>Number of weeks or months used to calculate regularity</td></tr><tr><td>tripNumberMean</td><td>Int</td><td>Average number of trips per week or month</td></tr><tr><td>tripNumberStandardDeviation</td><td>Int</td><td>Standard deviation of the number of trips per week or month</td></tr><tr><td>distanceMean</td><td>Int</td><td>Average weekly or monthly distance (in km)</td></tr><tr><td>distanceStandardDeviation</td><td>Int</td><td>Standard deviation of the weekly or monthly distance (in km)</td></tr><tr><td>durationMean</td><td>Int</td><td>Average weekly or monthly driving duration (in min)</td></tr><tr><td>durationStandardDeviation</td><td>Int</td><td>Standard deviation of the weekly or monthly driving duration (in min)</td></tr></tbody></table>

```java
@Keep
data class DKDriverRegularity(
    val periodNumber: Int,
    val tripNumberMean: Int,
    val tripNumberStandardDeviation: Int,
    val distanceMean: Int,
    val distanceStandardDeviation: Int,
    val durationMean: Int,
    val durationStandardDeviation: Int
)
```

## DKDriverDistanceEstimation

`DKDriverDistanceEstimation` is an object providing distance estimation by week, month or year.

<table><thead><tr><th width="202.33333333333331">Attribute</th><th width="253">Type</th><th>Description</th></tr></thead><tbody><tr><td>weekDistance</td><td>Int</td><td>Estimated weekly distance (in km)</td></tr><tr><td>monthDistance</td><td>Int</td><td>Estimated monthly distance (in km)</td></tr><tr><td>yearDistance</td><td>Int</td><td>Estimated annual distance (in km)</td></tr><tr><td>confidence</td><td><a href="#dkdriverdistanceestimationconfidence">DKDriverDistanceEstimationConfidence</a></td><td>Confidence level indicator, based on the available data</td></tr></tbody></table>

```java
@Keep
data class DKDriverDistanceEstimation(
    val weekDistance: Int,
    val monthDistance: Int,
    val yearDistance: Int,
    val confidence: DKDriverDistanceEstimationConfidence
)
```

## DKDriverDistanceEstimationConfidence

`DKDriverDistanceEstimationConfidence` indicates the distance estimation confidence class.

<table><thead><tr><th width="170">Value</th><th>Description</th></tr></thead><tbody><tr><td>LOW</td><td>If less than 8 weeks since driver’s subscription</td></tr><tr><td>MEDIUM</td><td>If between 9 and 16 weeks since driver’s subscription</td></tr><tr><td>HIGH</td><td>If more than 16 weeks since driver’s subscription</td></tr></tbody></table>

```java
@Keep
enum class DKDriverDistanceEstimationConfidence {
    LOW,
    MEDIUM,
    HIGH
}
```

## DKRoadContextInfo

`DKRoadContextInfo` is an object providing information about road context for the driver.

<table><thead><tr><th width="270.3333333333333">Attribute</th><th width="174">Type</th><th>Description</th></tr></thead><tbody><tr><td>roadContext</td><td><a href="#roadcontext">RoadContext</a></td><td>Road context</td></tr><tr><td>distancePercentage</td><td>Double</td><td>Percentage of total distance driven in this context</td></tr><tr><td>durationPercentage</td><td>Double</td><td>Percentage of total duration driven in this context</td></tr><tr><td>consumedEnergyPercentage</td><td>Double</td><td>Percentage of total energy driven in this context</td></tr></tbody></table>

```java
@Keep
data class DKRoadContextInfo(
    val roadContext: RoadContext,
    val distancePercentage: Double,
    val durationPercentage: Double,
    val consumedEnergyPercentage: Double
)
```

## DKCommonTripType

`DKCommonTripType` indicates the type of trip.

<table><thead><tr><th width="231">Value</th><th>Description</th></tr></thead><tbody><tr><td>MOST_FREQUENT</td><td>Most frequent trip</td></tr><tr><td>UNKNOWN</td><td>Unknown type for the SDK (if a new type is added but the SDK is not up to date)</td></tr></tbody></table>

```java
@Keep
enum class DKCommonTripType {
    MOST_FREQUENT,
    UNKNOWN
}
```

## DKCommonTrip

`DKCommonTrip` is an object providing information about a trip.

<table><thead><tr><th width="207">Attribute</th><th width="197.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td><a href="#dkcommontriptype">DKCommonTripType</a></td><td>Type of trip</td></tr><tr><td>tripNumber</td><td>Int</td><td>Number of trips</td></tr><tr><td>distanceMean</td><td>Int</td><td>Average trip distance (in km)</td></tr><tr><td>durationMean</td><td>Int</td><td>Average trip duration (in min)</td></tr><tr><td>roadContext</td><td><a href="#roadcontext">RoadContext</a></td><td>Road context type</td></tr></tbody></table>

```java
@Keep
data class DKCommonTrip(
    val type: DKCommonTripType,
    val tripNumber: Int,
    val distanceMean: Int,
    val durationMean: Int,
    val roadContext: RoadContext
)
```

## DKMobilityAreaType

`DKMobilityAreaType` indicates the type of mobility area.

<table><thead><tr><th width="264">Value</th><th>Description</th></tr></thead><tbody><tr><td>PERCENTILE_50TH</td><td>The radius including 50% of all the user’s trips</td></tr><tr><td>PERCENTILE_90TH</td><td>The radius including 90% of all the user’s trips</td></tr></tbody></table>

```java
@Keep
enum class DKMobilityAreaType {
    PERCENTILE_50TH,
    PERCENTILE_90TH
}
```