Skip to main content

Samsara Safety Events

The Samsara Safety Events feed in ArcGIS Velocity connects to the Samsara Safety Events Stream and ingests safety events, such as harsh braking, collisions, and distracted driving, that Samsara detects with in-vehicle cameras and sensors. The feed ingests event attributes, including media URLs; it does not download media files.

Examples

The following are example use cases for the feed:

  • A logistics company ingests new safety events and uses a real-time analytic to alert the on-duty fleet supervisor whenever an event with a crash behavior label occurs, including the asset, driver, and location.

  • A city transportation department ingests safety events from its municipal fleet and runs hot spot analysis on harsh braking and following distance events to identify intersections that need traffic safety improvements.

Usage notes

Note the following when working with the feed:

  • You need a Samsara subscription that includes Safety Events and an API key to use this feed. The API key must have both the Read Safety Events & Scores and Read Camera Media scopes, and it must be issued for the region you select.

  • The feed polls Samsara at the rate specified in the Feed Polling Interval step of the configuration wizard. The minimum polling interval is five seconds.

  • The feed uses a predefined schema, so you do not need to define the schema or time and geometry fields. If no recent events are available, configuration can continue with the predefined schema without sample records.

  • This feed uses startMs as the Start time, endMs as the End time, and id as the Track ID.

  • The Asset IDs, Driver IDs, Tag IDs, and Assigned coaches filters each accept up to 2,000 comma-separated IDs. Leave a filter empty to include all values.

  • Velocity subscription license levels limit how much data a feed can ingest. If a feed exceeds the ingestion limit of your license level, Velocity writes a log message and sends an email to the administrative contact. If ingestion remains above the limit for more than an hour, Velocity stops the feed. Work with your Esri representative or Esri Technical Support to explore Velocity license levels that support your workflows if necessary.

  • Velocity automatically handles paginated responses from Samsara and processes all pages in a poll.

Parameters

The following table describes the parameters for the feed:

Parameter

Description

Data type

API key

The Samsara API key used to authenticate requests. The key must have the Read Safety Events & Scores and Read Camera Media scopes and must be issued for the selected region.

Select the matching region in the Advanced options section.

String

Query by time field

Determines which events the feed receives. Choose Updated time to re-emit events when their state changes or Created time to receive newly created events. Replay after a checkpoint reset can emit an event again.

The default is Updated time.

String

Region

The Samsara region for which the API key was issued: US (api.samsara.com) or EU (api.eu.samsara.com).

The default is US (api.samsara.com).

This parameter is in the Advanced options section.

String

Asset IDs

(optional)

Limits the feed to events for the specified assets. For example, 100234, 100235, 100236. Enter up to 2,000 comma-separated IDs.

If empty, events for all assets are ingested.

This parameter is in the Advanced options section.

String

Driver IDs

(optional)

Limits the feed to events for the specified drivers. Enter up to 2,000 comma-separated IDs.

If empty, events for all drivers are ingested.

This parameter is in the Advanced options section.

String

Tag IDs

(optional)

Limits the feed to events for assets and drivers with the specified tags. For example, 1001, 1002. Enter up to 2,000 comma-separated IDs.

If empty, all tags are included.

This parameter is in the Advanced options section.

String

Assigned coaches

(optional)

Limits the feed to events assigned to the specified coaches. Enter up to 2,000 comma-separated coach user IDs.

If empty, all coaches are included.

This parameter is in the Advanced options section.

String

Checkpoint reset ID

(optional)

Leave empty for normal operation. To recover from an unusable cursor, stop the feed and enter a new UUID. When you restart the feed, it clears the cursor once and replays events from the original checkpoint start time. The replay can produce duplicate events and a large backlog. Entering the last applied UUID does not reset the cursor again. Before resetting, verify the API key and filters.

This parameter is in the Advanced options section.

String

Behavior labels

(optional)

Limits the feed to events with the specified behavior labels such as Crash or Braking. Select one or more behavior labels.

If empty, all labels are included.

This parameter is in the Advanced options section.

String

Event states

(optional)

Limits the feed to events in the specified states: Needs review, Reviewed, Needs coaching, Coached, Dismissed, Needs recognition, or Recognized. Select one or more event states.

If empty, all states are included.

This parameter is in the Advanced options section.

String

Include VG-only events

(optional)

Includes events from devices that have a Vehicle Gateway but no camera. The default is off.

This parameter is in the Advanced options section.

Boolean

Enable Request Logging

(optional)

Turn on this parameter to log request details for troubleshooting. The feed redacts the API key and omits response bodies. The default is off.

Note:

Turn on this parameter for troubleshooting purposes and turn it off when troubleshooting is complete. After you turn it on, start the feed. The info-level logs are available on the feed logs page. Contact Esri Technical Support for help with troubleshooting, if necessary.

This parameter is in the Advanced options section.

Boolean