Push Data

Introduction

The transfer of data collected by the SDK as well as driving indicators to a client server is a common need for users of the DriveQuant platform.

The information provided can be used for additional data processing, for archiving in databases or to display information on websites.

This is why DriveQuant offers the possibility to retrieve all the driving data collected by the mobile SDKs as well as all the driving indicators that result from our analyses. This is the purpose of the Push Data service.

Principle

The Push Data service sends the trip results after it is completed and analyzed. The process is described below.

  • When the trip recording's started (manually or automatically), DriveQuant's mobile SDK saves GPS data locally on the user's phone.

  • When the driver has finished his trip, the SDK automatically stops recording and requests the trip analysis service hosted on the DriveQuant's platform.

  • At the end of the processing, which takes about 2 seconds, the results are returned to the SDK and can be displayed in the driver's mobile application.

  • The data push service is scheduled every minute. Therefore, the maximum delay between the end of the trip analysis and the push to your server is 1 minute.

Configuration

Trip data are sent as a POST request to a client URL. The URL must be provided to DriveQuant in order to set up and activate the push data service.

The body of the request is a JSON object with a set of fields that contain the driving scores organized by categories and the raw data collected on the user smartphone stored in tables. An example of data in JSON format is given at the end of this section.

It is mandatory to configure a response code. If the post is accepted, we expect a status code of 200 (OK). In case of failure, for any answer other than 200, the service will attempt to post the data again. The retry strategy is described below.

If the service returns a 200 HTTP code while the data has not been accepted by the client server, then, there will be no further attempt to send the data.

Security

The trip results may include driver’s private information (location, username, email). For this reason, the two following security measures are mandatory:

  • The URL provided must be HTTPS.

  • You must set up a BasicAuth header on every request. To do so, you can send us the credentials that need to be added to each request.

Optionally, we can provide IP addresses from which requests are performed in case you need to secure your endpoint with IP whitelisting.

Automatic Retry

DriveQuant will retry to push the trip data in case of a HTTP error. In order to avoid too many consecutive retries, the push data replay will be performed one time per day from the day after a fail, this until the trip has been accepted.

Sample Message

The data included in a message posted by the push data service can be configured. The data available in this stream depends on the analytics services you subscribe to.

For security and user privacy reasons, we may delete or hash sensitive data.

The example below gives an exhaustive overview of the data resulting from DriveQuant's trip analysis. Definition of all these variables can be found in the related section.

The Push Data API specification can be downloaded here in OpenAPI YAML format.

{
"itinId": "6030ebe4ea60426b34e9b3bf",
"firstname": "Fistname",
"lastname": "Lastname",
"itineraryStatistics": {
"tripDuration": 1996.0,
"drivingDuration": 1737.0,
"idlingDuration": 259.0,
"drivingPercentage": 87.0,
"idlingPercentage": 13.0,
"distance": 15801.0,
"speedMean": 30.5,
"subdispNb": 60,
"meteo": 2,
"day": true,
"weekDay": false,
"transportationMode": 1
},
"ecoDriving": {
"score": 7.1,
"scoreAccel": -1.7,
"scoreMain": 0.9,
"scoreDecel": -0.5,
"stdDevAccel": 2.2006383,
"stdDevMain": 0.99105114,
"stdDevDecel": 3.797757,
"energyClass": 2
},
"fuelEstimation": {
"co2Mass": 2.691,
"co2Emission": 170.0,
"fuelVolume": 1.153,
"fuelConsumption": 7.3,
"idleFuelVolume": 0.049,
"idleFuelPercentage": 4.28,
"idleFuelConsumption": 0.696,
"idleCo2Emission": 1.625,
"idleCo2Mass": 0.115,
"engineTempStatus": true,
"coldFuelVolume": 0.018
},
"safety": {
"safetyScore": 9.1,
"nbAdh": 2,
"nbAccel": 0,
"nbDecel": 3,
"nbAdhCrit": 0,
"nbAccelCrit": 0,
"nbDecelCrit": 1
},
"advancedEcoDriving": {
"ecoDrivingContext": [
{
"contextId": 0,
"distance": 6.9,
"duration": 19.1,
"efficiencyScore": 11.0,
"scoreAccel": 6.0,
"scoreMain": 6.0,
"scoreDecel": 6.0
},
{
"contextId": 1,
"distance": 3.7,
"duration": 6.5,
"efficiencyScore": 6.1,
"scoreAccel": -2.8,
"scoreMain": 0.3,
"scoreDecel": 1.3
},
{
"contextId": 2,
"distance": 64.8,
"duration": 61.8,
"efficiencyScore": 6.7,
"scoreAccel": -1.7,
"scoreMain": 0.6,
"scoreDecel": -1.3
},
{
"contextId": 3,
"distance": 12.7,
"duration": 7.8,
"efficiencyScore": 6.6,
"scoreAccel": -1.8,
"scoreMain": 1.6,
"scoreDecel": 0.8
},
{
"contextId": 4,
"distance": 11.8,
"duration": 4.9,
"efficiencyScore": 8.4,
"scoreAccel": -1.1,
"scoreMain": 0.1,
"scoreDecel": -2.9
}
]
},
"advancedFuelEstimation": {
"fuelEstimationContext": [
{
"contextId": 0,
"distance": 6.9,
"duration": 19.1,
"co2Mass": 0.199,
"co2Emission": 179.0,
"fuelVolume": 0.085,
"fuelConsumption": 7.69
},
{
"contextId": 1,
"distance": 3.7,
"duration": 6.5,
"co2Mass": 0.099,
"co2Emission": 167.0,
"fuelVolume": 0.042,
"fuelConsumption": 7.139
},
{
"contextId": 2,
"distance": 64.8,
"duration": 61.8,
"co2Mass": 1.832,
"co2Emission": 176.0,
"fuelVolume": 0.785,
"fuelConsumption": 7.535
},
{
"contextId": 3,
"distance": 12.7,
"duration": 7.8,
"co2Mass": 0.264,
"co2Emission": 130.0,
"fuelVolume": 0.113,
"fuelConsumption": 5.549
},
{
"contextId": 4,
"distance": 11.8,
"duration": 4.9,
"co2Mass": 0.182,
"co2Emission": 96.0,
"fuelVolume": 0.078,
"fuelConsumption": 4.107
}
]
},
"advancedSafety": {
"safetyContext": [
{
"contextId": 0,
"distance": 6.9,
"duration": 19.1,
"nbAdh": 0,
"nbAccel": 0,
"nbDecel": 0,
"nbAdhCrit": 0,
"nbAccelCrit": 0,
"nbDecelCrit": 0,
"safetyScore": 11.0
},
{
"contextId": 1,
"distance": 3.7,
"duration": 6.5,
"nbAdh": 0,
"nbAccel": 0,
"nbDecel": 0,
"nbAdhCrit": 0,
"nbAccelCrit": 0,
"nbDecelCrit": 0,
"safetyScore": 11.0
},
{
"contextId": 2,
"distance": 64.8,
"duration": 61.8,
"nbAdh": 2,
"nbAccel": 0,
"nbDecel": 2,
"nbAdhCrit": 0,
"nbAccelCrit": 0,
"nbDecelCrit": 1,
"safetyScore": 9.1
},
{
"contextId": 3,
"distance": 12.7,
"duration": 7.8,
"nbAdh": 0,
"nbAccel": 0,
"nbDecel": 0,
"nbAdhCrit": 0,
"nbAccelCrit": 0,
"nbDecelCrit": 0,
"safetyScore": 10.0
},
{
"contextId": 4,
"distance": 11.8,
"duration": 4.9,
"nbAdh": 0,
"nbAccel": 0,
"nbDecel": 1,
"nbAdhCrit": 0,
"nbAccelCrit": 0,
"nbDecelCrit": 0,
"safetyScore": 8.0
}
]
},
"pollutants": {
"co": 436.34,
"hc": 105.19,
"nox": 43.45,
"soot": 0.01
},
"tireWear": {
"frontTireWear": 625151,
"rearTireWear": 194424,
"frontTireDistance": 6522,
"rearTireDistance": 6522,
"frontTireAutonomy": 25010,
"rearTireAutonomy": 159958,
"frontTireTotalWear": 20.6847961834131,
"rearTireTotalWear": 3.917838643900801,
"frontTireWearRate": 3.1593584519985076,
"rearTireWearRate": 0.5879650354629268
},
"brakeWear": {
"frontBrakePadWear": 652316,
"rearBrakePadWear": 490585,
"frontBrakeDistance": 6522,
"rearBrakeDistance": 6522,
"frontBrakeAutonomy": 51081,
"rearBrakeAutonomy": 70712,
"frontBrakeTotalWear": 11.322879923360654,
"rearBrakeTotalWear": 8.444911708095175,
"frontBrakeWearRate": 1.6040543118399773,
"rearBrakeWearRate": 1.1953688298028098
},
"safetyEvents": [
{
"time": 198.0,
"longitude": 2.2345499992370605,
"latitude": 48.865421295166016,
"velocity": 27.597404310389447,
"heading": 181.3752105740906,
"elevation": 21.428831625626,
"distance": 1803.0,
"type": 3,
"level": 1,
"value": -1.9984114049011923
},
{
"time": 886.0,
"longitude": 2.228440046310425,
"latitude": 48.829158782958984,
"velocity": 9.322159013829488,
"heading": 115.71003406053404,
"elevation": 35.0165024497636,
"distance": 5811.0,
"type": 1,
"level": 1,
"value": 0.2091391662960067
},
{
"time": 1179.0,
"longitude": 2.2220299243927,
"latitude": 48.776981353759766,
"velocity": 59.56077714321047,
"heading": 196.14873235105892,
"elevation": 169.4896656907427,
"distance": 8721.0,
"type": 3,
"level": 1,
"value": -1.851640380003413
},
{
"time": 1352.0,
"longitude": 2.2241098880767822,
"latitude": 48.76197814941406,
"velocity": 23.478607191677995,
"heading": 231.66262821151452,
"elevation": 96.56055945085538,
"distance": 11036.0,
"type": 1,
"level": 1,
"value": 0.2596086644093922
},
{
"time": 1352.0,
"longitude": 2.2241098880767822,
"latitude": 48.76197814941406,
"velocity": 23.478607191677995,
"heading": 231.66262821151452,
"elevation": 96.56055945085538,
"distance": 11036.0,
"type": 3,
"level": 2,
"value": -3.1478373502646355
},
{
"time": 1902.0,
"longitude": 2.2364699840545654,
"latitude": 48.742130279541016,
"velocity": 29.11161620369841,
"heading": 127.70357513427746,
"elevation": 76.72611043725985,
"distance": 14436.0,
"type": 3,
"level": 1,
"value": -2.095731316728654
}
],
"endDate": "2021-02-20T10:56:37.188+0000",
"itineraryData": {
"endDate": "2021-02-20T10:56:37.188+0000",
"startDate": "2021-02-20T10:23:22.188+0000",
"departureCity": "Puteaux",
"arrivalCity": "Verrières-le-Buisson",
"departureAddress": "Pont de Puteaux, 92800 Puteaux",
"arrivalAddress": "3 Rue Rimbaud, 91370 Verrières-le-Buisson"
},
"tripAdviceData": {
"id": "5da5b749e3f4d636f1f3376e",
"title": "Conseil de sécurité",
"message": "<br>Soit par surprise ou à cause d'un <b>dépassement de votre vitesse</b>, vous avez freiné fort à plusieurs reprises. En respectant bien les <b>distances de sécurité</b>, vous freinerez naturellement beaucoup plus progressivement et éviterez ainsi tous risques de collisions.<br>",
"theme": 0,
"adviceEvaluation": null
},
"tripAdvicesData": [
{
"id": "5da5b749e3f4d636f1f3376e",
"title": "Conseil de sécurité",
"message": "<br>Soit par surprise ou à cause d'un <b>dépassement de votre vitesse</b>, vous avez freiné fort à plusieurs reprises. En respectant bien les <b>distances de sécurité</b>, vous freinerez naturellement beaucoup plus progressivement et éviterez ainsi tous risques de collisions.<br>",
"messageId": "sfty-urban-day-dry-D030-brk-v01",
"theme": "SAFETY"
},
{
"id": "5da5b8c3e3f4d6370219ab7d",
"title": "Conseil d'éco-conduite",
"message": "Vous pouvez progresser.<br>Accélérez plus franchement pour atteindre rapidement votre vitesse de croisière.<br>Pour les véhicules équipés d’une boîte de vitesses manuelle, il faut passer le rapport supérieur dès que l’aiguille du compte tours atteint 1500 tours/minute pour un véhicule Diesel et aux alentours de 2000 tours/minute pour un véhicule à essence.",
"messageId": "eco-urban000-accW-v01",
"theme": "ECODRIVING"
}
],
"driverDistraction": {
"nbUnlock": 1,
"durationUnlock": 97.0,
"durationPercentUnlock": 4.86002640172576,
"distanceUnlock": 403.68833585416337,
"distancePercentUnlock": 2.5548277694713204,
"score": 1.9159997325752993,
"scoreUnlock": 6.7627283707197705,
"scoreCall": 1.9159997325752993,
"calls": [
{
"id": 0,
"start": 544.0035407543182,
"end": 634.0030286312103,
"durationS": 89,
"duration": 5,
"distanceM": 456,
"distance": 3,
"status": "OUTGOING",
"audioSystem": "SPEAKER",
"forbidden": true
}
]
},
"distractionEvents": [
{
"time": 539.0,
"latitude": 48.85495,
"longitude": 2.22616,
"velocity": 12.168000411987304,
"heading": -1.616703658463509,
"elevation": 23.05337370577991,
"distance": 3245.3746307904125,
"type": 1,
"duration": 97,
"index": 539
},
{
"time": 636.0,
"latitude": 48.85034,
"longitude": 2.22683,
"velocity": 45.22616824022174,
"heading": -1.3488582653419061,
"elevation": 29.8860134067469,
"distance": 3746.5653789286157,
"type": 2,
"duration": 1360,
"index": 636
}
],
"callEvents": [
{
"time": 544.0035407543182,
"latitude": 48.85475,
"longitude": 2.22616,
"velocity": 12.456000137329102,
"heading": -1.5768984084633124,
"elevation": 23.53374615925395,
"distance": 0.0,
"type": 3,
"duration": 1,
"index": 544,
"audioSystem": "SPEAKER",
"callType": "OUTGOING",
"forbidden": true
},
{
"time": 634.0030286312103,
"latitude": 48.85059,
"longitude": 2.22674,
"velocity": 46.44316055270816,
"heading": -1.3482454261409265,
"elevation": 30.170426377189013,
"distance": 456.0,
"type": 4,
"duration": 89,
"index": 634,
"audioSystem": "SPEAKER",
"callType": "OUTGOING",
"forbidden": true
}
],
"speedingEvents": [
{
"longitude": 2.240690719770278,
"latitude": 48.87119316290749,
"time": 96.0,
"type": 1,
"index": 36
},
{
"longitude": 2.2389993413999454,
"latitude": 48.87022711541927,
"time": 106.0,
"type": 0,
"index": 39
},
{
"longitude": 2.226948759849819,
"latitude": 48.8285248546614,
"time": 899.0,
"type": 1,
"index": 220
},
{
"longitude": 2.2247798257606703,
"latitude": 48.82771252373621,
"time": 910.0,
"type": 0,
"index": 229
},
{
"longitude": 2.220820796904408,
"latitude": 48.790306020720436,
"time": 1121.87393116951,
"type": 1,
"index": 374
},
{
"longitude": 2.222806342988146,
"latitude": 48.781090574187054,
"time": 1158.87393116951,
"type": 0,
"index": 409
},
{
"longitude": 2.221726988867627,
"latitude": 48.776698917142845,
"time": 1181.87393116951,
"type": 1,
"index": 428
},
{
"longitude": 2.221415682498137,
"latitude": 48.77728241347195,
"time": 1198.87393116951,
"type": 0,
"index": 449
},
{
"longitude": 2.2259807317602576,
"latitude": 48.77630605611952,
"time": 1222.87393116951,
"type": 1,
"index": 472
},
{
"longitude": 2.229023362169593,
"latitude": 48.77273423930304,
"time": 1252.87393116951,
"type": 0,
"index": 499
},
{
"longitude": 2.2291619672238197,
"latitude": 48.77164365290039,
"time": 1259.87393116951,
"type": 1,
"index": 502
},
{
"longitude": 2.229596580809962,
"latitude": 48.76831710988511,
"time": 1281.87393116951,
"type": 0,
"index": 525
}
],
"speedingStatistics": {
"distance": 15857,
"duration": 1727,
"speedingDistance": 1956,
"speedingDuration": 105,
"score": 4.82,
"speedLimitContexts": [
{
"speedLimit": 30,
"distance": 966,
"duration": 138,
"speedingDistance": 188,
"speedingDuration": 16,
"score": 1.09
},
{
"speedLimit": 50,
"distance": 11115,
"duration": 1367,
"speedingDistance": 1112,
"speedingDuration": 65,
"score": 3.0
},
{
"speedLimit": 70,
"distance": 1504,
"duration": 95,
"speedingDistance": 0,
"speedingDuration": 0,
"score": 10.0
},
{
"speedLimit": 80,
"distance": 655,
"duration": 62,
"speedingDistance": 0,
"speedingDuration": 0,
"score": 10.0
},
{
"speedLimit": 90,
"distance": 1617,
"duration": 65,
"speedingDistance": 656,
"speedingDuration": 24,
"score": 0.0
}
]
},
"vehicle": {
"typeIndex": 2,
"engineIndex": 1,
"power": 95.0,
"mass": 1270.0,
"engineDisplacement": 1368.0,
"gearboxIndex": 3,
"consumption": 6.4,
"autoGearboxNumber": 0.0,
"vehicleId": "dq_5d448140a7b11b00070db354",
"brand": "Fiat",
"model": "Tipo 2",
"version": "II 1.4 95 5P",
"year": 2016,
"declaredCarConsumption": -1.0,
"carPassengers": 1,
"dqIndex": "FiTi2016FT1P0095N005",
"frontTyreSize": "195/65/15",
"rearTyreSize": "195/65/15",
"length": 4.36,
"width": 1.79,
"height": 1.49,
"engineCylinderNb": 4,
"driveWheels": 0,
"extraData": {
"declaredYear": "2014",
"declaredConsumption": "6,8"
},
"statistics": {
"distance": 17125.132999999994,
"analyzedDistance": 6522.418999999997,
"estimatedYearDistance": 5879.961500000001
}
},
"username": "[email protected]",
"sampledRoute": {
"time": [
0.0,
2.0,
3.0,
//...
1994.87393116951,
1995.87393116951
],
"latitude": [
48.87772619263164,
48.877613119537884,
48.877562954154385,
// ...
48.73911801732323,
48.739126730485275
],
"longitude": [
2.2432564571520714,
2.243406746064082,
2.243463827807432,
// ...
2.239377922358742,
2.239456314545016
],
"velocity": [
31.068000411987306,
28.385972396534353,
24.6599490503239,
//...
21.724866902673966,
16.10954535584897
],
"heading": [
137.95486114769494,
136.72651816499405,
136.7328576980442,
//...
232.56937544415268,
230.3544309580917
],
"distance": [
0.0,
15.769984664741308,
22.619970512053502,
//...
15802.981461128833,
15807.456334838791
],
"elevation": [
27.177746203612408,
27.62722660817797,
27.984814573173303,
//...
66.78256729513335,
66.79191671802205
]
},
"vehicleStops": [
{
"time": 20.0009999275208,
"latitude": 48.877169941009676,
"longitude": 2.244076446951414,
"heading": 132.48435917284843,
"elevation": 34.03918631453839,
"distance": 85.1159528188692,
"stopDuration": 66
}
],
"smartphoneData": {
"phoneModel": "iPhone 6s",
"appBuildNumber": "4.18.8",
"osVersion": "14.3",
"osType": "iOS",
"sdkVersion": "1.9.1",
"uid": null,
"gpsDate": "2021-02-20T10:56:37.188+0000",
"phoneDate": "2021-02-20T11:00:40.572+0000",
"startMode": 4,
"batteryPercent": 36,
"tripCut": false,
"bluetoothEnabled": false
},
"matchedRoute": {
"latitude": [
48.8778,
48.87775,
48.87763,
//...
48.73876,
48.73891
],
"longitude": [
2.24338,
2.24345,
2.24361,
//...
2.23991,
2.24093
]
},
"metaData" : {
"customerStringData" : "<CUSTOMER STRING DATA>",
"customerJsonData" : "{\"customerTestNumber\" : 1, \"customerTestString\" : \"<CUSTOMER TEXT>\"}"
}
}