Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started

Telematics

Get real-time or historical GPS and onboard diagnostic data

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:

EndpointDescription
/fleet/vehicles/stats/feedSynchronize vehicle stat data using a feed.
/fleet/vehicles/stats/historyPull a historical report of vehicle data between a given start time and end time.
/fleet/vehicles/statsGet a "snapshot" or last known stat values.

Feed

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

All vehicle stat events are provided as a feed through this endpoint. You repeatedly poll this endpoint to continuously synchronize vehicle stat data with your system.

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 this endpoint is much less susceptible to "missing" data due to connectivity issues.

See the Telematics Sync guide for more details and sample code.

History

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 use cases 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 the use cases such as:

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

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 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 has a different data rate, or frequency, at which events are recorded.

Stat TypeDescriptionData Rate
auxInput1-auxInput10Values for the auxiliary inputs to the Samsara Vehicle Gateway.Every time the auxiliary input changes state.
batteryMilliVoltsBattery voltage.Approx. every 2 minutes.
ecuSpeedMphSpeed in MPH from the ECU.Variable - approx. every 5 seconds.
engineRpmEngine RPM.Approx. every 2 minutes.
engineStatesState of the engine (On, Off, Idle).Every time engine state changes.
faultCodesFault codes including check engine light information.Whenever a fault code is reported by the ECU and after each complete emissions monitor drive-cycle.
fuelPercentsFuel level of the engine.Approx. every 1% change in fuel level.
gpsGPS data including lat/long, heading, speed, and a reverse geocoded address.Every 5 seconds when the vehicle is on. Every 5 minutes when the vehicle is off or idle.
gpsDistanceMetersDistance the Samsara Vehicle Gateway has traveled since being activated (according to GPS).Approx. every 1000 meters.
gpsOdometerMetersOdometer reading from GPS when OBD odometer cannot be pulled. See this article for details. For odometer directly from the ECU, see obdOdometerMeters.Approx. every 1000 meters.
nfcCardScansID card scans.Every scan of an ID card.
obdEngineSecondsRuntime of the engine pulled directly from the ECU. If Samsara does not have diagnostic coverage for a vehicle, this value will be omitted. For an approximation, see syntheticEngineSeconds.Every 3 minutes of engine runtime.
obdOdometerMetersOdometer pulled from the ECU. If Samsara does not have diagnostic coverage for a vehicle, this value will be omitted. For GPS odometer, see gpsOdometerMeters.Approx. every 30 seconds when the vehicle is in motion.
syntheticEngineSecondsEngine runtime approximated by the time the vehicle gateway gets power from the vehicle. See this article for details. For engine runtime directly from the ECU, see obdEngineSeconds.Approx. every 10 minutes when the vehicle is in on.

Query Parameters

types

Each stat type changes at its own rate. For example, gps can update as frequently as every 5 seconds, whereas engineStates might only change every few hours.

The types query parameter allows you to indicate which state changes you are interested in. For example, types=engineStates will provides engine state changes:

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

The response will contain a data array that provides an entry for each vehicle. In this case, we only have one vehicle called Little Red. The engineStates array will contain all the engine state changes over the given time period for that vehicle:

{
    "data": [
        {
            "engineStates": [
                {
                    "time": "2020-07-05T21:48:42Z",
                    "value": "On"
                },
                {
                    "time": "2020-07-05T21:56:24Z",
                    "value": "Off"
                }
            ],
            "id": "281474977075805",
            "name": "Little Red"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Multiple Stat Types

You may query up to 3 stat types in a single request. The types parameter accepts a comma-separated list, for example: types=engineStates,obdOdometerMeters.

📘

auxInput3-auxInput10 count as a single type against the limit of 3. 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.

Because each stat changes at different rates, additional arrays will be included in the response for each additional stat type:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats/history' \
--header 'Authorization: Bearer <<token>>' \
-d startTime='2020-07-05T00:00:00Z' \
-d endTime='2020-07-06T00:00:00Z' \
-d types='engineStates,obdOdometerMeters' \
-G
{
    "data": [
        {
            "engineStates": [
                {
                    "time": "2020-07-05T21:48:42Z",
                    "value": "On"
                },
                {
                    "time": "2020-07-05T21:56:24Z",
                    "value": "Off"
                }
            ],
            "obdOdometerMeters": [
                {
                    "time": "2020-07-05T21:49:33Z",
                    "value": 238562008
                },
                {
                    "time": "2020-07-05T21:51:22Z",
                    "value": 238563014
                },
                {
                    "time": "2020-07-05T21:53:53Z",
                    "value": 238564019
                },
                {
                    "time": "2020-07-05T21:55:36Z",
                    "value": 238565022
                }
            ],
            "id": "281474977075805",
            "name": "Little Red"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

If you want to combine stat data into a single list, see the decorations parameter below.

decorations

Decorations are available for the /feed and the /history endpoints.

Let's say you wanted to know where each engine state change occurred using GPS data. The types parameter by itself presents a challenge because you'd have an engineStates array, and a separate gps array.

You can combine stat types into a single list using the decorations query parameter.

If you want to know where each engine state change occurred, then you can decorate the engineStates stat type with the gps stat type:

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

Now each entry to the engineStates array will contain a decorations dictionary that includes the gps value at the time of that engine state change. The example below shows us that the vehicle turned On at 173 Butano Ave and turned Off at 144 W El Camino Real:

{
    "data": [
        {
            "engineStates": [
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.38195703,
                            "longitude": -122.05254263,
                            "headingDegrees": 0,
                            "speedMilesPerHour": 0,
                            "reverseGeo": {
                                "formattedLocation": "173 Butano Ave, Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:48:42Z",
                    "value": "On"
                },
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.36757924,
                            "longitude": -122.0333573,
                            "headingDegrees": 0,
                            "speedMilesPerHour": 0,
                            "reverseGeo": {
                                "formattedLocation": "144 W El Camino Real, Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:56:24Z",
                    "value": "Off"
                }
            ],
            "id": "281474977075805",
            "name": "Little Red"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Multiple Types with Decorations

If the types parameter includes multiple stat types, the decorations will be added to each stat type listed:

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

The list of engineStates includes a gps decoration for each engine state change and the list of odbOdometerMeters contains a gps decoration for each odometer reading:

{
    "data": [
        {
            "engineStates": [
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.38195703,
                            "longitude": -122.05254263,
                            "headingDegrees": 0,
                            "speedMilesPerHour": 0,
                            "reverseGeo": {
                                "formattedLocation": "Crespi Drive, Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:48:42Z",
                    "value": "On"
                },
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.36757924,
                            "longitude": -122.0333573,
                            "headingDegrees": 0,
                            "speedMilesPerHour": 0,
                            "reverseGeo": {
                                "formattedLocation": "Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:56:24Z",
                    "value": "Off"
                }
            ],
            "obdOdometerMeters": [
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.3817225,
                            "longitude": -122.05141374,
                            "headingDegrees": 106,
                            "speedMilesPerHour": 16.7760627932872,
                            "reverseGeo": {
                                "formattedLocation": "Crespi Drive, Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:49:33Z",
                    "value": 238562008
                },
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.37744183,
                            "longitude": -122.046635809,
                            "headingDegrees": 194.9,
                            "speedMilesPerHour": 35.2529776107532,
                            "reverseGeo": {
                                "formattedLocation": "South Mary Avenue, Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:51:22Z",
                    "value": 238563014
                },
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.371066,
                            "longitude": -122.04502763,
                            "headingDegrees": 105.8,
                            "speedMilesPerHour": 44.53631541795912,
                            "reverseGeo": {
                                "formattedLocation": "West El Camino Real, Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:53:53Z",
                    "value": 238564019
                },
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.36825551,
                            "longitude": -122.03366502,
                            "headingDegrees": 113.3,
                            "speedMilesPerHour": 16.239799570508232,
                            "reverseGeo": {
                                "formattedLocation": "Sunnyvale, CA"
                            }
                        }
                    },
                    "time": "2020-07-05T21:55:36Z",
                    "value": 238565022
                }
            ],
            "id": "281474977075805",
            "name": "Little Red"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Multiple Decorations

You may include up to 2 types in the decorations parameter, which accepts a comma-separated list. Each additional decoration will be included in the decorations array:

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

In this example, the obdOdometerMeters readings are added to the engineStates events as decorations, rather than in a separate array:

{
    "data": [
        {
            "engineStates": [
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.38195703,
                            "longitude": -122.05254263,
                            "headingDegrees": 0,
                            "speedMilesPerHour": 0,
                            "reverseGeo": {
                                "formattedLocation": "Crespi Drive, Sunnyvale, CA"
                            }
                        },
                        "obdOdometerMeters": {
                            "value": 238562008
                        }
                    },
                    "time": "2020-07-05T21:48:42Z",
                    "value": "On"
                },
                {
                    "decorations": {
                        "gps": {
                            "latitude": 37.36757924,
                            "longitude": -122.0333573,
                            "headingDegrees": 0,
                            "speedMilesPerHour": 0,
                            "reverseGeo": {
                                "formattedLocation": "Sunnyvale, CA"
                            }
                        },
                        "obdOdometerMeters": {
                            "value": 238565022
                        }
                    },
                    "time": "2020-07-05T21:56:24Z",
                    "value": "Off"
                }
            ],
            "id": "281474977075805",
            "name": "Little Red"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Notice that there are now only 2 odometer readings in the response. (We got 4 in when odbOdometerMeters was included in the types parameter). This is because now we are just requesting the odometer value at the time of the engine state change - not every single odometer reading available. This is the main difference between the types and decorations parameters.

Updated 12 days ago



Telematics


Get real-time or historical GPS and onboard diagnostic data

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.