Get Safety Event

curl --request GET \
  --url https://api.withterminal.com/tsp/v1/safety/events/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Connection-Token: <connection-token>'

{
  "id": "sft_evt_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "sourceId": "123456789",
  "provider": "geotab",
  "type": "harsh_brake",
  "vehicle": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "startedAt": "2021-01-06T03:24:53.000Z",
  "metadata": {
    "addedAt": "2023-11-07T05:31:56Z",
    "modifiedAt": "2023-11-07T05:31:56Z"
  },
  "sourceType": "HARD_CORE_BRAKING_MESSAGE",
  "driver": "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "startLocation": {
    "longitude": -122.4194155,
    "latitude": 37.7749295
  },
  "endedAt": "2021-01-06T03:24:53.000Z",
  "endLocation": {
    "longitude": -122.4194155,
    "latitude": 37.7749295
  },
  "stats": {
    "maximumSpeed": 95.33,
    "averageSpeed": 95.33,
    "roadSpeedLimit": 95.33,
    "gForceForwardBackward": 1,
    "gForceSideToSide": 1,
    "heading": 25
  },
  "cameraMedia": {
    "frontFacing": {
      "available": true,
      "sourceId": "12345"
    },
    "rearFacing": {
      "available": true,
      "sourceId": "12345"
    }
  },
  "extensions": {
    "here": {
      "speedLimit": 95.33,
      "speedLimitSource": "posted",
      "truckSpeedLimit": 95.33,
      "roadName": "John St",
      "linkAttributes": {
        "countryCode": "<string>",
        "vehicleTypes": "<string>",
        "isUrban": "<string>",
        "transportVerified": "<string>",
        "functionalClass": "<string>",
        "controlledAccess": "<string>",
        "limitedAccessRoad": "<string>",
        "travelDirection": "<string>",
        "isBoatFerry": "<string>",
        "isRailFerry": "<string>",
        "isMultiDigitized": "<string>",
        "isDivided": "<string>",
        "isDividerLegal": "<string>",
        "isFrontage": "<string>",
        "isPaved": "<string>",
        "isRamp": "<string>",
        "isPrivate": "<string>",
        "hasPoiAccess": "<string>",
        "intersectionCategory": "<string>",
        "speedCategory": "<string>",
        "laneCategory": "<string>",
        "coverageIndicator": "<string>",
        "lowMobility": "<string>",
        "hasPublicAccess": "<string>",
        "routeTypes": "<string>"
      },
      "weather": {
        "latitude": 123,
        "longitude": 123,
        "temperature": 123,
        "dewPoint": 123,
        "humidity": 123,
        "pressure": 123,
        "windSpeed": 123,
        "windDirection": 123,
        "locationId": "<string>",
        "precipitationType": "<string>",
        "intensityOfPrecipitation": 123,
        "visibility": 123
      }
    }
  },
  "raw": []
}

GET

safety

events

{id}

Get Safety Event

curl --request GET \
  --url https://api.withterminal.com/tsp/v1/safety/events/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Connection-Token: <connection-token>'

{
  "id": "sft_evt_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "sourceId": "123456789",
  "provider": "geotab",
  "type": "harsh_brake",
  "vehicle": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "startedAt": "2021-01-06T03:24:53.000Z",
  "metadata": {
    "addedAt": "2023-11-07T05:31:56Z",
    "modifiedAt": "2023-11-07T05:31:56Z"
  },
  "sourceType": "HARD_CORE_BRAKING_MESSAGE",
  "driver": "drv_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "startLocation": {
    "longitude": -122.4194155,
    "latitude": 37.7749295
  },
  "endedAt": "2021-01-06T03:24:53.000Z",
  "endLocation": {
    "longitude": -122.4194155,
    "latitude": 37.7749295
  },
  "stats": {
    "maximumSpeed": 95.33,
    "averageSpeed": 95.33,
    "roadSpeedLimit": 95.33,
    "gForceForwardBackward": 1,
    "gForceSideToSide": 1,
    "heading": 25
  },
  "cameraMedia": {
    "frontFacing": {
      "available": true,
      "sourceId": "12345"
    },
    "rearFacing": {
      "available": true,
      "sourceId": "12345"
    }
  },
  "extensions": {
    "here": {
      "speedLimit": 95.33,
      "speedLimitSource": "posted",
      "truckSpeedLimit": 95.33,
      "roadName": "John St",
      "linkAttributes": {
        "countryCode": "<string>",
        "vehicleTypes": "<string>",
        "isUrban": "<string>",
        "transportVerified": "<string>",
        "functionalClass": "<string>",
        "controlledAccess": "<string>",
        "limitedAccessRoad": "<string>",
        "travelDirection": "<string>",
        "isBoatFerry": "<string>",
        "isRailFerry": "<string>",
        "isMultiDigitized": "<string>",
        "isDivided": "<string>",
        "isDividerLegal": "<string>",
        "isFrontage": "<string>",
        "isPaved": "<string>",
        "isRamp": "<string>",
        "isPrivate": "<string>",
        "hasPoiAccess": "<string>",
        "intersectionCategory": "<string>",
        "speedCategory": "<string>",
        "laneCategory": "<string>",
        "coverageIndicator": "<string>",
        "lowMobility": "<string>",
        "hasPublicAccess": "<string>",
        "routeTypes": "<string>"
      },
      "weather": {
        "latitude": 123,
        "longitude": 123,
        "temperature": 123,
        "dewPoint": 123,
        "humidity": 123,
        "pressure": 123,
        "windSpeed": 123,
        "windDirection": 123,
        "locationId": "<string>",
        "precipitationType": "<string>",
        "intensityOfPrecipitation": 123,
        "visibility": 123
      }
    }
  },
  "raw": []
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Connection-Token

string

required

The token returned when a user authenticated their account. This authorizes access to a specific account.

Example:

"con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4"

Path Parameters

string

required

The id of the safety event.

Query Parameters

expand

enum<string>

Expand resources in the returned response

Available options:

driver,

vehicle,

driver,vehicle,

vehicle,driver

raw

boolean

Include raw responses used to normalize model. Used for debugging or accessing unique properties that are not unified.

Response

string<ulid>

required

Example:

"sft_evt_01D8ZQFGHVJ858NBF2Q7DV9MNC"

sourceId

string

required

The ID used to represent the entity in the source system.

Example:

"123456789"

provider

string

required

Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under provider details.

Example:

"geotab"

type

enum<string>

required

Available options:

harsh_brake,

harsh_acceleration,

harsh_turn,

speeding,

crash,

near_crash,

tailgating,

cell_phone,

distracted,

drowsiness,

smoking,

seat_belt_violation,

stop_sign_violation,

red_light_violation,

unsafe_lane_change,

camera_obstruction,

eating_and_drinking,

rolling_stop,

unsafe_parking

vehicle

required

The ID of the vehicle that was involved in the event.

Example:

"vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC"

startedAt

string<date-time>

required

ISO 8601 date

Example:

"2021-01-06T03:24:53.000Z"

metadata

EntityMetadata · object

required

Internal metadata about the record.

Show child attributes

metadata.addedAt

string<date-time>

required

The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider's system.

metadata.modifiedAt

string<date-time>

required

The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system.

sourceType

string

The original event type as defined by the telematics provider's system

Example:

"HARD_CORE_BRAKING_MESSAGE"

driver

The ID of the driver that was driving during the event.

Example:

"drv_01D8ZQFGHVJ858NBF2Q7DV9MNC"

startLocation

Coordinates · object

Show child attributes

startLocation.longitude

number

required

Example:

-122.4194155

startLocation.latitude

number

required

Example:

37.7749295

endedAt

string<date-time>

ISO 8601 date

Example:

"2021-01-06T03:24:53.000Z"

endLocation

Coordinates · object

Show child attributes

endLocation.longitude

number

required

Example:

-122.4194155

endLocation.latitude

number

required

Example:

37.7749295

stats

object

Show child attributes

stats.maximumSpeed

number

Maximum speed of the vehicle in KPH

Example:

95.33

stats.averageSpeed

number

Average speed of the vehicle in KPH

Example:

95.33

stats.roadSpeedLimit

number

Speed Limit of the road in KPH

Example:

95.33

stats.gForceForwardBackward

number

The acceleration/breaking force as a factor of gravity (g).

Example:

1

stats.gForceSideToSide

number

The cornering (lateral) acceleration as a factor of gravity (g).

Example:

1

stats.heading

number

Heading of the vehicle (in degrees)

Example:

25

cameraMedia

Camera Media Reference · object

Show child attributes

cameraMedia.frontFacing

Camera Media Reference · object

The front facing camera media.

Show child attributes

cameraMedia.frontFacing.available

boolean

required

Indicates whether the camera media file is available for retrieval.

Example:

true

cameraMedia.frontFacing.sourceId

string

The identifier for the camera media file in the source system.

Example:

"12345"

cameraMedia.rearFacing

Camera Media Reference · object

The rear facing camera media.

Show child attributes

cameraMedia.rearFacing.available

boolean

required

Indicates whether the camera media file is available for retrieval.

Example:

true

cameraMedia.rearFacing.sourceId

string

The identifier for the camera media file in the source system.

Example:

"12345"

extensions

object

Includes data enriched via third-party vendors. See Extensions

Show child attributes

extensions.here

Here Safety Event Extension · object

Data obtained from the HERE platform.

Show child attributes

extensions.here.speedLimit

number

Speed limit of the road in KPH obtained from the HERE platform.

Example:

95.33

extensions.here.speedLimitSource

enum<string>

Source for speed limit obtained from the HERE platform.

Available options:

posted,

derived

Example:

"posted"

extensions.here.truckSpeedLimit

number

Speed limit for Trucks in KPH obtained from the HERE platform.

Example:

95.33

extensions.here.roadName

string

Name of the road obtained from the HERE platform.

Example:

"John St"

extensions.here.linkAttributes

object

Additional road attributes from HERE platform

Show child attributes

extensions.here.linkAttributes.countryCode

string

ISO country code of the road location

extensions.here.linkAttributes.vehicleTypes

string

Types of vehicles allowed

extensions.here.linkAttributes.isUrban

string

Indicates if the road is in an urban area

extensions.here.linkAttributes.transportVerified

string

Indicates if transport information is verified

extensions.here.linkAttributes.functionalClass

string

Road functional class according to HERE Maps:

0: Unknown
1: Functional Class 1
2: Functional Class 2
3: Functional Class 3
4: Functional Class 4
5: Functional Class 5

extensions.here.linkAttributes.controlledAccess

string

Indicates if the road has controlled access

extensions.here.linkAttributes.limitedAccessRoad

string

Indicates if it's a limited access road

extensions.here.linkAttributes.travelDirection

string

Direction of travel

extensions.here.linkAttributes.isBoatFerry

string

Indicates if it's a boat ferry route

extensions.here.linkAttributes.isRailFerry

string

Indicates if it's a rail ferry route

extensions.here.linkAttributes.isMultiDigitized

string

Indicates if the road is multi-digitized

extensions.here.linkAttributes.isDivided

string

Indicates if the road is divided

extensions.here.linkAttributes.isDividerLegal

string

Indicates if the divider is legal

extensions.here.linkAttributes.isFrontage

string

Indicates if it's a frontage road

extensions.here.linkAttributes.isPaved

string

Indicates if the road is paved

extensions.here.linkAttributes.isRamp

string

Indicates if it's a ramp

extensions.here.linkAttributes.isPrivate

string

Indicates if it's a private road

extensions.here.linkAttributes.hasPoiAccess

string

Indicates if there's POI access

extensions.here.linkAttributes.intersectionCategory

string

Type of intersection according to HERE Maps:

0: Unknown
1: Intersection Internal
2: Manoeuvre
3: Indescribable
4: Roundabout
5: Undefined Traffic Area
6: Special Traffic Figure

extensions.here.linkAttributes.speedCategory

string

Speed category according to HERE Maps:

0: Unknown
1: Over 130 km/h (80 mph)
2: 101-130 km/h (65-80 mph)
3: 91-100 km/h (55-64 mph)
4: 71-90 km/h (41-54 mph)
5: 51-70 km/h (31-40 mph)
6: 31-50 km/h (21-30 mph)
7: 11-30 km/h (6-20 mph)
8: Under 11 km/h (6 mph)

extensions.here.linkAttributes.laneCategory

string

Lane category according to HERE Maps:

0: Unknown
1: One lane
2: Two or three lanes
3: Four or more lanes

extensions.here.linkAttributes.coverageIndicator

string

Coverage indicator

extensions.here.linkAttributes.lowMobility

string

Low mobility indicator:

0: Unknown (Default)
1: Low mobility driving condition
2: Not low mobility driving condition

extensions.here.linkAttributes.hasPublicAccess

string

Indicates if there's public access

extensions.here.linkAttributes.routeTypes

string

Types of routes

extensions.here.weather

object

Weather conditions at the time of the event

Show child attributes

extensions.here.weather.latitude

number

Latitude of weather measurement location

extensions.here.weather.longitude

number

Longitude of weather measurement location

extensions.here.weather.temperature

number

Air temperature in Celsius

extensions.here.weather.dewPoint

number

Dew point temperature in Celsius

extensions.here.weather.humidity

number

Relative humidity percentage

extensions.here.weather.pressure

number

Air pressure

extensions.here.weather.windSpeed

number

Wind velocity in meters per second

extensions.here.weather.windDirection

number

Wind direction in degrees

extensions.here.weather.locationId

string

HERE weather location identifier

extensions.here.weather.precipitationType

string

Precipitation type

extensions.here.weather.intensityOfPrecipitation

number

Intensity of precipitation (measured in cm/h)

extensions.here.weather.visibility

number

Visibility (measured in km)

raw

RawData · object[]

Show child attributes

raw.provider

string

required

raw.schema

string

required

raw.extractedAt

string

required

raw.data

object

required

Example:

[]

List Safety Events Get Event Camera Media

⌘I

API Reference

Authentication

Vehicles

Drivers

Hours of Service

Vehicle Utilization

Trips

Devices

Safety

Groups

Trailers

IFTA

Connections

Data Management

Providers

Issues

Fault Codes

Webhook Events

Get Safety Event

Authorizations

Headers

Path Parameters

Query Parameters

Response