Overview

Samsara allows you to get GPS and onboard diagnostic data for all vehicles in your organization using the API. See Diagnostic Types for a list of diagnostics available.

There are three endpoints that allow you to query vehicle data:

Feed

The /fleet/vehicles/stats/feed endpoint should be used for synchronizing vehicle stat data.

This endpoint allows you to follow a feed of vehicle stat data. You repeatedly poll this endpoint to synchronize new vehicle stat events with each request.

You can poll the endpoint every 5 seconds to track real-time data, or you could poll every 24 hours for a daily sync. In either case, each time you poll the endpoint, you'll receive all vehicle stats updates since the last time you made a call.

This endpoint is better than the /history endpoint for synchronizing data because it is much less susceptible to "missing" data due to connectivity issues.

See Diagnostic Types for a full list of available stat types, and see the Telematics Sync guide details and sample code.

Historical Report

The /fleet/vehicles/stats/history endpoint should be used for retrieving a historical report of data between a given start time and end time.

This endpoint should not be used for continuous synchronization as it is more susceptible to "missing" data due to connectivity issues. For continuous synchronization, use the Feed endpoint instead.

This endpoint is most suited for cases such as:

• Back-filling historical vehicle stat data
• Ad-hoc querying of historical vehicle stat data

See Diagnostic Types for a full list of available stat types, and see the Historical Report guide for more details and sample code.

Snapshot

The /fleet/vehicles/stats endpoint returns the last known vehicle stat data for all vehicles.

This endpoint is suited for uses cases where you do not need to know every single vehicle state change, but rather you just require a "snapshot" of vehicle state at a given time.

For example, you can use this endpoint to:

• Get current vehicle stats values for all vehicles
• Get vehicle stat values for a specific point in time (i.e. a "snapshot" of vehicle state)
• Periodically refresh known vehicle state at a frequency that matches your use case

See Diagnostic Types for a full list of available stat types, and see the Telematics Snapshot guide for more details and sample code.

Diagnostic Types

All three vehicle stats endpoints allow you to query for the same set of vehicle stat types. The table below lists the available options for the types and decorations query parameters. Each stat updates at a different frequency, which is listed below.

Query Parameters

The vehicle stats endpoints provide two query parameters for selecting which vehicles stats to return:

• types
• decorations

types

Samsara stores each vehicle stat as a separate timeseries. The types parameter is required and indicates the main timeseries you'd like to return. You can return up to 3 in single query:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats/history' \
-d types='gps,engineStates,obdOdometerMeters' \
-d startTime='2020-07-05T00:00:00Z' \
-d endTime='2020-07-06T00:00:00Z' \
--header 'Authorization: Bearer <<token>>' \
-G

{
    "data": [
        {
            "id": "1234567890",
            "name": "Vehicle A",
            "gps": [....],
            "engineStates": [....],
            "obdOdometerMeters": [....]
        }
    ],
    "pagination": {....}
}

Note that the timestamps for each of the timeseries above (gps, engineStates, obdOdometerMeters) will be different.

decorations

You can use decorations to query for the value of one stat at the time of another. You can add up to 2 decorations. For example, you can decorate engineStates with gps and obdOdometerMeters readings:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats/history' \
-d types='engineStates' \
-d decorations='gps' \
-d startTime='2021-01-21T00:00:00Z' \
-d endTime='2021-01-22T00:00:00Z' \
--header 'Authorization: Bearer <<token>>' \
-G

{
    "data": [
        {
            "id": "1234567890",
            "name": "Vehicle A",
            "engineStates": [
                {
                    "time": "2021-01-21T20:22:39Z",
                    "value": "Off",
                    "decorations": {
                        "gps": {....},
                        "obdOdometerMeters": {....}
                    }
                }
            ]
        }
    ],
    "pagination": {....}
}

Now, you have the timestamp of all engineStates events, and the values of the gps and obdOdometerMeters at that time.

📘Aux Inputs

auxInput3-auxInput10 count as a single type against the limits. For example, you could list types=engineStates,obdOdometerMeters,auxInput3,auxInput4 because auxInput3 and auxInput4 count as a single stat type.
auxInput1 and auxInput2 still count as their own individual types.