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:
eco-driving indicators,
an estimate of the fuel consumption,
safety indicators,
tire and brake wear measurements,
pollutant emissions estimation,
a distraction score (phone use),
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.
Trip
POST
https://service.drivequant.com/v2/trip
This method returns all driving analytics calculated by DriveQuant for a trip.
Request Body
account
object
Identification data for the trip
route
object
GPS or vehicle recorded data for the trip
vehicle
object
Vehicle characteristics used for the trip
itineraryData
object
Data of the trip
metaData
object
Customer specific data
Request
Account
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:
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.
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.
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
gpsVelocity
array[double]
GPS speed vector in km/h
latitude
array[double]
Latitude vector in degree
longitude
array[double]
Longitude vector in degree
gpsAccuracy
array[double]
GPS accuracy vector in meter
gpsElevation
array[double]
Elevation vector in meter
gpsHeading
array[double]
Heading vector in degree
gpsDate
array[double]
GPS timestamp vector in second
vehVelocity
array[double]
Vehicle speed vector in km/h
vehEngineSpeed
array[double]
Engine speed vector in rotation per minute
vehTankLevel
array[double]
Fuel tank volume in liter
vehWheelAngle
array[double]
Steering angle vector in degree
batteryVoltage
array[double]
Measurement of the car battery voltage vector in volt
vehDate
array[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
carTypeIndex
int
carEngineIndex
int
carPower
double
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:
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.
startDate
date
Trip start date
Date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
endDate
date
Trip end date
Date format: YYYY-MM-dd’T’HH:mm:ss.SSSZ
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
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.
itinId
string
Trip unique identifier
status
boolean
true
if no problem, false
otherwise
comments
array[object]
itineraryStatistics
object
itineraryData
object