Search…
⌃K
Links

# Trip

This section describes the trip analysis API.

## Description

The overall approach behind DriveQuant’s trip analysis service is based on vehicle dynamics and powertrain modeling. Using vehicle or smartphone sensors, our services estimate the efforts applied to the powertrain enabling us, for example, to remodel the efforts between the road and the wheels or to estimate the exhaust pollutants.
DriveQuant’s data analysis service delivers a wide range of indicators describing vehicle usage and driver behavior. For a single trip, DriveQuant’s trip analysis service retrieves:
1. 1.
eco-driving indicators,
2. 2.
an estimate of the fuel consumption,
3. 3.
safety indicators,
4. 4.
tire and brake wear measurements,
5. 5.
pollutant emissions estimation,
6. 6.
a distraction score (phone use),
7. 7.
and a speed limit score.
The trip analysis API is automatically requested by the DriveKit SDK at the end of each trip.
This API can also be used without the DriveKit SDK if you have your own GPS data collection system (OBD dongle, black box, vehicle data).
The distraction score (phone use) is only available for SDK users.
An additional cost is required for the use of the speed limit score, which is calculated using data coming from map data providers.
This section explains how to query the trip analysis API, how driving indicators are computed and how they are structured.
DriveQuant services provide additional data by collecting all vehicle trips so you can easily retrieve statistics for each of your vehicles. We recommend to add a new vehicle before requesting the trip analysis API if you target a vehicule mantenance use case.
post
https://service.drivequant.com
/v2/trip
Trip

## Request

### Account

 Field Type Description account String API key userId String User unique identifier vehicleId String Vehicle unique identifier
DriveQuant counts the number of active assets per customer. The DriveQuant API is a pay-per-active-asset API. An asset is considered active if it has performed at least one trip on a monthly basis. An asset can be a driver (identified with its driverId) or a vehicle (identified by a vehicleId).
Three main use cases can be considered:
1. 1.
The request includes only a driverId: This is common when the data collected comes from a mobile application installed on a driver's phone. The total number of assets per customer is equal to the number of unique driverId's.
2. 2.
The request includes only a vehicleId: This is common when the data collected comes from a telematics device plugged into the vehicle. The total number of assets per customer is equal to the number of unique vehicleId's.
3. 3.
The request includes a driverId and a vehicleId: This is common when a group of drivers can use several vehicle within a fleet. The total number of assets may be the number of unique vehicleId's or driverId's. Billing and counting will depend on your business model and the difference between the number of drivers and vehicles. Please contact DriveQuant sales department to find out the best pricing model.
The Account object must contain the account and the userId or vehicleId attributes.

### Route

 Field Type Description gpsVelocity double[] GPS speed vector in km/h latitude double[] Latitude vector in degree longitude double[] Longitude vector in degree gpsAccuracy double[] GPS accuracy vector in meter gpsElevation double[] Elevation vector in meter gpsHeading double[] Heading vector in degree gpsDate double[] GPS timestamp vector in second vehVelocity double[] Vehicle speed vector in km/h vehEngineSpeed double[] Engine speed vector in rotation per minute vehTankLevel double[] Fuel tank volume in liter vehWheelAngle double[] Steering angle vector in degree batteryVoltage double[] Measurement of the car battery voltage vector in volt vehDate double[] Vehicle date timestamp vector in second
• A request must contain all the data corresponding to a single trip. The trip data analysis cannot be cut into multiple queries. It is not recommended to merge data from several trips into a single request.
• Route object must contain at least the vehDate or gpsDate and at least gpsVelocity or vehVelocity attributes.
• The input variables included into Route object are arrays which must contain the same number of data points.
• The sample period for all input vectors must be 1 second. The sampling frequency of 1Hz is a standard for GPS sensors. in case your telematics device does not satisfy this constraint, please contact us to determine what alternative can be applied.

### Vehicle

 Field Type Description carTypeIndex int carEngineIndex int 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$​ carMass double Vehicle mass in kg carGearboxIndex int carConsumption double Combined fuel consumption [l/100km] measured during the New European Driving Cycle (NEDC) carAutoGearboxNumber int Number of gear ratios for the automatic gearbox. This parameter is taken into account only if carGearboxIndex is set to 1
Some parameters have a default value if not set, and a min and max limitations:
 Field Default value Min Max carTypeIndex 1 (compact) - - carEngineIndex 1 (gasoline) - - carPower 150 40 450 carMass 1400 700 3500 carGearboxIndex 2 (manual 5-speed) - - carConsumption 4.5 3 20

### ItineraryData

Itinerary object is optional.
 Field Type Description startDate Date Trip start date. Example: 2017-09-07T08:00:00.000+0200 endDate Date Trip end date. Example: 2017-09-07T08:00:00.000+0200 departureCity String Name of the departure city arrivalCity String Name of the arrival city

### MetaData

Metadata can be used if you want to add some of your specific data in a trip. They can be added to the Trip API as a key/value object where the key and value have a String type

### Example of JSON body request

{
"account": {
"account": "<API KEY>",
"userId": "<UNIQUE USER ID>",
"vehicleId": "<UNIQUE VEHICLE ID>"
},
"vehicle": {
"carTypeIndex": 4,
"carEngineIndex": 1,
"carPower": 205.0,
"carMass": 1430.0,
"engineDisplacement": 1618.0,
"carGearboxIndex": 2,
"carConsumption": 6.0
},
"itineraryData": {
"startDate": "2018-02-15T15:20:00.000+0200",
"endDate": "2018-02-15T15:50:00.000+0200",
"departureCity": "<DEPARTURE>",
"arrivalCity": "<ARRIVAL>"
},
"route": {
"gpsVelocity": [...],
"latitude": [...],
"longitude": [...],
"gpsHeading": [...],
"gpsElevation": [...],
"gpsDate": [...],
"gpsAccuracy": [...]
},
"metaData" : {
"customerStringData" : "<CUSTOMER STRING DATA>",
"customerJsonData" : "{\"customerTestNumber\" : 1, \"customerTestString\" : \"<CUSTOMER TEXT>\"}"
}
}

## Response

The table below summarizes the list of driving data analysis modules. The comments and itinerary statistics modules are included by default. All other modules are optional and can be combined as needed.
 Field Type Description itinId String Trip unique identifier status Boolean true if no problem, false otherwise comments Comment[] ​Comment​ itineraryStatistics ItineraryStatistics itineraryData ItineraryData ecoDriving EcoDriving advancedEcoDriving AdvancedEcoDriving fuelEstimation FuelEstimation advancedFuelEstimation AdvancedFuelEstimation safety Safety ​Safety​ advancedSafety AdvancedSafety safetyEvents SafetyEvent[] tireWear TireWear ​TireWear​ brakeWear BrakeWear pollutants Pollutants userId String unique id of the user firstname String first name of the user lastname String Last name of the user endDate String End date of the trip driverDistraction DriverDistraction distractionEvents DistractionEvents[] callEvents CallEvent[] speedingStatistics SpeedingStatistics speedingEvents SpeedingEvents[] energyEstimation EnergyEstimation advancedEnergyEstimation AdvancedEnergyEstimation[]

### Comment

 Field Type Description errorCode int Error code comment String Error description
Possible values are described here.

### ItineraryStatistics

Itinerary Statistics module provides several indicators that characterize the trip conditions: the trip distance, the vehicle movement duration and the idle duration. We also compute the number of sub-displacements. A trip can be characterized as a succession of events either dictated by the driver’s will or by external factors. These events, called breakpoints, are indicated with black dots in the figure below. Each section of a trip between two breakpoints is called sub-displacement. The figure illustrates these concepts for a short trip with one traffic light (vehicle stopped) and one intersection with priority (vehicle deceleration followed by acceleration).
 Field Type Description distance double Distance travelled in meter speedMean double Mean vehicle speed in km/h tripDuration double Total trip duration in second drivingDuration double Vehicle movement duration in second idlingDuration double Total duration of idling phases (vehicle stopped) in second drivingPercentage double Percentage of vehicle movement idlingPercentage double Percentage of idling phases subdispNb int Number of sub-displacements detected during the trip meteo int day boolean true if day, false if night weekDay boolean true: Monday to Friday, false: Saturday to Sunday transportationMode int

### ItineraryData

 Field Type Description startDate Date Trip start date. Example : 2017-09-07T08:00:00.000+0200 endDate Date Trip end date. Example : 2017-09-07T08:00:00.000+0200 departureCity String Name of the departure city arrivalCity String Name of the arrival city departureAddress String Departure full address arrivalAddress String Arrival full address

### Eco-driving

#### Description

Eco-driving module performes an analysis of the entire trip, characterized by a succession of events and road segments. The driving efficiency is computed by comparing the vehicle speed recorded with an optimal speed profile, for each segment. This calculation takes into account the actual driving conditions and a physical vehicle model that captures the inertial dynamics of the vehicle and the efficiency of the powertrain components. The eco-driving score ranges from 0 and 10, and is calculated by comparing the actual energy consumed during the trip with the energy that would have been consumed using the optimal speed profile. The best eco-driving score corresponds to the highest driving efficiency.
 Field Type Description score double Eco-driving score (min: 0, max: 10). If trip is too short to be scored, score is set to 11. scoreAccel double Score of the acceleration phases. If trip is too short to be scored, score is set to 6. scoreMain double Score of the stabilized speed phases. If trip is too short to be scored, score is set to 6. scoreDecel double Score of the deceleration phases. If trip is too short to be scored, score is set to 6. stdDevAccel double Standard deviation of acceleration score stdDevMain double Standard deviation of stabilized speed score stdDevDecel double Standard deviation of deceleration score int 0: energy class A 1: energy class B2: energy class C3: energy class D4: energy class E

#### Scores definitions

Acceleration, deceleration and speed maintain phases have a large impact on the vehicle’s fuel consumption. As a consequence, by comparing the real and the optimal speed profiles, eco-driving analysis module returns 3 key driving indicators.
The acceleration and deceleration scores range from -5 to +5. For a value of (-5), your acceleration or deceleration is too slow. For the highest value (+5) you are accelerating or decelerating too fast. A score of (0) indicates that your acceleration or deceleration perfectly matches with an eco-driving style.
The speed maintain score ranges from 0 to 5. The minimum value (0) indicates that the driver has an appropriate behavior and drives at a constant speed. On the other hand, if the driving analysis module detects an oscillating speed profile, this score increases. The highest value (+5) indicates that you can improve to keep a constant speed to reduce your fuel consumption.
These indicators will help you improve your driving efficiency and reduce your energy consumption. They can also illustrate the level of anticipation that the drivers should adopt to avoid harsh accelerations and brakings.
The numerical values of driving scores can be transformed into driving tips. The tables below give examples of content that can be returned to a driver based on the driving notes of a trip:
 scoreAccel Description -5 to -4 Acceleration is too low -4 to -2 Weak acceleration -2 to 1 Good acceleration 1 to 3 Strong acceleration 3 to 5 Acceleration is too high
 scoreMain Description 0 to 1.5 Good speed maintain 1.5 to 3.5 Irregular speed 3.5 to 5 Very fluctuating speed
 scoreDecel Description -5 to -4 Deceleration is too low -4 to -2 Weak deceleration -2 to 1 Good deceleration 1 to 3 Strong deceleration 3 to 5 Deceleration is too high
The eco-driving analysis is performed for vehicle displacement greater than 100 meters and speed higher than 10 km/h. This avoids providing inaccurate driving scores during vehicle maneuvers (slow driving in traffic jams or in parking lots...). In that case, eco-driving analysis module returns the following error codes:
• 11 for the eco-driving score
• 6 for acceleration phase, stabilized speed phase and deceleration phase

#### Energy class

The energy class « energyClass » depends on the average fuel consumption of the vehicle. It positions the trip fuel consumption with respect to the average consumption of the vehicle.
• Class A corresponds to 0.5 x the NEDC consumption of the vehicle expressed in gCO2/km.
• Class E corresponds to 1.5 x the NEDC consumption of the vehicle expressed in gCO2/km
Then we defined the 5 classes with a uniform distribution between class A and class E. The energy class « energyClass » is calculated from the trip CO2 emission « co2Emission » and the function below:
Energy class definition

### Advanced eco-driving

 Field Type Description ecoDrivingContext EcoDrivingContext[] Array of EcoDrivingContext
In order to provide fair scoring and to facilitate drivers comparison, the trip scores can be accompanied by road class scores. These scores are included in the EcoDrivingContext class into the Advanced Modules. This service differentiates 5 types of road conditions (contextId) to contextualize the driving scores:
• 0 - Traffic jam: This corresponds to vehicle displacements of less than 100 meters and performed with speeds below 10 km/h. In traffic jams, it is obviously not possible to improve your driving, that is why scoring are not provided for this type of road.
• 1 - Heavy urban traffic
• 2 - City
• 3 - Suburban
• 4 - Expressways
In case a road type is not included in the trip, the distance and duration percentages are equal to zero, the efficiency score is set to 11 and the driving scores (Accel/Main/Decel) are set to 6.

#### EcoDrivingContext

 Field Type Description distance double Percentage of distance travelled in a road type duration double Percentage of elapsed time in a road type efficiencyScore double Eco-driving score scoreAccel double Score of the acceleration phases scoreMain double Score of the stabilized speed phases scoreDecel double Score of the deceleration phases contextId int

### Fuel estimation

#### Description

The fuel consumption is obtained from a backward computation based on a mathematical modeling of the vehicle and powertrain. Fuel consumption estimation asses the mechanical traction power from the vehicle speed and mass. A power transfer is performed between each component of the powertrain to compute the engine torque. Finally, the engine torque combined with the vehicle speed help to process the fuel mass from an engine consumption map developed by IFPEN. This fuel mapping is adapted according to the vehicle parameters and is valid for any type of vehicle or fleet of vehicles.
This approach is particularly adapted to estimate real-driving fuel consumption which can be more than 20% above the homologation data provided by car manufacturers. The main advantage lies in the accuracy of the estimate that can reach 5% when all input variables are available and the vehicle parameters set. The estimation method accounts for the physical fuel characteristics. These parameters are listed below:
 Fuel type Density (kg/l) Lower heating value (GJ/t) CO2 emission factor (tCO2/TJ) CO2 emission factor (kgCO2/l) Gasoline 0.755 44 70.26 2.3340 Diesel 0.845 42 75.70 2.6866
Values calculated by fuel estimation module are described below:
 Field Type Description co2Mass double Total Mass of CO2 in kg co2Emission double Total Mass of CO2 per unit of distance in g/km fuelConsumption double Total fuel consumption per unit of distance in l/100km fuelVolume double Total fuel consumption in liter idleFuelPercentage double Idle fuel consupmtion percentage idleFuelConsumption double Idle fuel consumption per unit of distance in l/100km idleCo2Emission double Idle CO2 emission in g/km idleCo2Mass double Idle CO2 mass in kg engineTempStatus boolean Engine cold start ? coldFuelVolume double Cold engine fuel volume

### Advanced fuel estimation

 Field Type Description fuelEstimationContext FuelEstimationContext[] Array of FuelEstimationContext​
In order to provide detailed fuel consumption estimation across the vehicle trips, the advanced fuel estimation service may return the fuel consumption for each driving context of the vehicle. This service differentiates 5 types of road conditions (contextId):
• 0 - Traffic jam
• 1 - Heavy urban traffic
• 2 - City
• 3 - Suburban
• 4 - Expressways
In case a road type is not included in the trip, the percentages of distance and duration are equals to zero as well as the co2Mass, co2Emission, fuelVolume and fuelConsumption.

#### FuelEstimationContext

 Field Type Description contextId int Road conditions distance double Percentage of distance travelled in a road type duration double Percentage of elapsed time in a road type co2Mass double Total Mass of CO2 in kg co2Emission double Total Mass of CO2 per unit of distance in g/km fuelVolume double Total fuel consumption in liter fuelConsumption double Total fuel consumption per unit of distance in l/100km

### EnergyEstimation

For the electric vehicles, DriveQuant provides energy information instead of fuel estimation.
Field
Type
Description
energy
double
Estimated energy in kWh
energyConsumption
double
Estimated energy consumption in kWh/100km
energyOpti
double
Optimal energy in kWh
energyOptiConsumption
double
Optimal energy consumption in kWh/100km

### AdvancedEnergyEstimation

To provide more details on the energy consumption, the service may return the energy data for each driving context of the vehicle.
Field
Type
Description
energy
double
Estimated energy in kWh
energyConsumption
double
Estimated energy consumption in kWh/100km
energyOpti
double
Optimal energy in kWh
energyOptiConsumption
double
Optimal energy in kWh/100km
contextId
int
Road conditions
distance
double
Percentage of distance travelled in a road type
duration
double
Percentage of elapsed time in a road type

### Safety

 Field Type Description safetyScore double Driver risk index for a given itineraryRanges from 3 to 10 nbAdh int Number of adherence threshold crossing nbAccel int Number of strong accelerations nbDecel int Number of strong decelerations nbAdhCrit int Number of adherence threshold crossing (critical) nbAccelCrit int Number of critical accelerations (critical) nbDecelCrit int Number of critical decelerations (critical)
If trip is too short to be scored, safetyScore is set to 11.

### Advanced safety

 Field Type Description safetyContext SafetyContext[] Array of SafetyContext​

#### SafetyContext

 Field Type Percentage of distance travelled in a road type distance double Percentage of distance travelled in a road type duration double Percentage of elapsed time in a road type safetyScore double Ranges from 3 to 10 nbAdh int Number of adherence threshold crossing nbAccel int Number of strong accelerations nbDecel int Number of strong decelerations nbAdhCrit int Number of adherence threshold crossing (critical) nbAccelCrit int Number of critical accelerations (critical) nbDecelCrit int Number of critical decelerations (critical) contextId int Road conditions
In case a road type is no included in the trip, the distance and duration percentages are equal to zero and the safety score is set to 11.

### SafetyEvents

The data provided in the following table helps to display safety events on your map system and deliver the locations of harsh braking or acceleration as well as the coordinates where a tire to road adherence threshold has been crossed.
 Field Type Description time double Time since the beginning of the trip in second latitude double Latitude in degree longitude double Longitude in degree velocity double Vehicle speed in km/h heading double Vehicle heading in degree elevation double Altitude in meter distance double Distance travelled since the beginning of the trip in meter type int Type of event 1. Adherence 2. Acceleration 3. Braking level int Intensity related to the event 1. Strong 2. Harsh value int Absolute value of the event:in m/s2 for acceleration and braking eventsnormalized between 0 and 1 for the adherence events
The service provides the time, coordinate and severity level of each event. Two levels of severity are calculated using specific threshold values for each event.
 Type of event Unit Strong Harsh Acceleration m/s2 2.0 2.5 Braking m/s2 -1.8 -2.4 Adherence limit - 0.2 0.3

### Pollutants

 Field Type Description co double Carbon monoxide (CO) emissions expressed in mg/km hc double Hydrocarbons (HC) emissions expressed in mg/km nox double Nitrogen oxide emissions (NOx) expressed in mg/km soot double Soot emissions expressed in mg/km

### Tire and brake wear estimates

#### Description

The wear analysis service has been designed to monitor the brake pads and tires wear levels. This service was designed to improve vehicle maintenance solutions and can be used to create maintenance alerts.
The wear estimation relates to the power dissipated in the tire - road or brake disc - brake contact. To compute this variable our service relies on the vehicle’s dynamic modelling that estimates the braking efforts and the efforts at the contact between the tire and the road.
For each trip, the service gives for each components (front/rear brakes/tires):
• The worn mass fraction during the trip.
• The total worn percentage since the installation of new tires or brakes.
Tire and brake wear indicators for a single trip
The wear analysis service measures tire wear and brake pad wear. The service allows to distinguish the front and rear axles of the vehicle. The wear is assumed to be the same for the right tire and the left tire of the vehicle. A similar assumption is made for the brake pads.
The output value corresponds to a mass fraction of the worn componen