Vehicle Locations
GPS data is now available through the
/fleet/vehicles/statsendpoints, and you can combine GPS data with onboard diagnostic data in one API call. Head over to the Telematics guide for more details!
Samsara provides three different 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 in miles per hour, and reverse-geocoded location of the vehicle along with the time this data was generated.
This endpoint is paginated. See the Pagination guide for more details.
Empty or Short Pages
There is a chance you will see pages where
hasNextPage == true, but the page has an emptydataarray or few vehicles in the array.This is due to how Samsara collects and stores data and happens when vehicles do not have recent updates or are inactive.
There may be more pages with updates. 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.
Each time you call this endpoint with a given endCursor, you will receive all updates 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 the last event you received, and Samsara will send any updates since then 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>'
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 are not immediately available. Wait 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
}
}
Subsequent calls to the endpoint with new endCursors will result in 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 emptydataarray or few vehicles in the array.This is due to how Samsara collects and stores data and happens when vehicles do not have recent updates or are inactive.
There may be more pages with updates. 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 in miles per hour, 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 emptydataarray or few vehicles in the array.This is due to how Samsara collects and stores data and happens when vehicles do not have recent updates or are inactive.
There may be more pages with updates. 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 about 3 years ago