Push Crash Data

Introduction

The transfer of data collected by the DriveKit SDK during a collision and the crash insights are a common need for DriveQuant platform users. Crash data can be shared to:

• An assistance platform in order to alert an operator, who may decide to call in a tow truck or the emergency services.

• An insurance platform to open a claims report and use the data to accelerate decision-making and processing.

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

Principle

The crash data push service sends the crash analysis results right after it is completed and analysed.

The accident detection and confirmation cycle is described below.

• Crash detection is active only while a trip is being recorded. Trip recording is automatically triggered by the DriveKit SDK, which can detect a vehicle's displacement.

• The SDK constantly analyses the data collected by the phone's sensors during the trip. In case of a collision, the DriveKit SDK sends a portion of data to the DriveQuant platform for analysis.

• The DriveQuant platform performs signal processing on the raw data to extract sensitive indicators. These indicators are analysed by an algorithm trained to identify accidents by similarity with a confirmed accident database.

• As soon as the analysis is complete, the data is transmitted to your platform through the crash data push service.

Collision detection on the smartphone is instantaneous. Then, 20 seconds are required to record the post-collision data before sending the data to the DriveQuant platform. Crash confirmation on our platform takes less than a second. As soon as the crash is confirmed, the data is pushed. Overall, it takes less than 30 seconds from the time of collision to get accident data on your platform.

Configuration

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

The body of the request is a JSON object with a set of fields that contain the raw data and crash indicators.

It is mandatory to configure a response code. If the POST request is accepted, we expect a http status code 200 (OK). Any other code will be considered as a failure, and the service will attempt to send the crash data again every minute for 10 minutes. If the request still fails after these 10 attempts, the crash will be sent once a day until receiving a valid answer.

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 crash data push service needs to be secured:

• The provided URL must be using TLS (> 1.2) protocol (HTTPS).

• The service must be authenticated using either Basic Auth or OAuth2. OAuth2 is our preferred solution.

The OAuth2 authentication is shared by both trip push and crash push services.

Basic Auth configuration

The basic authentication configuration is the simplest to configure, though it is considered less secure. It only requires a username and a password.

OAuth2 configuration

The OAuth2 configuration requires an additional endpoint, which will be used to retrieve a token. This endpoint must be secured using basic authentication. The list of required fields is presented below:

• url : URL used to generate bearer token

• clientId : client id used in basic authentication

• clientSecret : client secret used in basic authentication

Additionally, specific headers or query parameters can be provided, should the OAuth2 endpoint require it:

• 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.

Sample Message

The crash data push API specification can be downloaded here in OpenAPI YAML format.

{
    "crashId": "63b17c517177432ebe069bbc",
    "customerId": "------------------",
    "driverId": "------------------",
    "userId": "------------------",
    "state": "CONFIRMED",
    "probability": 87,
    "predictionVersion": "1.0.0",
    "parameter": {
        "localTripId": "a40662ad636c82890df7528143a9b718ec8ffdcd0dee7cb1e7188598708144f7_1672575539740",
        "date": "2023-01-01T12:27:40.391+0000",
        "tripStartDate": "2023-01-01T12:18:59.740+0000",
        "gpsWindowNeg": 20,
        "gpsWindowPos": 20,
        "imuWindowNeg": 5,
        "imuWindowPos": 10,
        "imuFrequency": 100
    },
    "gps": {
        "timestamp": [
            0,
            0.98,
            2.01,
            "//... 37.98",
            38.98
        ],
        "latitude": [
            41.912932,
            41.912858,
            41.912822,
            "//... 41.910656",
            41.910656
        ],
        "longitude": [
            12.454223,
            12.454248,
            12.454268,
            "//... 12.454856",
            12.454856
        ],
        "velocity": [
            18.21,
            18.22,
            18.06,
            "//... 0",
            0
        ],
        "heading": [
            166.283,
            166.268,
            169.471,
            "//... 170.671",
            170.671
        ],
        "accuracy": [
            24,
            24,
            24,
            "//... 12",
            12,
            12
        ],
        "elevation": [
            70.5,
            70.3,
            68.4,
            "//... 70",
            70.1
        ]
    },
    "movements": {
        "timestamp": [
            0,
            9,
            20,
            "//... 14969",
            14980
        ],
        "accelerationX": [
            504,
            687,
            726,
            "//... 197//",
            192
        ],
        "accelerationY": [
            985,
            862,
            934,
            "//... 985//",
            981
        ],
        "accelerationZ": [
            20,
            230,
            314,
            "//... 57//",
            65
        ]
    },
    "gpsFeatures": {
        "index": 19,
        "time": 19,
        "latitude": 41.911104,
        "longitude": 12.454923,
        "crashType": 1,
        "stopTime": 26,
        "stopDuration": 7,
        "stopDistance": 21,
        "velocity": 26.94,
        "velocityMin": 0,
        "velocityMax": 38.16,
        "velocityClass": 2,
        "velocityPreNear": 33.59,
        "velocityPreFar": 31.42,
        "velocityPostNear": 16.77,
        "velocityPostFar": 0,
        "velocityOffsetNear": 16.82,
        "velocityOffsetFar": 33.59,
        "acceleration": -1.178,
        "accelerationMin": -1.472,
        "accelerationMax": 0.6,
        "heading": -1.41,
        "yawRate": 0.0092,
        "yawRateMin": -0.039,
        "yawRateMax": 0.0499,
        "available": true
    },
    "movementFeatures": {
        "index": 377,
        "module": 5.66,
        "time": 3.77,
        "energy": 19.07,
        "power": 1.27,
        "energyNear": 1.77,
        "energyFar": 0.63,
        "powerNear": 2.95,
        "powerFar": 1.07,
        "stdModuleNear": 0.96,
        "stdModuleFar": 0.13,
        "stdModuleOffset": 0.83,
        "entropyNear": -0.75,
        "entropyFar": -0.03,
        "entropyOffset": -0.72,
        "meanModuleNear": 1.41,
        "meanModuleFar": 1.01,
        "meanModuleOffset": 0.4
    },
    "userLocationUrl": "https://sharedtrip.drivequant.com/v1/CQD5hLox7"
}

How to use crash data in an assistance context?

The crash data push service is designed to automatically make an emergency call to an assistance operator.

The data shared via this service helps the operator to take the right decision to assist the driver. He can choose several types of action depending on the severity of the accident. For example:

• Call the driver to obtain confirmation of the accident.

• Send a towing vehicle in the case of mechanical damage.

• Send the emergency services if there is a severe accident.

Assessing the situation and the severity of the accident is critical and can be facilitated by the following indicators:

• the probability of an accident, expressed as a %.

• the speed at the time of collision. At high speeds, a vehicle stores more kinetic energy, which will cause more damage the force of the collision.

• the force of the impact measured by the smartphone. The severity of the accident increases with the force measured.

The service sends the coordinates of the accident at the time the collision was detected, as well as the coordinates of the vehicle for 20 seconds before and after the collision.

This data is displayed on a web page which can be opened using the URL link in the userLocationUrl field.

In addition to the characteristics and location of an accident, the DriveKit SDK measures and shares the smartphone's location after the accident.

In case of doubt, the operator can find out whether the driver is continuing his route or has stopped near the place of the accident.

This is useful information to evaluate the severity of the accident, as drivers will generally continue their trip if it is a minor accident or a false alarm (i.e. a false positive accident detection).

The data is displayed on a web page accessible via a unique URL link.

• The web page displays the crash data and the smartphone's coordinates updated every 10 seconds.

• The page only displays information about the trip during which an accident was detected and confirmed.

• The URL link expires after 24 hours.

Display of a user's location during a trip: the green pinpoint indicates the collision location and the blue dots represent the user's locations after the collision refreshed each 10 seconds.