Push Trip 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 (driving scores and indicators) are returned to the SDK and can be displayed in the driver's mobile application.

  • Finally, trip data (GPS variables recorded by the smartphone's sensors, driving scores and indicators) are sent to your server.

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.

We recommend to configure endpoint security using an Oauth2 configuration.

For the configuration of the push service, please provide us with the following information:

  • url : URL used to generate bearer token

  • clientId : client id used in basic authentication

  • clientSecret : client secret used in basic authentication

  • headers : Headers added to the request

  • params : Parameters added to the request

The token will be renewed if the push data returns an http status code 401 or 403, depending on the customer endpoint configuration.

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 failure. If push data is still not accepted after 30 days, push data replay will not be performed anymore.

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.

If you want to receive the recorded GPS data in addition to the driving indicators, the request message body size will be larger. The size of the request message body is proportional to the duration of a trip because the GPS variables are recorded periodically at 1Hz. Here are some approximate orders of magnitude:

  • 10 min -> 40 kB

  • 30 min -> 110 kB

  • 60 min -> 200 kB

  • 120 min -> 420 kB

  • 150 min -> 580 kB

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,
    "drivingDuration": 1737,
    "idlingDuration": 259,
    "drivingPercentage": 87,
    "idlingPercentage": 13,
    "distance": 15801,
    "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,
    "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,
        "scoreAccel": 6,
        "scoreMain": 6,
        "scoreDecel": 6
      },
      {
        "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,
        "fuelVolume": 0.085,
        "fuelConsumption": 7.69
      },
      {
        "contextId": 1,
        "distance": 3.7,
        "duration": 6.5,
        "co2Mass": 0.099,
        "co2Emission": 167,
        "fuelVolume": 0.042,
        "fuelConsumption": 7.139
      },
      {
        "contextId": 2,
        "distance": 64.8,
        "duration": 61.8,
        "co2Mass": 1.832,
        "co2Emission": 176,
        "fuelVolume": 0.785,
        "fuelConsumption": 7.535
      },
      {
        "contextId": 3,
        "distance": 12.7,
        "duration": 7.8,
        "co2Mass": 0.264,
        "co2Emission": 130,
        "fuelVolume": 0.113,
        "fuelConsumption": 5.549
      },
      {
        "contextId": 4,
        "distance": 11.8,
        "duration": 4.9,
        "co2Mass": 0.182,
        "co2Emission": 96,
        "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
      },
      {
        "contextId": 1,
        "distance": 3.7,
        "duration": 6.5,
        "nbAdh": 0,
        "nbAccel": 0,
        "nbDecel": 0,
        "nbAdhCrit": 0,
        "nbAccelCrit": 0,
        "nbDecelCrit": 0,
        "safetyScore": 11
      },
      {
        "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
      },
      {
        "contextId": 4,
        "distance": 11.8,
        "duration": 4.9,
        "nbAdh": 0,
        "nbAccel": 0,
        "nbDecel": 1,
        "nbAdhCrit": 0,
        "nbAccelCrit": 0,
        "nbDecelCrit": 0,
        "safetyScore": 8
      }
    ]
  },
  "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,
      "longitude": 2.2345499992370605,
      "latitude": 48.865421295166016,
      "velocity": 27.597404310389447,
      "heading": 181.3752105740906,
      "elevation": 21.428831625626,
      "distance": 1803,
      "type": 3,
      "level": 1,
      "value": -1.9984114049011923
    },
    {
      "time": 886,
      "longitude": 2.228440046310425,
      "latitude": 48.829158782958984,
      "velocity": 9.322159013829488,
      "heading": 115.71003406053404,
      "elevation": 35.0165024497636,
      "distance": 5811,
      "type": 1,
      "level": 1,
      "value": 0.2091391662960067
    },
    {
      "time": 1179,
      "longitude": 2.2220299243927,
      "latitude": 48.776981353759766,
      "velocity": 59.56077714321047,
      "heading": 196.14873235105892,
      "elevation": 169.4896656907427,
      "distance": 8721,
      "type": 3,
      "level": 1,
      "value": -1.851640380003413
    },
    {
      "time": 1352,
      "longitude": 2.2241098880767822,
      "latitude": 48.76197814941406,
      "velocity": 23.478607191677995,
      "heading": 231.66262821151452,
      "elevation": 96.56055945085538,
      "distance": 11036,
      "type": 1,
      "level": 1,
      "value": 0.2596086644093922
    },
    {
      "time": 1352,
      "longitude": 2.2241098880767822,
      "latitude": 48.76197814941406,
      "velocity": 23.478607191677995,
      "heading": 231.66262821151452,
      "elevation": 96.56055945085538,
      "distance": 11036,
      "type": 3,
      "level": 2,
      "value": -3.1478373502646355
    },
    {
      "time": 1902,
      "longitude": 2.2364699840545654,
      "latitude": 48.742130279541016,
      "velocity": 29.11161620369841,
      "heading": 127.70357513427746,
      "elevation": 76.72611043725985,
      "distance": 14436,
      "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,
    "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,
      "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,
      "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,
      "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,
      "type": 4,
      "duration": 89,
      "index": 634,
      "audioSystem": "SPEAKER",
      "callType": "OUTGOING",
      "forbidden": true
    }
  ],
  "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
    },
    {
      "longitude": 2.226948759849819,
      "latitude": 48.8285248546614,
      "time": 899,
      "type": 1,
      "index": 220
    },
    {
      "longitude": 2.2247798257606703,
      "latitude": 48.82771252373621,
      "time": 910,
      "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
      },
      {
        "speedLimit": 70,
        "distance": 1504,
        "duration": 95,
        "speedingDistance": 0,
        "speedingDuration": 0,
        "score": 10
      },
      {
        "speedLimit": 80,
        "distance": 655,
        "duration": 62,
        "speedingDistance": 0,
        "speedingDuration": 0,
        "score": 10
      },
      {
        "speedLimit": 90,
        "distance": 1617,
        "duration": 65,
        "speedingDistance": 656,
        "speedingDuration": 24,
        "score": 0
      }
    ]
  },
  "vehicle": {
    "typeIndex": 2,
    "engineIndex": 1,
    "power": 95,
    "mass": 1270,
    "engineDisplacement": 1368,
    "gearboxIndex": 3,
    "consumption": 6.4,
    "autoGearboxNumber": 0,
    "vehicleId": "dq_5d448140a7b11b00070db354",
    "brand": "Fiat",
    "model": "Tipo 2",
    "version": "II 1.4 95 5P",
    "year": 2016,
    "declaredCarConsumption": -1,
    "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": "firstname.lastname@drivequant.com",
  "sampledRoute": {
    "time": [
      0,
      2,
      3,
      "//... 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,
      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
    ]
  },
  "energyEstimation": {
    "energy": 0,
    "energyConsumption": 0,
    "energyOpti": 0,
    "energyOptiConsumption": 0
  },
  "advancedEnergyEstimation": [
    {
      "contextId": 0,
      "distance": 6.9,
      "duration": 19.1,
      "energy": 0,
      "energyConsumption": 0,
      "energyOpti": 0,
      "energyOptiConsumption": 0
    },
    {
      "contextId": 1,
      "distance": 3.7,
      "duration": 6.5,
      "energy": 0,
      "energyConsumption": 0,
      "energyOpti": 0,
      "energyOptiConsumption": 0
    },
    {
      "contextId": 2,
      "distance": 64.8,
      "duration": 61.8,
      "energy": 0,
      "energyConsumption": 0,
      "energyOpti": 0,
      "energyOptiConsumption": 0
    },
    {
      "contextId": 3,
      "distance": 12.7,
      "duration": 7.8,
      "energy": 0,
      "energyConsumption": 0,
      "energyOpti": 0,
      "energyOptiConsumption": 0
    },
    {
      "contextId": 4,
      "distance": 11.8,
      "duration": 4.9,
      "energy": 0,
      "energyConsumption": 0,
      "energyOpti": 0,
      "energyOptiConsumption": 0
    }
  ]
}

Last updated