The Samsara feed type in ArcGIS Velocity sends HTTPS requests to a specified Samsara API URL with relevant parameters.
Examples
The following are example uses of the Samsara feed:
- The Samsara API with URL https://api.samsara.com/fleet/vehicles/stats?types=gps is queried every five seconds to retrieve the current location of vehicles and relevant statistics.
- The Samsara API with URL https://api.samsara.com/fleet/equipment/locations is queried every minute to retrieve the current location of equipment.
- Any GET request endpoint from the Samsara API (v2) that returns a data and pagination object in the JSON response.
Usage notes
Keep the following in mind when working with the Samsara feed:
- The Samsara feed polls the specified Samsara API URL to load data at the rate specified by the Feed Polling Interval step of the configuration wizard.
Note:
The feed should not be configured to run more frequently than the Samsara API can return features.
- When a polling interval is set, the polling occurs at regular time intervals as opposed to the start time of the feed. For example, if a feed is set to poll for data every five minutes, and the feed is started at 8:03 a.m., the first request for data will occur at 8:05 a.m., the next at 8:10 a.m., and so on.
- The ArcGIS Velocity subscription license levels have limits to how much data can be ingested by a feed as summarized below. If feeds exceed the ingestion limit of your license level, a message is written to the logs and an email is sent notifying you that the limit has been reached. If ingestion of data remains above the limit for more than an hour, the feed is stopped. For more information about ArcGIS Velocity licensing, see Licensing.Work with your Esri representative or Esri Technical Support to explore Velocity license levels that support your workflows if necessary. License levels are as follows:
- Standard—Ingest and process data at 25 KB/second (approximately 100 events per second).
- Advanced—Ingest and process data at 250 KB/second (approximately 1,000 events per second).
- Dedicated—Ingest and process data at 2,500 KB/second (approximately 10,000 events per second).
- The URL parameters parameter supports feed global variables. By default, the feed global variables are converted to epoch time (milliseconds since January 1, 1970 UTC). Optionally, you can convert the feed global variables to epoch seconds (seconds since January 1, 1970) and a string date time format. The following outlines the feed analytic variables and the time they represent. The first time the feed runs after starting or restarting, the $feed.FeedLastScheduledStart time will be the current run time minus five minutes.
- $feed.FeedStartTime—The time the feed was started
- $feed.FeedScheduledStartTime—The time the next recurrence of the feed is scheduled
- $feed.FeedLastScheduledStartTime—The time the last recurrence of the feed was scheduled
- The Samsara feed automatically processes the JSON response from the Samsara API in the data object returned, and it flattens the JSON.
- You can flatten arrays and provide specific array flattening exemptions. Separate multiple array flattening exemptions with commas.
- Velocity automatically handles paginated responses from the Samsara API to process all features.
- After configuring the feed connection parameters, see Configure input data to learn how to define the schema and the key fields parameters.
Parameters
The following are the parameters for the Samsara feed:
| Parameter | Description | Data type |
|---|---|---|
URL | The Samsara API URL. This should be a GET request endpoint of the Samsara API as the feed is fetching data for ingestion. The URL, along with the URL parameters provided, control the data that is returned by the Samsara API. To find your Samsara API endpoint URL, visit Samsara API Overview. | String |
API Key | The Samsara API key. Provide the API key in the following form: samsara_api_<yourAPIKey>. | String |
URL parameters | Optional URL parameters to be included in the URL of the HTTP request sent to the specified Samsara URL. While parameters can also be set in the URL parameter, the URL parameters entered here will override any matching parameter supplied for the URL parameter. Parameters defined here will always be URL encoded. This parameter supports feed global variables. | Key-Value Pair |
Global variables | Convert the feed global variables to a custom datetime format. This parameter is optional For more information about setting a date format (epoch milliseconds, epoch seconds, and string format), refer to Date and time parameters. | String |
Additional logging | Specifies whether logging for raw HTTP requests and responses issued by Velocity to the Samsara URL will be enabled. This parameter is optional. Note:Only enable this parameter for troubleshooting purposes and disable it when troubleshooting is complete. Once enabled, start the feed, and the debug level logs will be available on the feed logs page. Contact Esri Technical Support for assistance with troubleshooting if necessary. | Boolean |
Considerations and limitations
The following are considerations and limitations when using the Samsara feed:
- A Samsara subscription and API key are required to use this feed type.
- The current generation of Samsara APIs use the RFC 3339 format for time stamps. To configure, set the Start Time parameter to the field with this string datetime and provide a string datetime format of yyyy-MM-dd'T'HH:mm:ss'Z'.
- The Samsara API can be polled as often as every five seconds.