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

Vehicle Locations

Get real-time or historical location data

As part of our new set of APIs, Samsara has released three new endpoints for retrieving vehicle location data:

  • List most recent vehicle locations
  • Follow a real-time feed of vehicle locations
  • Get historical vehicle locations

See below for descriptions of each of these scenarios.

List most recent vehicle locations

The GET /fleet/vehicles/locations endpoint allows you to list most recent vehicle location data for a "snapshot" of data. You can use the tagIds or vehicleIds parameters to optionally filter by tags or vehicles.

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/locations' \
  -H 'Authorization: Bearer <token>'
{
    "data": [
        {
            "id": "212014918234495",
            "name": "GDDY-CH2-XGP",
            "location": {
                "time": "2019-10-17T20:52:54Z",
                "latitude": 37.78392805,
                "longitude": -122.42708537,
                "heading": 0,
                "speed": 0,
                "reverseGeo": {...}
            }
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The response will contain a data array of the most recent locations for each vehicle (filtered by the tagIds or vehicleIds you supplied).

Each entry in the data array will contain the vehicle's id, name, and a location object that will contain the last known latitude, longitude, heading, speed, and reverse-geocoded location of the vehicle along with the time this data was generated.

If the locations of more than 512 vehicles are requested, the response will be paginated.

Empty or Short Pages

There is a chance you will see pages where hasNextPage == true, but the page has an empty data array or fewer than 512 vehicles in the array.

This is the result of vehicles whose locations are unknown. This is usually due to devices that have not been connected yet.

There may be more pages of vehicles with locations. It is important that you always keep paginating while hasNextPage == true.

Follow a real-time feed of vehicle locations

The GET /fleet/vehicles/locations/feed endpoint allows you to follow a real-time feed of vehicle location data, optionally filtered by tags or vehicles.

Calling this endpoint with a given endCursor will provide all updates to location data generated after that endCursor.

Calling this endpoint without a given endCursor will provide the most recent locations for the requested vehicles, and an initial endCursor for subsequent calls.

This pattern is specifically designed to ensure that you will eventually receive all data regardless of connectivity issues. Even if your data stream is momentarily interrupted, once connectivity is restored, your endCursor will tell us what the last event you received was, and any updates since then will be sent in your subsequent request.

Here's an example:

Initial call to /fleet/vehicles/locations/feed:

curl -X GET \
  https://api.samsara.com/fleet/vehicles/locations/feed \
  -H 'Authorization: Bearer <token>'

When a call to the feed endpoint is made without a cursor, the response will contain the most recent location data for the requested vehicles:

{
    "data": [
        {
            "id": "212014918119010",
            "name": "110065",
            "locations": [
                {
                    "time": "2019-10-18T22:42:31Z",
                    "latitude": 32.76448902,
                    "longitude": -96.84255775,
                    "heading": 63.2,
                    "speed": 7.023206971287679,
                    "reverseGeo": {...}
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "b864a4f6-0f90-4bbe-af48-171cacf62cca",
        "hasNextPage": false
    }
}

If hasNextPage is false, then new updates to the vehicles are not immediately available. We suggest waiting at least 5 seconds before requesting for updates:

Subsequent call to /fleet/vehicles/locations/feed with endCursor:

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/locations/feed?after=b864a4f6-0f90-4bbe-af48-171cacf62cca' \
  -H 'Authorization: Bearer <token>'

The response contains two updates to the given vehicle that occurred after the provided endCursor.

{
    "data": [
        {
            "id": "212014918119010",
            "name": "110065",
            "locations": [
                {
                    "time": "2019-10-18T22:42:43Z",
                    "latitude": 32.7646268,
                    "longitude": -96.842262369,
                    "heading": 61.7,
                    "speed": 10.378879841724329,
                    "reverseGeo": {...}
                },
                {
                    "time": "2019-10-18T22:42:51Z",
                    "latitude": 32.76475481,
                    "longitude": -96.84196494,
                    "heading": 61.8,
                    "speed": 13.689672313688064,
                    "reverseGeo": {...}
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "8e4fbc7b-24bf-4d23-9f3d-5d7826d34eaa",
        "hasNextPage": false
    }
}

Any subsequent calls to the endpoint with new endCursors will result in any updates that occurred after the given endCursor.

If hasNextPage is true, you can continue paginating through all the results. If hasNextPage is false, it is recommended that you wait 5 seconds before querying for new updates.

The following code demonstrates how to continuously poll for updates to location data:

import requests
import json
import time

url = "https://api.samsara.com/fleet/vehicles/locations/feed"
headers = {"Authorization": "Bearer <token>"}
endCursor = ""
querystring = {}

while True:
    if endCursor:
        querystring["after"] = endCursor
    response = requests.request("GET", url, headers=headers, params=querystring).json()
    vehicle_locations = response["data"]
    for vehicle in vehicle_locations:
        vehicle_id = vehicle["id"]
        name = vehicle["name"]
        for location in vehicle["locations"]:
            # Do something with each location update
            # For example:
            database.write(vehicle_id, location)
    endCursor = response["pagination"]["endCursor"]
    if response["pagination"]["hasNextPage"] == False:
        time.sleep(5)

Empty or Short Pages

There is a chance you will see pages where hasNextPage == true, but the page has an empty data array or fewer than 512 vehicles in the array.

This is the result of vehicles whose locations are unknown. This is usually due to devices that have not been connected yet.

There may be more pages of vehicles with locations. It is important that you always keep paginating while hasNextPage == true.

Get historical vehicle locations

The GET /fleet/vehicles/locations/history endpoint provides location data between a given start time and end time, optionally filtered by tags or vehicles.

The startTime and endTime are required parameters, and accept RFC 3339 timestamps. Timezones and/or millisecond precision are supported.

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/locations/history?startTime=2019-10-20T09:00:00Z&endTime=2019-10-21T09:00:00Z' \
  -H 'Authorization: Bearer <token>'
{
    "data": [
        {
            "id": "212014918174224",
            "name": "110169",
            "locations": [
                {
                    "time": "2019-10-20T09:02:30Z",
                    "latitude": 29.70608806,
                    "longitude": -95.32494387,
                    "heading": 0,
                    "speed": 0,
                    "reverseGeo": {...}
                },
                {
                    "time": "2019-10-20T09:07:31Z",
                    "latitude": 29.70608806,
                    "longitude": -95.32494387,
                    "heading": 0,
                    "speed": 0,
                    "reverseGeo": {...}
                },
              ...
                {
                    "time": "2019-10-21T08:55:21Z",
                    "latitude": 29.7054379,
                    "longitude": -95.39550712,
                    "heading": 0,
                    "speed": 0,
                    "reverseGeo": {...}
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The response will contain all of the location data for the requested vehicles between the given start time and end time.

The data array will contain an entry for each vehicle. The vehicle object will contain the vehicle's id, name, and a locations array that contains the vehicle's locations between the given start time and end time. Each entry in the locations array will contain the time the data was generated and the latitude, longitude, heading, speed, and reverse-geocoded location of the vehicle at that time.

The response will be paginated based on the number of vehicles and the length of the time range requested.

Empty or Short Pages

There is a chance you will see pages where hasNextPage == true, but the page has an empty data array or fewer than 512 vehicles in the array.

This is the result of vehicles whose locations are unknown. This is usually due to devices that have not been connected yet.

There may be more pages of vehicles with locations. It is important that you always keep paginating while hasNextPage == true.

Note that this endpoint is more susceptible to missed events due to connectivity issues than the feed endpoint is. If you request a very recent time range and the vehicle is experiencing connectivity issues, then there is a chance that events will not have been uploaded before you request them. If your use case dictates that you must continuously poll for very recent time ranges (an endTime less than 5 minutes ago), explore the feed endpoint as an alternative.

Location Update Frequency

While the vehicle is on, the Samsara device will send location updates approximately every 5 seconds. This means that if the device is on, but not moving, there may be consecutive events with the same data.

When the vehicle is off, the Samsara device will send a location update approximately every hour. If the device sense motion, the device will start sending location updates approximately every 5 seconds until the device stops moving again.

If the vehicle is in a garage, GPS connectivity may be impacted (and thus no location updates will be sent) even if the Samsara dashboard indicates that the vehicle is on.

Connectivity Issues

The Samsara device keeps a rolling log of the past 30 days of data. If there is a connectivity issue, the device will continue updating location according to the logic above. When connectivity is restored, these data points will be available via the API.

Updated 27 days ago



Vehicle Locations


Get real-time or historical location data

Suggested Edits are limited on API Reference Pages

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