Safety Events

List Safety Events

Endpoint:

GET /safety-events

Description:

Retrieve all safety events recorded by the system, such as harsh braking, speeding, or 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., "Crash").
`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=Crash" \
  --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., "Crash") 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": "Crash",
    "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.

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
Copy code
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.