References (Android)

TripResult

TripResult is a sealed class that indicates if the analyzed trip by the DriveQuant servers is valid or not, and it either provides information about the analyzed trip, or the cause of the error:

sealed class TripResult {
    data class TripValid(val itinId: String, val hasSafetyAndEcoDrivingScore: Boolean, val info: List<TripResponseInfo>) : TripResult() {
       fun getTrip(): Trip?
    }
    
    data class TripError(val tripResponseError: TripResponseError) : TripResult()

TripValid

If TripResult is TripValid, it means that the analyzed trip is valid. Additional information are available:

Field	Type	Description
itinId	String	Unique trip identifier generated after the trip data analysis.
localTripId	String	Local and unique trip identifier generated by DriveKit SDK ⚠️ It is different from the itinId property returned in the Trip object.
hasSafetyAndEcoDrivingScore	Boolean	If false, it means that the trip is too short to be analyzed. In this case, there is no safety or ecodriving score.
info	List<TripResponseInfo>	The DriveQuant servers returns a list of information codes. These are not errors.

This object also provides a method, getTrip(), to retrieve from the local database the saved Trip.

TripResponseInfo

Value	Description
ENGINE_SPEED_NOT_AVAILABLE	The engine speed is not available. The trip analysis is performed with an estimated value of the engine speed.
ENGINE_SPEED_IS_NULL	The engine speed is always at 0 rpm while the vehicle is moving. The trip analysis is performed but with an estimated value of the engine speed.
NO_VEHICLE_CHARACTERISTICS	The vehicle characteristics are not set or some values are missing. The trip analysis is performed with generic vehicle model parameters.
DATA_LOSS	More than 25% of data loss is detected during the trip.
DISTANCE_TOO_SHORT	The trip was analysed but the distance is not sufficient to provide an accurate energy analysis.
INVALID_VEHICLE_CHARACTERISTICS	The vehicle characteristics are not in the range of available values. See vehicle characteristics for range limits.
INVALID_VEHICLE_ID	No vehicle found for the vehicleId provided to the API request.

TripError

If TripResult is TripError, it means that the trip has been analyzed but an error occurred and data is not valid. Additional error information are available:

Property	Type	Description
localTripId	String	Local and unique trip identifier generated by DriveKit SDK. ⚠️ It is different from the itinId property returned in the Trip object. itinId corresponds to the unique trip identifier generated after the data analysis.
tripResponseError	TripResponseError	The reason why the trip is analyzed as invalid.

TripResponseError

Value	Description
NO_ACCOUNT_SET	The account block is not set in the trip data.
NO_ROUTE_OBJECT_FOUND	The route block is not available in the trip data.
INVALID_ROUTE_DEFINITION	Error when parsing the route block
NO_VELOCITY_DATA	The vehicle or GPS velocity is not available
INVALID_SAMPLING_PERIOD	The input variables have an invalid acquisition period.
INVALID_CUSTOMER_ID	Unknown account value. Unauthorised access.
NO_DATE_FOUND	The field vehicleDate or gpsDate is not available.
MAX_DAILY_REQUEST_NUMBER_REACHED	The trip could not be analyzed because you exceeded your daily request quota.
DATA_ERROR	The service failed to process your data. There is a need to diagnose your data to determine the origin of this problem.
INVALID_ROUTE_VECTORS	The route vectors are not of the same size, the service cannot perform the analysis
MISSING_BEACON	The beacon has not been detected and it is required to validate the trip analysis.
INVALID_BEACON	A beacon was detected during the trip but it does not have the correct identifiers
DUPLICATE_TRIP	The duplicate trip feature is enabled and the trip has already been analysed
INSUFFICIENT_GPS_DATA	The number of GPS points is too low
USER_DISABLED	The driver is disabled, the service cannot perform the analysis
INVALID_USER	The user identifier is not valid.
INVALID_GPS_DATA	The dates are inconstistent, the service cannot perform the analysis
INVALID_TRIP	The trip has already been analysed by the service and considered as invalid
ACCOUNT_LIMIT_REACHED	The maximum number of user account reached for the customer
UNKNOWN_ERROR	The error is not yet handled by the DriveKit SDK.

Trip

Field	Type	Description
itinId	String	Trip unique identifier.
endDate	Date	The end date of the trip.
startDate	Date?	The start date of the trip.
vehicleId	String?	The identifier of the vehicle used for this trip, if known.
transportationMode	TransportationMode	The transportation mode used for this trip, among: CAR, MOTO, TRUCK, BUS, TRAIN, BOAT, BIKE, FLIGHT, SKIING, ON_FOOT, IDLE, OTHER, UNKNOWN.
declaredTransportationMode	DeclaredTransportationMode?	The transportation mode declared by the user. See DeclaredTransportationMode.
departureCity	String	The city of the departure of the trip.
arrivalCity	String	The city of the arrival of the trip.
departureAddress	String	The full address of the departure of the trip.
arrivalAddress	String	The full address of the arrival of the trip.
unscored	Boolean	true if has no safety and eco-driving score.
occupantInfo	OccupantInfo?	Indicating whether the occupant was the driver or a passenger. See OccupantInfo.
metaData	Map<String, String>	Your specific data attached to the trip. See Custom metadata.
tripStatistics	TripStatistics?	Indicators that characterize the trip conditions. See ItineraryStatistics.
brakeWear	BrakeWear?	See BrakeWear.
tireWear	TireWear?	See TireWear.
ecoDriving	EcoDriving?	See EcoDriving.
ecoDrivingContexts	List<EcoDrivingContext>	See AdvancedEcoDriving.
fuelEstimation	FuelEstimation?	See FuelEstimation.
fuelEstimationDrivingContexts	List<FuelEstimationDrivingContext>	See Advanced fuel estimation.
safety	Safety?	See Safety.
safetyContexts	List<SafetyContext>	See AdvancedSafety.
safetyEvents	List<SafetyEvent>?	See SafetyEvents.
driverDistraction	DriverDistraction?	See DriverDistraction.
pollutants	Pollutants?	See Pollutants.
speedingStatistics	SpeedingStatistics?	See Speed Limit.
speedLimitContexts	List<SpeedLimitContext>?	See SpeedLimitContexts.
calls	List<Call>?	See CallEvent.
energyEstimation	EnergyEstimation?	See EnergyEstimation.
advancedEnergyEstimations	List<AdvancedEnergyEstimation>?	See AdvancedEnergyEstimation.

OccupantInfo

Field	Type	Description
role	OccupantRole	Indicates the role of the occupant. See OccupantRole.
passengerProbability	Int	Probability, expressed as a percentage, that the vehicle occupant is a passenger.

OccupantRole

Value	Description
DRIVER	The vehicle occupant is very likely to be a driver.
PASSENGER	The vehicle occupant is very likely to be a passenger.
UNAVAILABLE	The trip data and historical information about the user's habits do not allow determining whether the occupant is a driver or a passenger. In this case, we recommend considering the occupant as the driver for this trip.
NOT_APPLICABLE	The trip was made using public transportation (such as train or bus) or by a mode of transport other than a car (e.g., bicycle, boat, plane). In these cases, driver/passenger detection is not performed.

DeclaredTransportationMode

The user has the possibility to declare the transportation mode that was used during a trip to confirm the one detected or to change it, and to declare whether the trip was made as a passenger or as the driver.

Here is the description of the corresponding object:

Field	Type	Description
transportationMode	TransportationMode	The transportation mode declared by the user for this trip, among: CAR, MOTO, TRUCK, BUS, TRAIN, BOAT, BIKE, FLIGHT, SKIING, ON_FOOT, IDLE, OTHER, UNKNOWN.
passenger	Boolean?	true if the trip was made as a passenger, false if the trip was made as the driver.
comment	String?	The comment associated to this declaration.

DKTripRecordingStartedState

This object is returned in the TripListener's tripRecordingStarted() callback.

Field	Type	Description
localTripId	String	Local and unique trip identifier generated by DriveKit SDK ⚠️ It is different from the itinId property returned in the Trip object, which corresponds to the unique trip identifier generated after the data analysis.
startMode	StartMode	Indicates how the trip started. Possible values are describe here.
recordingStartDate	Date	Date when DriveKit has started the trip recording. ⚠️ It is not the recalculated trip start date returned in TripResult after DriveQuant platform's analysis.

DKTripRecordingConfirmedState

This object is returned in the TripListener's tripRecordingConfirmed() callback.

Field	Type	Description
localTripId	String	Local and unique trip identifier generated by DriveKit SDK ⚠️ It is different from the itinId property returned in the Trip object, which corresponds to the unique trip identifier generated after the data analysis.
startMode	StartMode	Indicates how the trip started. Possible values are describe here.
recordingStartDate	Date	Date when DriveKit has started the trip recording. ⚠️ It is not the recalculated trip start date returned in TripResult after DriveQuant platform's analysis.
recordingConfirmationDate	Date	Date when the trip entered into the confirmation state.

DKTripRecordingCanceledState

This object is returned in the TripListener's tripRecordingCanceled() callback.

Field	Type	Description
localTripId	String	Local and unique trip identifier generated by DriveKit SDK ⚠️ It is different from the itinId property returned in the Trip object, which corresponds to the unique trip identifier generated after the data analysis.
startMode	StartMode	Indicates how the trip started. Possible values are describe here.
recordingStartDate	Date	Date when DriveKit has started the trip recording. ⚠️ It is not the recalculated trip start date returned in TripResult after DriveQuant platform's analysis.
recordingConfirmationDate	Date?	Date when the trip was confirmed if the trip entered into the confirmation state.
cancelationReason	DKTripCancelationReason	Indicates how the trip was canceled. Possible values are described here.

DKTripRecordingFinishedState

This object is returned in the TripListener's tripRecordingFinished() callback.

Field	Type	Description
localTripId	String	Local and unique trip identifier generated by DriveKit SDK ⚠️ It is different from the itinId property returned in the Trip object, which corresponds to the unique trip identifier generated after the data analysis.
startMode	StartMode	Indicates how the trip started. Possible values are describe here.
recordingStartDate	Date	Date when DriveKit has started the trip recording. ⚠️ It is not the trip start date returned in TripResult after DriveQuant platform's analysis.
recordingConfirmationDate	Date	Date when the trip entered into the confirmation state.
recordingEndDate	Date	Date when DriveKit has terminated the trip recording. ⚠️ It is not the trip end date returned in TripResult after DriveQuant platform's analysis.

StartMode

StartMode indicates how the trip is started. It is an enum with the following values:

Value	Description
Value	Description
GPS	Automatic start when the SDK detects a change in user position
BEACON	Automatic start due to the presence of a beacon
MANUAL	Trip started manually by calling the method startTrip()
GEOZONE	Automatic start when the SDK detects that you exit the zone where your vehicle may be parked
BLUETOOTH	Automatic start by detecting a connection to a vehicle's Bluetooth system
UNKNOWN_BLUETOOTH	Automatic start by detecting a connection to a unknown vehicle's Bluetooth system
BICYCLE_ACTIVITY	Automatic start by detecting a bicycle activity
CONNECTED_CAR	Automatic start when the SDK detects that your smartphone has been connected to an Android Auto or Automotive OS system

DKTripCancelationReason

Value	Description
USER	Trip canceled by calling the method cancelTrip
HIGH_SPEED	Trip canceled because speed was too high (train, airplane)
NO_SPEED	Trip canceled because speed was too slow to be made in a vehicle
NO_BEACON	Trip canceled because the beacon was not detected while it was required
NO_BLUETOOTH_DEVICE	Trip canceled because the Bluetooth device was not detected while it was required.
MISSING_CONFIGURATION	Trip canceled because DriveKit was not configured
NO_LOCATION_DATA	Trip canceled because no location data was recorded
RESET	Trip canceled because SDK configuration has been reset.
BEACON_NO_SPEED	Trip canceled because the beacon is near the smartphone but there was no movement (zero or low speed)
BLUETOOTH_DEVICE_NO_SPEED	Trip canceled because the Bluetooth device is connected to the smartphone but there was no movement (zero or low speed)
APP_KILLED	The trip recording has been canceled due to an app termination. The trip is not sent to the DriveQuant's platform for analysis because it has never entered in confirmation state, or the Bluetooth device/Beacon is required but has not been detected.

TripPoint

TripPoint is an object that contains data for each location registered by the SDK.

Attribute	Type	Description
latitude	Double	Latitude
longitude	Double	Longitude
speed	Double	Speed in km/h
accuracy	Double	Accuracy of the GPS data in meter
elevation	Double	Elevation in meter
distance	Double	Distance since the beginning of the trip in meter
heading	Double	Heading
duration	Double	Duration since the beginning of the trip in second

TripVehicle

TripVehicle is an object that contains vehicle detailed characteristics.

data class TripVehicle (
    val carTypeIndex: Int = 1,
    val carEngineIndex: Int = 1,
    val carPower: Double = 150.0,
    val carMass: Double = 1400.0,
    val carGearboxIndex: Int = 2,
    val carConsumption: Double = 4.5,
    val carAutoGearboxNumber: Int = 0,
    val engineDisplacement: Double = 1200.0,
    val frontTireSize: String? = null,
    val rearTireSize: String? = null,
    val length: Double? = null,
    val width: Double? = null,
    val height: Double? = null,
    val engineCylinderNb: Int? = null,
    val driveWheels: Int? = null
)

Attribute	Type	Description	Default value, if not specified
carTypeIndex	Int	Vehicle body type	1
carEngineIndex	Int	Engine type	1
carPower	Double	Vehicle power in hp. This value must be entered in horsepower. In case you only have the engine power in kW you can apply the following formula: $P [hp] = P [kW] / 0.7355$ (min: 40 hp, max 450 hp)	150
carMass	Double	Vehicle mass in kg (min: 700 kg, max: 3500 kg)	1400
carGearboxIndex	Int	Gearbox type	2
carConsumption	Double	Combined fuel consumption [l/100km] measured during the New European Driving Cycle (NEDC). (min: 3 l/100km, max: 20 l/100km)	4.5
carAutoGearboxNumber	Int	Number of gear ratios for the automatic gearbox. This parameter is taken into account only if carGearboxIndex is set to 1.	6
engineDisplacement	Double	Engine displacement in liters	1200
frontTireSize	String?	Front tire size	"205/55/16"
rearTireSize	String?	Rear tire size	"205/55/16"
length	Double?	Vehicle length in meter	4.5
width	Double?	Vehicle width in meter	1.8
height	Double?	Vehicle height in meter	1.45
engineCylinderNb	Int?	Number of cylinders	4
driveWheels	Int?	Drive wheels type	0

BeaconData

BeaconData is an object that contains beacon characteristics.

Attribute	Type	Description
proximityUuid	String	Beacon proximity UUID
major	Int	Beacon major value (set to -1 to ignore value)
minor	Int	Beacon minor value (set to -1 to ignore value)

BluetoothData

BluetoothData is an object that contains the Bluetooth device characteristics.

Attribute	Type	Description
macAddress	String	Required MAC address of the device
name	String	Optional display name of the device

DKCrashInfo

Crash information object have the following structure:

Attribute	Type	Description
crashId	String	Crash unique identifier
date	Date	Crash date Example: 2023-03-07T09:13:22.461+0200
probability	Short	Crash probability (in %)
latitude	Double	Coordinates (latitude) of the crash
longitude	Double	Coordinates (longitude) of the crash
velocity	Double	Velocity at time of crash
crashStatus	DKCrashStatus	Crash status enum. Two possible values: CONFIRMED or UNCONFIRMED
userLocationUrl	String?	When a crash is confirmed and push crash data is activated, an URL of the map that will display the location data is returned. Otherwise, it is null.

DKCrashFeedbackConfig

DKCrashFeedbackConfig is an object used to configure the Crash Detection feedback feature.

Attribute	Type	Description
notification	DKCrashFeedbackNotification	Configuration of the notification
crashVelocityThreshold	Double	Minimal speed when the crash occurred. For example, if crashVelocityThreshold is set at 20 km/h and a crash occurred at 10 km/h, feedback will not be sent to the user. Default value : 0.0 km/h

DKCrashFeedbackNotification

Attribute	Type	Description
icon	Int	Resource identifier of the notification icon
channelId	String	Android channel identifier. Default value: dq_sdk_crash_channel
notificationId	Int	Android notification identifier
title	String	Title that appears on the notification
message	String	Message that appears on the notification
activity	Class<*>	Activity to display
crashAlert	DKCrashAlert	Object that describes how the user will be noticed when a feedback is asked Default value : SILENCE

DKCrashAlert

Attribute	Description
SILENCE	Device will not vibrate or ring
VIBRATION	Device will vibrate
SOUND_AND_VIBRATION	Device will ring and vibrate

CrashFeedbackType

Enum value	Description
NO_CRASH	User said that no crash occurred
CRASH_CONFIRMED	User confirmed a crash
NO_FEEDBACK	User did not provide any feedback

CrashFeedbackSeverity

Enum value	Description
NONE	User said that no crash occurred
MINOR	User confirmed a minor crash
CRITICAL	User confirmed a critical crash

TripResponseStatus (Deprecated)

TripResponseStatus is a sealed class that indicates if the analyzed trip by the DriveQuant servers is valid or not:

TripValid

If TripResponseStatus is TripValid, it means that the analyzed trip is valid. Additional information are available:

Field	Type	Description
hasSafetyAndEcoDrivingScore	Boolean	If false, it means that the trip is too short to be analyzed. In this case, there is no safety or ecodriving score.
info	List<TripResponseInfo>	The DriveQuant servers returns a list of information codes. These are not errors.

TripResponseError

If TripResponseStatus is TripResponseError, it means that the trip has been analyzed but an error occurred and data is not valid. Additional error information are available in the tripResponseError enum.

CancelTrip (Deprecated)

CancelTrip indicates how the trip was cancelled. It is an enum with the following values:

Value	Description
USER	Trip cancelled by calling the method cancelTrip
HIGHSPEED	Trip cancelled because speed was too high (train, airplane)
NO_SPEED	Trip cancelled because speed was too slow to be made in a vehicle
NO_BEACON	Trip cancelled because the beacon was not detected while it was required
MISSING_CONFIGURATION	Trip cancelled because DriveKit was not configured
NO_GPS_DATA	Trip cancelled because no GPS data was recorded
RESET	Trip cancelled because SDK configuration has been reset.
BEACON_NO_SPEED	Trip cancelled because the beacon is near the smartphone but there was no movement (zero or low speed)
BLUETOOTH_DEVICE_NO_SPEED	Trip cancelled because the Bluetooth device is connected to the smartphone but there was no movement (zero or low speed)

DeviceConfigEvent (Deprecated)

DeviceConfigEvent indicates when the device configuration has been changed. It is a sealed class with the following values:

BluetoothSensorStateChanged

This data class is called when the Bluetooth device sensor has been turned on or off.

• btEnabled : Equals true when the Bluetooth sensor has been turned on.

• btRequired : Equals true when the DriveKit configuration needs the Bluetooth sensor (when beaconRequired is set to true or when TripAnalysis component is configured with is at least one beacon or one Bluetooth device).

GpsSensorStateChanged

This data class is called when the GPS sensor has been turned on or off

• isEnabled: Equals true when the GPS sensors has been turned on.