# Trip analysis from custom data source ## Principle The trip analysis service combines GPS measurements with physical models of vehicle dynamics to produce driving behaviour insights: * Trip statistics * Eco-driving indicators and fuel consumption estimates * Tire and brake wear measurements * Driving safety indicators * Speed limit score The trip analysis service processes GPS data sampled at 1 Hz (once per second), which is typically the maximum frequency of consumer-grade GPS sensors. If you are using the DriveKit SDK, trip analysis runs automatically and the results are synchronized at the SDK level and transferred to your platform through our push trip service. If you operate your own data collection infrastructure (black box, OBD device, or in-vehicle data system), you can leverage the same analysis capabilities by using the Trip Analysis API. This section explains how to send your trip data to the Trip Analysis API and how to interpret the response. ## Request The trip analysis service has the following signature: `POST` `https://service.drivequant.com/v1/drivekit/analysis/trip` ### Request body The data required for the request are as follows: a unique user identifier, the trip end date, the vehicle characteristics, and the trip data — typically GPS data recorded at a sampling frequency of 1 Hz.

Name	Type	Description
userId	`string`	User unique identifier
tripEndDate	`date`	Trip end date
vehicle	`object`	see Vehicle characteristics
route	`object`	see GPS route data

Sample request

```json { "userId": "f49ac10a-57cc-4872-a567-0e92b2d3d479", "tripEndDate": "2026-04-02T10:05:10.662+0000", "vehicle": { "typeIndex": 1, "engineIndex": 1, "power": 150, "mass": 1400, "gearboxIndex": 2, "consumption": 4.5, "autoGearboxNumber": 6, "engineDisplacement": 1200, "frontTireSize": "205/55/16", "rearTireSize": "205/55/16", "length": 4.5, "width": 1.8, "height": 1.45, "engineCylinderNb": 4, "driveWheels": 0 }, "route": { "gpsDate": [double], "latitude": [double], "longitude": [double], "gpsVelocity": [double], "gpsAccuracy": [double], "gpsElevation": [double], "gpsHeading": [double] } } ```

#### User Each request requires a unique user identifier, provided in the userId field. This field is mandatory, as it is used to track the number of unique users of the service, and serves as the basis for monthly billing. {% hint style="info" %} User identification also enables data aggregation, allowing the generation of [synthesis](https://docs.drivequant.com/backend/driver/synthesis-of-scores) and[ timeline](https://docs.drivequant.com/backend/driver/timeline-of-scores) (weekly and monthly) for driving indicators (mileage, number of trips, average scores, etc.). {% endhint %} #### Trip end date The trip end date can be provided via the tripEndDate field. If not specified, the service defaults to the current server time with no timezone offset (UTC). #### Vehicle characteristics For a more accurate analysis of driving behavior, we recommend configuring the vehicle that was actually used. Vehicle mass and engine type are key parameters for getting an accurate fuel consumption estimation, and for computing the ecodriving score. The vehicle characteristics can be provided in the vehicle field:

Name	Type	Description	Default value
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 (in 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 l)	1200
frontTireSize	`string`	Front tire size	"205/55/16"
rearTireSize	`string`	Rear tire size	"205/55/16"
length	`double`	Vehicle length (in m)	4.5
width	`double`	Vehicle width (in m)	1.8
height	`double`	Vehicle height (in m)	1.45
engineCylinderNb	`int`	Number of cylinders	4
driveWheels	`int`	Drive wheels type	0

{% hint style="info" %} If the vehicle field is omitted from the request, the API will fall back to a default vehicle, whose characteristics are listed in the table. {% endhint %} #### GPS route data The route field accepts standard GPS data points (location, speed, altitude, heading, and accuracy) as typically provided by a GPS device.

Name	Type	Description
gpsDate*	`array[double]`	GPS relative time vector (in s)
gpsVelocity*	`array[double]`	GPS speed vector (in km/h)
latitude	`array[double]`	Latitude vector (in deg)
longitude	`array[double]`	Longitude vector (in deg)
gpsAccuracy	`array[double]`	GPS accuracy vector (in m)
gpsElevation	`array[double]`	GPS elevation vector (in m)
gpsHeading	`array[double]`	GPS heading vector measured clockwise from true North (in deg)

{% hint style="info" %} * Each request corresponds to a **single trip**. Therefore, splitting a trip across multiple requests is not supported, and no attempt will be made to merge the requests. * Only the gpsDate and gpsVelocity fields are mandatory. However, providing the other fields enables the computation of more metrics. * All the arrays in the route field must have the same length. * All parameters must be sampled at 1 Hz (once per second), in line with standard GPS sensor specifications. This frequency is necessary to accurately capture acceleration and braking events for vehicle dynamics analysis. {% endhint %} #### Rate limiting The Trip Analysis API is limited to **20 requests per second**. Requests that exceed this threshold will receive an error response. We recommend implementing retry logic with exponential backoff to handle these errors gracefully. ## Response The Trip Analysis API returns a rich, structured response organized by data category. The table below summarizes the available analysis modules. The comments and itinerary statistics modules are included by default; all others are optional and can be combined as needed.

Name	Type	Description
itinId	`string`	Trip unique identifier
userName	`string`	User unique identifier
endDate	`date`	Trip end date
processingDate	`date`	Trip processing date
sampledRoute	`object`	see Sampled route
matchedRoute	`object`	see Matched route
itineraryStatistics	`object`	see Itinerary statistics
weather	`object`	see Weather
itineraryData	`object`	see Itinerary data
ecoDriving	`object`	see Eco-driving score
advancedEcoDriving	`array[object]`	see Advanced eco-driving score
fuelEstimation	`object`	see Fuel estimation
advancedFuelEstimation	`array[object]`	see Advanced fuel estimation
energyEstimation	`object`	see Energy estimation
advancedEnergyEstimation	`array[object]`	see Advanced energy estimation
safety	`object`	see Safety score
advancedSafety	`array[object]`	see Advanced safety score
safetyEvents	`array[object]`	see Safety events
tireWear	`object`	see Tire and brake wear estimates
brakeWear	`object`	see Tire and brake wear estimates
speedingStatistics	`object`	see Speeding score
speedingEvents	`array[object]`	see Speeding events

### Sampled route The sampledRoute field provides a cleaned and enriched representation of the trip. Raw GPS data is reinterpolated to a uniform 1 Hz sampling rate and filtered to remove noise. Additional motion variables (such as acceleration and yaw rate) are then derived from the processed signal.

Name	Type	Description
time	`array[double]`	Relative time (in s)
latitude	`array[double]`	Latitude (in deg)
longitude	`array[double]`	Longitude (in deg)
velocity	`array[double]`	Speed (in km/h)
velocityLimits	`array[double]`	Speed limit (in km/h)
heading	`array[double]`	Heading (in deg)
distance	`array[double]`	Cumulative distance (in m)
elevation	`array[double]`	GPS elevation (in m)
yawRate	`array[double]`	Yaw rate (in rad/s)
longitudinalAccel	`array[double]`	Longitudinal acceleration (in m/s²)
lateralAccel	`array[double]`	Lateral acceleration (in m/s²)

### Matched route The matchedRoute field provides a map-matched version of the trip route. Raw GPS coordinates are snapped to the underlying road network to correct positioning errors and accurately reflect the roads travelled.

Name	Type	Description
latitude	`array[double]`	Snapped latitude shape (in deg)
longitude	`array[double]`	Snapped longitude shape (in deg)

{% hint style="info" %} The service returns an optimised subset of coordinates sufficient enough to accurately display the vehicle's path on a map, rather than returning matched coordinates for every input point. {% endhint %} ### Itinerary statistics 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). ![](https://lh4.googleusercontent.com/OTBTQqMP7kWCcv8AuyBp5bOdMVXA0PYuHjMWgZnwoKbW6cMptE13H8ck1QkvjJY71um4Mm77d7S9K1jGe6Rfql6ln7cUQe2gpHZusCf1vUhuOpw8PK10xE27XSByAn1X5W5fHJzI)

Name	Type	Description
distance	`double`	Total distance travelled (in m)
speedMean	`double`	Mean vehicle speed (in km/h)
tripDuration	`double`	Total trip duration (in s)
drivingDuration	`double`	Total duration of movement phases (in s)
idlingDuration	`double`	Total duration of idling phases (in s)
drivingPercentage	`double`	Percentage of vehicle movement
idlingPercentage	`double`	Percentage of idling phases
subdispNb	`int`	Number of sub-displacements detected during the trip
meteo	`int`	Weather condition code (see Weather code)
day	`boolean`	`true` if the trip occurred during the day, `false` if at night
weekDay	`boolean`	`true` if the trip occurred on a weekday (Mon–Fri), `false` if on a weekend (Sat–Sun)
transportationMode	`int`	Detected transportation mode (see Transportation mode)

### Weather The weather field contains the weather data at the time and location of the end of the trip (based on the trip’s last GPS location). Results are returned using both the provider's own classification and DriveQuant's unified weather coding system, which ensures consistency across providers.

Name	Type	Description
provider	`string`	Name of the weather data provider
providerCode	`double`	Weather condition code as defined by the provider
providerCondition	`double`	Weather condition label as defined by the provider
code	`double`	Weather condition code (see Weather code)
condition	`double`	Weather condition
temperature	`double`	Air temperature (in °C)
windSpeed	`double`	Wind speed (in km/h)
windDegree	`int`	Wind direction measured clockwise from North (in deg)
pressure	`int`	Atmospheric pressure (in hPa)
precipitation	`boolean`	Precipitation amount (in mm)
humidity	`boolean`	Relative humidity (in %)
cloud	`int`	Cloud coverage (in %)
visibility	`int`	Visibility distance (in m)
sunrise	`date`	Sunrise time at trip location
sunset	`date`	Sunset time at trip location

### Itinerary data The itineraryData field provides temporal and geographical context for the trip. It includes start and end times, as well as the departure and arrival locations resolved to city, postal code, state, and country level.

Name	Type	Description
startDate	`date`	Trip start date
endDate	`date`	Trip end date
departureCity	`string`	Name of the departure city
arrivalCity	`string`	Name of the arrival city
departureAddress	`string`	Full address of the departure location
arrivalAddress	`string`	Full address of the arrival location
departurePostalCode	`string`	Postal code of the departure location
arrivalPostalCode	`string`	Postal code of the arrival location
departureState	`string`	Name of the departure state
arrivalState	`string`	Name of the arrival state
departureCountry	`string`	Name of the departure country
arrivalCountry	`string`	Name of the arrival country

### Eco-driving score #### Description Eco-driving module performs 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.

Name	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
energyClass	`int`	See Energy Class: 0: energy class A 1: energy class B 2: energy class C 3: energy class D 4: 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

{% hint style="warning" %} 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 {% endhint %} #### 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 $$\mathrm{gCO\_2/km}$$. * Class E corresponds to 1.5 x the NEDC consumption of the vehicle expressed in $$\mathrm{gCO\_2/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 $$\mathrm{CO\_2}$$ emission « co2Emission » and the function below: ![Energy class definition](https://lh3.googleusercontent.com/o7zeQ4fozZs6TYCtPglmJlV-zaQ2cmq_qNLKyJsWbV-MkL-_s6lJj_l1J0evkI1qXekhyWly4xZX6TlofZw_-i8K9PY6aN801sW2v8xhJIH-csAkJJ4n6j9AOn_1V4G3guE-BdI2) ### Advanced eco-driving

Name	Type	Description
ecoDrivingContext	`array[object]`	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 {% hint style="warning" %} 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. {% endhint %} #### EcoDrivingContext

Name	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`	Road conditions

### 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 asseses 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:

Name	Type	Description
co2Mass	`double`	Total Mass of \mathrm{CO_2} (in kg)
co2Emission	`double`	Average Mass of \mathrm{CO_2} per unit of distance (in g/km)
fuelConsumption	`double`	Average fuel consumption (in l/100km)
fuelVolume	`double`	Total fuel consumption (in l)
idleFuelPercentage	`double`	Idle fuel consumption percentage
idleFuelConsumption	`double`	Idle fuel consumption per unit of time (in l/h)
idleCo2Emission	`double`	Idle \mathrm{CO_2} emission (in g/km)
idleCo2Mass	`double`	Idle \mathrm{CO_2} mass (in kg)
engineTempStatus	`boolean`	Engine cold start
coldFuelVolume	`double`	Cold engine fuel volume (in l)

### Advanced fuel estimation

Name	Type	Description
fuelEstimationContext	`array[object]`	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 {% hint style="warning" %} 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. {% endhint %} #### FuelEstimationContext

Name	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 \mathrm{CO_2} (in kg)
co2Emission	`double`	Average \mathrm{CO_2} emissions (in g/km)
fuelVolume	`double`	Total fuel consumption (in l)
fuelConsumption	`double`	Average fuel consumption (in l/100km)

### **Energy estimation** For electric vehicles, DriveQuant provides energy information instead of fuel estimation.

Name	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)

{% hint style="info" %} The **EnergyEstimation** sub-document is only present in the response body for electric vehicles. If the configured vehicle is a conventional vehicle, the energy estimation is not added in the response body. {% endhint %} ### **Advanced energy estimation** To provide more details on the energy consumption, the service may return the energy data for each driving context of the vehicle.

Name	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

{% hint style="info" %} The **AdvancedEnergyEstimation** sub-document is only present in the response body for electric vehicles. If the configured vehicle is a conventional vehicle, the energy estimation is not added in the response body. {% endhint %} ### Safety score

Name	Type	Description
safetyScore	`double`	Safety score (ranges from 3 to 10)
nbAdh	`int`	Number of times strong adherence threshold was exceeded
nbAccel	`int`	Number of strong accelerations
nbDecel	`int`	Number of strong decelerations
nbAdhCrit	`int`	Number of times critical adherence threshold was exceeded
nbAccelCrit	`int`	Number of critical accelerations
nbDecelCrit	`int`	Number of critical decelerations

{% hint style="warning" %} If trip is too short to be scored, `safetyScore` is set to 11. {% endhint %} ### Advanced safety score | Name | Type | Description | | ------------- | :-------------: | ---------------------------------------------------------------------------- | | safetyContext | `array[object]` | Array of [SafetyContext](/trip-analysis/rest-services/trip.md#safetycontext) | #### SafetyContext

Name	Type	Description
distance	`double`	Percentage of distance travelled in a road type
duration	`double`	Percentage of travel time spent in a road type
safetyScore	`double`	Safety score (ranges from 3 to 10)
nbAdh	`int`	Number of times strong adherence threshold was exceeded
nbAccel	`int`	Number of strong accelerations
nbDecel	`int`	Number of strong decelerations
nbAdhCrit	`int`	Number of times critical adherence threshold was exceeded
nbAccelCrit	`int`	Number of critical accelerations
nbDecelCrit	`int`	Number of critical decelerations
contextId	`int`	Road conditions

{% hint style="warning" %} 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. {% endhint %} ### Safety events 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.

Name	Type	Description
time	`double`	Time since the beginning of the trip (in s)
latitude	`double`	Latitude (in deg)
longitude	`double`	Longitude (in deg)
velocity	`double`	Vehicle speed (in km/h)
heading	`double`	Vehicle heading (in deg)
elevation	`double`	Altitude (in m)
distance	`double`	Distance travelled since the beginning of the trip (in m)
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 events normalized 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/s² | 2.0 | 2.5 | | Braking | m/s² | -1.8 | -2.4 | | Adherence limit | - | 0.2 | 0.3 | ### 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 component (tire or brake pad). This value is expressed in thousandth part of parts-per-million (ppm) which is a unit equivalent to a parts-per-billion (ppb). The worn mass fraction (tire or brake pad) is given for each individual trip. To obtain the total worn mass fraction, the sum of all the trip’s values must be done. The total worn mass fraction value is bounded between a minimum and a maximum value: * Minimum value = 0 ppb. If the total worn mass fraction is 0, the component (tire or brake pad) is assumed to have no wear. * Maximum value = $$10^9$$ppb. If the total worn mass fraction reaches the maximum value, this means that the component (tire or brake pad) is fully worn and must be replaced. For a tire, the maximum value for the mass fraction ($$10^9$$ppb) indicates that the tire has lost all its usable mass of rubber. This corresponds to a minimum tire tread height of 1.6 mm. *In France, a tire must legally have a minimum tread height of 1.6 mm over its entire circumference.* The wear calculation service estimates for each trip: * The worn fraction of front tires * The worn fraction of the rear tire * The worn fraction of the front brakes * The worn fraction of the rear brakes. Example of tire autonomy calculation: Assuming a vehicle that has performed $$N$$ trips, the tire autonomy ( $$d\_a$$ ) in km can be computed as follow: $$d\_a=f(w)\times\sum\_{k=1}^Nd\_i$$ with $$f(w)=\frac{1}{10^9\times\sum\_{k=1}^Nw\_i}-1$$ where ω is the tire worn mass fraction for the trip i (in ppb) and di is the distance (in km) of the trip i. The wear function f(ω) is a decreasing function that goes from infinity to zero. When f(ω) equals zero, the tire has no longer autonomy and must be replaced. This function is displayed below: ![](https://lh5.googleusercontent.com/zEF2xgPIxXRY9o34GjFjsHqdYeRMw47MlYGe-El9YmDiOnF-z8-TMgdU2q_OVwNKSA9hBlbodW5Mo3pI2TBQyUiU6ow5AlK98XR-NpGDPJcUjR6s43Nki0KR7QyrPbsFHUZ0X-R5) **Total tire and brake wear indicators** In order to facilitate the integration within a vehicle maintenance service, the DriveQuant API provides for all your requests the following set of data related to any component (tires or brakes): * The total distance traveled with a given component (Distance) * The level of wear of the considered component (TotalWear) * The remaining autonomy before a complete wear (Autonomy) * The average wear speed of the considered component (WearRate) * The total autonomy of the considered component is assumed to be equal to the total travelled distance plus the remaining autonomy (Distance + Autonomy). The diagram below illustrates the principle and the meaning of these quantities. The figure shows the evolution of the wear as a function of the distance traveled with the component. This is a generic representation that applies to a brake pad or a tire. ![](https://lh5.googleusercontent.com/KrfZ8VA8u4gGW4PKsWnW8qQ6PSv_VzpCGIXHMdKU8W-kcr_0-vRoSjG1R9IoYaDKm2oC9mptpFvRKASmGvId5GEjWqjiXyaJVPrkLdRFKvdthTIhbXreWgDL9qDSIPkz01kMJKaW) The autonomy of a set of tires or brakes is calculated for each axle (front and rear). For example, the most worn tire between the left tire and the right tire on the same axle is used.

Name	Type	Description
frontTireWear	`int`	Worn mass fraction of the front tires (right/ left) for current trip Unit : thousandths part of ppm = ppb Min. value = 0 / Max. value = 10^9
rearTireWear	`int`	Worn mass fraction of the rear tires (right/left) for current trip Unit : thousandths part of ppm = ppb Min. value = 0 / Max. value = 10^9
frontBrakePadWear	`int`	Worn mass fraction of the front brakes (right/left) for current trip Unit : thousandths part of ppm = ppb Min. value = 0 / Max. value = 10^9
rearBrakePadWear	`int`	Worn mass fraction of the rear brakes (right/left) for current trip Unit : thousandths part of ppm = ppb Min. value = 0 / Max. value = 10^9
frontTireDistance	`int`	Total distance analyzed for the front tires (in km) Min. value = 0 / Max. value = 1 000 000
rearTireDistance	`int`	Total distance analyzed for the rear tires (in km) Min. value = 0 / Max. value = 1 000 000
frontBrakeDistance	`int`	Total distance analyzed for the front brakes (in km) Min. value = 0 / Max. value = 1 000 000
rearBrakeDistance	`int`	Total distance analyzed for the rear brakes (in km) Min. value = 0 / Max. value = 1 000 000
frontTireAutonomy	`int`	Front tires remaining distance before change (in km) Min. value = 0 / Max. value = 1 000 000
rearTireAutonomy	`int`	Rear tires remaining distance before change (in km) Min. value = 0 / Max. value = 1 000 000
frontBrakeAutonomy	`int`	Front brakes remaining distance before change (in km) Min. value = 0 / Max. value = 1 000 000
rearBrakeAutonomy	`int`	Rear brakes remaining distance before change (in km) Min. value = 0 / Max. value = 1 000 000
frontTireTotalWear	`double`	Total worn mass percentage of the front tires (right/left) Min. value = 0% / Max. value = 100%
rearTireTotalWear	`double`	Total worn mass percentage of the rear tires (right/left) Min. value = 0% / Max. value = 100%
frontBrakeTotalWear	`double`	Total worn mass percentage of the front brakes (right/left) Min. value = 0% / Max. value = 100%
rearBrakeTotalWear	`double`	Total worn mass percentage of the rear brakes (right/left) Min. value = 0% / Max. value = 100%
frontTireWearRate	`double`	Average wear rate for the front tires (in %/1000km)
rearTireWearRate	`double`	Average wear rate for the rear tires (in %/1000km)
frontBrakeWearRate	`double`	Average wear rate for the rear brakes (in %/1000km)
rearBrakeWearRate	`double`	Average wear rate for the rear brakes (in %/1000km)

The wear rate measures the component wear (in %) as a function of distance. This variable allows to compare vehicles and to inform a vehicle fleet manager whose components are wearing out too quickly. The wear rate is related to the type of vehicle, the driving style, the type of road used and the driving condition. This is why its value can change if the typology of trips changes and if the vehicle is driven by several drivers who have different driving styles. ### Speeding score This service measures distance and driving time when the vehicle speed exceeds the speed limit. From this information, a speed limit score is calculated. The speed limit score is 10 if the overspeed distance is zero. The speed limit score decreases with the increase in the percentage of distance spent in overspeeding. The sensitivity function linking the relative speeding distance (in %) with the speeding score is shown below.

Log scale sensitivity function for speeding score

Speed score sensitivity function in decimal scale

This service returns a global (or trip) score for the entire trip as well as several sub-scores corresponding to each of the legal speed portions traveled during the trip. The global (or trip) score is the average of the sub-scores weighted by distance.

Name	Type	Description
distance	`int`	trip distance (in m)
duration	`int`	trip duration (in s)
speedingDistance	`int`	Distance travelled at a speed above the limit (in m)
speedingDuration	`int`	Duration spent at a speed above the limit (in s)
score	`double`	Speeding score
speedLimitContexts	`array[object]`	Array of SpeedLimitContexts

#### SpeedLimitContexts

Name	Type	Description
speedLimit	`int`	Speed limit for the portion of the trip (in km/h)
distance	`int`	Total distance for the portion of the trip limited at the speed limit value (in m)
duration	`int`	Total duration for the portion of the trip limited at the speed limit value (in s)
speedingDistance	`int`	Distance travelled at a speed above the limit within the speed limit portion (in m)
speedingDuration	`int`	Duration spent at a speed above the limit within the speed limit portion (in s)
score	`double`	Speeding score for a given speed limit portion

#### Response body example ```json { "speedingStatistics": { "distance": 6835, "duration": 613, "speedingDistance": 280, "speedingDuration": 14, "score": 9.55, "speedLimitContexts": [ { "speedLimit": 30, "distance": 21, "duration": 6, "speedingDistance": 0, "speedingDuration": 0, "score": 10.0 }, { "speedLimit": 50, "distance": 2378, "duration": 352, "speedingDistance": 169, "speedingDuration": 9, "score": 8.83 }, { "speedLimit": 70, "distance": 2153, "duration": 122, "speedingDistance": 111, "speedingDuration": 5, "score": 9.38 }, { "speedLimit": 90, "distance": 2283, "duration": 133, "speedingDistance": 0, "speedingDuration": 0, "score": 10.0 } ] } } ``` ### **Speeding events** The service that computes the speeding score also returns location-based information about overspeeding events. This type of information is used to indicate on a map the places on the trip where the speed of the vehicle exceeds the speed limit. The start and end positions of overspeeding segments are included in the SpeedingEvents table.

Name	Type	Description
time	`double`	Time since the beginning of the trip (in s)
latitude	`double`	Latitude (in deg)
longitude	`double`	Longitude (in deg)
type	`int`	1 = Overspeeding segment start point 0 = Overspeeding segment endpoint
index	`int`	Index of the speeding event in the matched route vector.

**Response body example** ```json "speedingEvents": [ { "longitude": 2.240690719770278, "latitude": 48.87119316290749, "time": 96, "type": 1, "index": 36 }, { "longitude": 2.2389993413999454, "latitude": 48.87022711541927, "time": 106, "type": 0, "index": 39 } ] ``` ## Error Response Format In some cases, the service may be unable to analyze a trip. The most common reasons are listed below.

HTTP status	Code	Description
400	1001	The mandatory field route is missing
400	1002	The mandatory field gpsDate is missing
400	1003	The mandatory field gpsVelocity is missing
400	1004	There are not enough GPS points to perform the analysis. Please make sure that your trip contains at least 10 GPS points
400	1005	The route data is inconsistent: each vector must have the same length
400	1006	The route data is not valid (velocity is too low)
400	1007	The route data sampling period is invalid (expected 1 Hz)
400	1008	The gpsDate field contains negative values
401	2000 - 2003	Unauthorized request (invalid or expired credentials)
409	3000	A similar trip has already been processed and stored with the same account
429	4000	You have reached your daily requests quota
429	4001	You have exceeded the rate limit for this endpoint. Please try again later
500	5000 - 5001	The service failed to process your data. Further analysis of your data is required
500	6000 - 6003	A configuration issue prevents the request from being analyzed
500	9999	An unexpected error has occurred

{% hint style="info" %} If a request fails, please contact our support team (via ) and include the HTTP status code and error code in your message. These details are essential for diagnosing the issue quickly. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.drivequant.com/analysis-services/trip-analysis-from-custom-data-source.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.