Telematics

Get real-time or historical GPS and onboard diagnostic data

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:

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" of last known stat values.

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.

Stat TypeDescriptionUpdate Frequency
ambientAirTemperatureMilliCThe ambient air temperature reading in millidegree Celsius.Approx. every 1 degree change while the vehicle is on.
auxInput1-auxInput10Values for the auxiliary inputs to the Samsara Vehicle Gateway.Every time the auxiliary input changes state.
barometricPressurePa The ambient barometric pressure reading in pascals..Approx. every 1 kPa change while the vehicle is on.
batteryMilliVoltsBattery voltage.Approx. every 2 minutes.
defLevelMilliPercent The Diesel Exhaust Fluid (DEF) level in milli percentage points.Approx. every 1% change in fluid level.
ecuSpeedMphSpeed in MPH from the ECU.Every 30 seconds or when the speed changes by more than 3 mph.
engineCoolantTemperatureMilliC Engine coolant temp.Approx. every 1 degree change while the vehicle is on.
engineLoadPercent Engine load percent.Approx. every 1% change in load percent.
engineOilPressureKPa Engine oil pressure in kilo pascals.Approx. every 1 kPa change while the vehicle is on.
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.
intakeManifoldTemperatureMilliC The intake manifold temperature reading in millidegree Celsius.Approx. every 1 degree change while the vehicle is on.
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

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.


What’s Next

See the links to the guides below for sample code.

Did this page help you?