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

See Configuration in the parent section.

The body of the request is a JSON object with a set of fields that contain the raw data and crash indicators. An example of data in JSON format is given at the end of this section.

Your service should respond with a 2xx http status code (typically 200 OK) when the push request is accepted. Any other code will be considered as a failure, and the service will attempt to send the data again as defined in the Retry Policy section.

If your service responds with a 2xx http status code, while the data has not been accepted by your platform, then there will be no further attempt to send the data!

Retry Policy

Every push request not successfully acknowledged by your service will be retried every minute for 30 minutes. After 30 unsuccessful attempts, the push data will be sent once a day until receiving a valid answer, or until the crash expires.

The expiration period of a crash whose probability is lower than 20% is at most 90 days. Therefore, if your push services are configured to receive both confirmed and unconfirmed crashes, any crash with a probability lower than 20% will be deleted after 90 days, even if it could not be sent to your platform.

Sample Message

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

Sample message (click to expand)

{
    "crashId": "676300727dba71011b728ddf",
    "customerId": "------------------",
    "driverId": "------------------",
    "userId": "------------------",
    "state": "CONFIRMED",
    "probability": 78,
    "predictionVersion": "1.3.0",
    "parameter": {
	"localTripId": "1b17c96284d3e7faf275d7c30142a89a0444b819fa75ead7601f15dd01deff26_1734540967.843855",
	"date": "2024-12-18T17:03:26.570+0000",
        "tripStartDate": "2024-12-18T16:56:07.844+0000",
        "gpsWindowNeg": 20,
        "gpsWindowPos": 20,
        "imuWindowNeg": 5,
        "imuWindowPos": 10,
        "imuFrequency": 100,
        "installationId": "9cc02aaa-92b4-cbd2-73fb-3dda6243dddf"
    },
    "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": 20,
    "time": 20,
    "latitude": 43.677391,
    "longitude": 1.532724,
    "crashType": 1,
    "stopTime": 35,
    "stopDuration": 15,
    "stopDistance": 20,
    "velocity": 22.94,
    "velocityMin": 0,
    "velocityMax": 41,
    "velocityClass": 2,
    "velocityPreNear": 29.31,
    "velocityPreFar": 37.41,
    "velocityPostNear": 18.36,
    "velocityPostFar": 0.52,
    "velocityOffsetNear": 10.95,
    "velocityOffsetFar": 28.79,
    "acceleration": -0.609,
    "accelerationMin": -1.653,
    "accelerationMax": 0.195,
    "heading": 0.44,
    "yawRate": 0.0609,
    "yawRateMin": -0.6862,
    "yawRateMax": 0.6683,
    "available": true
  },
  "movementFeatures": {
    "index": 503,
    "module": 11.21,
    "time": 5.03,
    "energy": 24.39,
    "power": 1.62,
    "energyNear": 5.01,
    "energyFar": 0.87,
    "powerNear": 8.35,
    "powerFar": 1.47,
    "stdModuleNear": 1.91,
    "stdModuleFar": 0.03,
    "stdModuleOffset": 1.88,
    "entropyNear": -1.45,
    "entropyFar": -0.27,
    "entropyOffset": -1.18,
    "meanModuleNear": 2.15,
    "meanModuleFar": 1.2,
    "meanModuleOffset": 0.95
  },
    "userLocationUrl": "https://sharedtrip.drivequant.com/v1/CQD5hLox7"
}

Service to get a sample message

To facilitate the validation of your data ingestion service for the push crash service, we provide a dedicated admin utility service. This tool allows you to generate sample requests based on your actual data and configuration, making it easier to test and verify your integration.

Below, you'll find a detailed description of the service, and you can also test it directly here.

Push crash data request

get

This service returns the body of the push crash data request that DriveQuant would send to the customer push crash service for a given crash.

Authorizations

API_Key

DriveKit-Admin-API-KeystringRequired

Path parameters

crashIdstringRequired

Crash unique identifier

Header parameters

DriveKit-Admin-API-KeystringRequired

Drivekit Admin API key

Responses

200

OK

application/json

crashIdstringOptional

customerIdstringOptional

driverIdstringOptional

userIdstringOptional

statestringOptional

probabilityintegerOptional

predictionVersionstringOptional

userLocationUrlstringOptional

401

Invalid DriveKit Admin API key

application/json

404

Crash Not Found

application/json

429

Too Many Requests

get

/drivekit/admin/push/crashes/{crashId}

HTTPcURLJavaScriptPython

GET /v3/drivekit/admin/push/crashes/{crashId} HTTP/1.1
Host: service.drivequant.com
DriveKit-Admin-API-Key: text
Accept: */*

Definitions

The content of the push crash data contains the crash status and the generic informations required for identification. It also includes the raw data, and the parameters used for crash analysis as described in the figure below.

Sample of crash data: velocity (top) and acceleration signal magnitude vector (SMV, bottom).

The content of the crash body request is described in the following section.

Crash identification and status

Field	Type	Description
crashId	string	Unique crash identifier
userId	string	Unique user identifier
state	string	Crash state Allowed values: CONFIRMED, UNCONFIRMED
probability	number	Crash probability
userLocationUrl	string	URL link that directs to a map displaying the user's location after a confirmed accident

Parameter

This section contains the crash recording configuration.

Field	Type	Description
localTripId	string	Unique trip identifier
date	date	Crash date Format: 'yyyy-MM-dd''T''HH:mm:ss.SSSZ'
tripStartDate	date	Trip start date Format: 'yyyy-MM-dd''T''HH:mm:ss.SSSZ'
gpsWindowNeg	integer	Recording duration of GPS data before detection (in s) Default value: 20
gpsWindowPos	integer	Recording duration of GPS data after detection (in s) Default value: 20
imuWindowNeg	integer	Recording duration of accelerometer data before detection (in s) Default value: 5
imuWindowPos	integer	Recording duration of accelerometer data after detection (in s) Default value: 10 s
imuFrequency	integer	Accelerometer signal recording frequency (in Hz) Default value: 100
installationId	string	Unique identifier of an installation

Gps

This section contains the GPS data recorded during the crash.

Field	Type	Description
timestamp	array[number]	Time (in s)
latitude	array[number]	Latitude (in deg)
longitude	array[number]	Longitude (in deg)
velocity	array[number]	Velocity (in km/h)
heading	array[number]	Heading (in deg)
accuracy	array[number]	GPS accuracy (in m)
elevation	array[number]	Elevation (in m)

Movements

This section contains the acceleration data recorded during the crash.

Field	Type	Description
timestamp	array[number]	Time (in ms)
accelerationX	array[number]	Acceleration component along the East axis in the Earth reference frame (in mG)
accelerationY	array[number]	Acceleration component along the North axis in the Earth reference frame (in mG)
accelerationZ	array[number]	Acceleration in the vertical direction, perpendicular to the Earth's surface (in mG)

How to use crash data in an assistance context?

The push crash data service is designed to automatically make an emergency call to an assistance operator. The data shared by this service in meant to help the operator take the right decision in assisting the driver, 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 percentage.

• The velocity 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 location of the user after the time of collision.

In addition to the characteristics and location of the accident, the DriveKit SDK also measures and shares the smartphone's live location after the accident. Therefore, the operator can easily determine whether the driver is continuing his route or has stopped near the place of the accident, which can help evaluating the severity of the accident.

The most relevant informations is displayed on a web page, which can be accessed from a unique URL provided in the userLocationUrl field of the push crash request's body (see above), and in a callback of the DriveKit SDK crash events listener (see android or iOS references):

• The web page displays the crash data and the smartphone's live location, updated every 10 seconds until the trip recording ends.

• The data displayed on the web page is limited to the trip during which the accident was detected and confirmed.

• The URL expires after 24 hours by default, or can be revoked anytime using the dedicated DriveKit admin API.

Display of a user's location during a trip: (a) the green pinpoint indicates the collision location; (b) the blue circles represent the user's location before and after the detected collision (by default, ± 20 s); (c) the blue dots represent the user's locations after the collision (refreshed every 10 s).