Safety Events

List Safety Events

Endpoint:

GET /safety-events

Description:

Retrieve all safety events recorded by the system, such as harsh braking, speeding, or near collisions, within a specified date range. Use optional filters to narrow results by vehicle, driver, or event type. Enhanced filtering and sorting are available through additional query parameters.

Query Parameters:

Parameter	Type	Description
`from`	`date-time`	Start date for fetching events. Example: `2024-10-01T00:00:00Z`.
`to`	`date-time`	End date for fetching events. Example: `2024-10-12T23:59:59Z`.
`vehicleIds`	`Array(string)`	(Optional) Filter events by specific vehicle IDs.
`driverIds`	`Array(string)`	(Optional) Filter events by specific driver IDs.
`eventType`	`String`	(Optional) Filter events by specific safety event types (e.g., "Near Collision").
`minIntensity`	`integer`	(Optional) Minimum intensity for filtering events.
`minRiskScore`	`integer`	(Optional) Minimum risk score for filtering events.
`limit`	`integer`	(Optional) Number of results to return per page. Defaults to 50.
`cursor`	`string`	(Optional) Pagination cursor for retrieving the next page of results.

Headers:

Header	Type	Description
`x-api-key`	`string`	Required for API authentication.
`Connection-Id`	`UUID`	Identifies the specific connection.

Example Request (cURL):

bash
Copy code
curl --request GET \
  --url "https://api.analytics.autos/safety-events?from=2024-10-01T00:00:00Z&to=2024-10-12T23:59:59Z&minRiskScore=70&eventTypes=speeding" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Response:

json
Copy code
{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "rawIncidentId": "raw_incident_1",
      "connectionId": "123e4567-e89b-12d3-a456-426614174000",
      "startedAt": "2024-10-13T16:12:52.505Z",
      "endedAt": "2024-10-13T16:12:52.505Z",
      "startLatitude": 34.052235,
      "startLongitude": -118.243683,
      "endLatitude": 34.052245,
      "endLongitude": -118.243695,
      "type": "Harsh Braking",
      "durationSeconds": 1,
      "acceleration": 5.2,
      "maxSpeed": 80,
      "minSpeed": 30
    }
  ],
  "next": "eyJvZmZzZXQiOjEwMH0"
}

Response Fields Explained:

Field	Type	Description
`id`	`string`	Unique ID of the safety event.
`rawIncidentId`	`string`	Identifier from the original data source.
`connectionId`	`string`	Links the event to the specific connection.
`startedAt`	`date-time`	Start timestamp of the event.
`endedAt`	`date-time`	End timestamp of the event.
`startLatitude`	`number`	Latitude of the event’s starting location.
`startLongitude`	`number`	Longitude of the event’s starting location.
`endLatitude`	`number`	Latitude of the event’s ending location.
`endLongitude`	`number`	Longitude of the event’s ending location.
`type`	`string`	Type of safety event (e.g., "Harsh Braking").
`durationSeconds`	`integer`	Duration of the event in seconds.
`acceleration`	`number`	Acceleration during the event (m/s²).
`maxSpeed`	`number`	Maximum speed during the event.
`minSpeed`	`number`	Minimum speed during the event.
`next`	`string`	Pagination cursor for retrieving the next page of results. If absent, no additional pages are available.

List Safety Event Types

Endpoint:

GET /safety-events/types

Description:

Retrieve a list of all possible safety event types. This endpoint provides details about supported event types (e.g., "Near Collision") to help categorize and analyze incidents.

Headers:

Header	Type	Description
`x-api-key`	`string`	Required for API authentication.
`Connection-Id`	`UUID`	Identifies the specific connection.

Example Request (cURL):

bash
Copy code
curl --request GET \
  --url https://api.analytics.autos/safety-events/types \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Response:

json
Copy code
[
  {
    "type": "Harsh Braking",
    "logo": "https://example.com/logo.png",
    "isExtended": true},
  {
    "type": "Near Collision",
    "logo": "https://example.com/logo.png",
    "isExtended": false}
]

Response Fields Explained:

Field	Type	Description
`type`	`string`	Name of the safety event type.
`logo`	`string`	URL of the logo representing the event type.
`isExtended`	`boolean`	Indicates if the event type includes extended metadata.

Supported Safety Event Types

The following safety event types may be returned by the Safety Events API.

Event Type	Description
`Harsh Braking`	A sudden or aggressive braking event.
`Hard Acceleration`	A sudden or aggressive acceleration event.
`Harsh Cornering`	A sharp or aggressive turning/cornering event.
`Harsh Motion`	A sudden vehicle movement or jolt that may indicate unsafe driving behavior.
`Speeding`	Vehicle speed exceeded the applicable speed threshold or speed limit.
`Tailgating`	Vehicle followed another vehicle too closely.
`Lane Departure`	Vehicle drifted or moved out of its lane unexpectedly.
`Near Collision`	A near-miss or close-proximity event with another object, vehicle, or road user.
`Accident`	A detected collision or crash-related event.
`Distracted Driving`	Driver appears distracted or not focused on the road.
`No Seatbelt`	Driver is not wearing a seatbelt while the vehicle is in motion.
`Partial Seatbelt`	Driver appears to be wearing the seatbelt incorrectly or only partially.
`Camera Obstruction`	Camera view is physically blocked or obstructed.
`Camera Misalignment`	Camera angle or position is incorrect and does not show the expected view.
`Driver Missing`	Interior camera does not show the driver when the driver is expected to be visible.
`Tampering`	Camera or device appears to have been intentionally blocked, moved, covered, or interfered with.

To retrieve the event types available for a specific connection, use:

curl --request GET \
  --url "https://api.analytics.autos/safety-events/types" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Example response:

[
  {
    "type": "Harsh Braking",
    "logo": "https://example.com/logo.png",
    "isExtended": true
  },
  {
    "type": "Near Collision",
    "logo": "https://example.com/logo.png",
    "isExtended": false
  },
  {
    "type": "No Seatbelt",
    "logo": "https://example.com/logo.png",
    "isExtended": true
  }
]

Incident Thumbnail URL

Endpoint:

GET /safety-events/{id}/thumbnails/{camPos}

Description:

Retrieve a thumbnail image of a safety event recorded by the system. Useful for quickly visualizing incidents.

Path Parameters:

Parameter	Type	Description
`id`	`string`	Unique ID of the safety event.
`camPos`	`string`	Camera position (e.g., "front", "rear").

Example Request (cURL):

bash
curl --request GET \
  --url "https://api.analytics.autos/safety-events/123e4567-e89b-12d3-a456-426614174000/thumbnails/front" \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Response:
Returns a thumbnail image URL.