Overview

The /fleet/vehicles/stats endpoint is designed to give you a snapshot of telematics data at a given point in time.

The key feature is the time query parameter. This allows you to specify a point in time that you'd like to snapshot. The time parameter defaults to "now" if not provided.

There are many different types of telematics data that you can query for. See the Query Parameters section for a complete list.

Current Snapshot

The following request will provide you with a current snapshot of the locations of all of your vehicles:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats' \
--header 'Authorization: Bearer <<token>>' \
-d types='gps' \
-G

The response contains a data array, which contains an entry for each vehicle in the fleet. In this example, there are two vehicles: "Big Red", and "Little Red". Each vehicle contains a gps field which contains its last GPS ping.

{
    "data": [
        {
            "id": "212014918732717",
            "name": "Big Red",
            "gps": {
                "time": "2020-05-13T20:04:10Z",
                "latitude": 37.38229104,
                "longitude": -122.05264563,
                "headingDegrees": 0,
                "speedMilesPerHour": 0,
                "reverseGeo": {
                    "formattedLocation": "Butano Avenue, Sunnyvale, CA"
                }
            }
        },
        {
            "id": "281474977075805",
            "name": "Little Red",
            "gps": {
                "time": "2020-07-29T03:19:20Z",
                "latitude": 37.79272178,
                "longitude": -122.41765116,
                "headingDegrees": 0,
                "speedMilesPerHour": 0,
                "reverseGeo": {
                    "formattedLocation": "Hyde Street, San Francisco, CA"
                }
            }
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The gps field contains a time, which is the timestamp of the GPS ping. You may notice that Big Red's timestamp is 2 months older than Little Red's. This is because the endpoint returns the last known value for the stat type requested. In this case, Big Red has been retired, so its last GPS ping was from a long time ago. Currently, there is no way to filter out inactive or retired vehicles.

Historical Snapshot

If you want to get a snapshot of telematics data for a historical point in time, you can use the time query parameter. This is different from a Historical Report because it will simply provide the last known stat value for that point in time - as opposed to all the stat value readings for a given time range.

For example, the following request will tell me the location of all my vehicles at 2020-07-25T00:00:00Z:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats' \
--header 'Authorization: Bearer <<token>>' \
-d types='gps'
-d time='2020-07-25T00:00:00Z' \
-G

{
    "data": [
        {
            "id": "212014918732717",
            "name": "Big Red",
            "gps": {
                "time": "2020-05-13T20:04:10Z",
                "latitude": 37.38229104,
                "longitude": -122.05264563,
                "headingDegrees": 0,
                "speedMilesPerHour": 0,
                "reverseGeo": {
                    "formattedLocation": "Butano Avenue, Sunnyvale, CA"
                }
            }
        },
        {
            "id": "281474977075805",
            "name": "Little Red",
            "gps": {
                "time": "2020-07-24T23:57:11Z",
                "latitude": 37.3822605,
                "longitude": -122.05265544,
                "headingDegrees": 0,
                "speedMilesPerHour": 0,
                "reverseGeo": {
                    "formattedLocation": "Butano Avenue, Sunnyvale, CA"
                }
            }
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Pagination

If there are a lot of vehicles in your fleet, the response may be paginated. See the Pagination guide for details and sample code.