Skip to main content

Samsara Ground Intelligence

The Samsara Ground Intelligence feed in ArcGIS Velocity polls the Samsara Ground Intelligence API and ingests road issues, such as potholes, patched potholes, and road cracking, that Samsara detects from its connected vehicle fleet.

Examples

The following are example use cases for the feed:

  • A public works department ingests newly detected or updated high-severity potholes every five minutes and routes them to a work-order system through a real-time analytic.

  • A city analyst configures the feed with the Load all matching issues each poll data access mode, leaves the Statuses filter empty, and polls every 15 minutes. A real-time analytic updates a feature layer with the latest observation for each issue ID. A web map filtered to Needs review and Reviewed displays the location, severity, and status of each unresolved road issue, so crews can plan repairs by priority.

Usage notes

Note the following when working with the feed:

  • You need a Samsara subscription that includes Ground Intelligence and an API key with the Read Ground Intelligence Issues scope to use this feed.

  • The feed polls Samsara at the rate specified in the Feed Polling Interval step of the configuration wizard.

  • The feed uses a predefined schema, so you do not need to define the schema or time and geometry fields. The feed does not return sample records during configuration.

  • This feed uses the updatedAtTime field as the Start time and the id field as the Track ID.

  • 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 the Samsara API to process all features.

Parameters

The following table describes the parameters for the feed:

Parameter

Description

Data type

API key

(required)

The Samsara API token used to authenticate requests. The token must have the Read Ground Intelligence Issues scope. Type the token value without the Bearer prefix.

Velocity stores the key as a secret and does not display it in the saved feed configuration.

String

Data access mode

Choose recently updated issues or all matching issues. Issues may be replayed at inclusive time boundaries or after failures, so use both id and updatedAtTime to identify duplicate updates. The following options are available:

  • Load recent issues each poll—Poll updates since the saved timestamp. The first poll looks back one polling interval. Velocity retains the saved timestamp when the feed stops or restarts.

  • Load all matching issues each poll—Re-emit every matching issue with no time filter. This is suitable for ancillary joins. Increase the interval for large populations so each poll can finish before the next one begins.

The default option is Load recent issues each poll.

String

Issue types

(optional)

Limits the feed to the selected issue types: Pothole, Road cracking, or Patched pothole. Leave empty to ingest all issue types.

String

Statuses

(optional)

Limits the feed to issues with the selected statuses: Needs review, Reviewed, Resolved, or Dismissed. Leave empty to ingest all status types.

String

Severities

(optional)

Limits the feed to issues with the selected severities: Low, Medium, or High. Leave empty to ingest all severity types.

String

Region

(optional)

The regional Samsara API host where your Samsara organization is provisioned: US (api.samsara.com), EU (api.eu.samsara.com), or Canada (api.ca.samsara.com).

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

This parameter is in the Advanced options section.

String

Additional logging

(optional)

Turn on the Enable Request Logging option to log HTTP requests and responses issued by Velocity to the Samsara Ground Intelligence API. Request logs can contain API credentials and returned issue data. Restrict access and remove sensitive information before sharing logs.

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.

The Enable Request Logging option is in the Advanced options section and is off by default.

Boolean

Considerations and limitations

Consider the following when using the feed:

  • The feed ingests Ground Intelligence issues. It does not ingest watchpoints or change issue statuses in Samsara.

  • Filters return only matching issues. If an issue no longer matches a filter, the feed does not send a deletion event or remove the issue from a feature layer. To maintain a current view of issue status, ingest all statuses and filter the resulting layer or map.

  • With Load recent issues each poll, Velocity maintains a separate saved timestamp for each region and filter configuration. A new configuration starts one polling interval before the first poll. Returning to a previous configuration resumes its saved timestamp.

  • When replacing the API key with one for a different Samsara organization, create a new feed.