Calculating Distance Traveled

Samsara captures multiple measures that you can use to calculate distance traveled over a given period of time. Here's a breakdown of the different measures and best practices for getting the most accurate measure available:

• Odometer readings from onboard diagnostics are the most accurate. These can be pulled from the Vehicle Stats API endpoints using the types=obdOdometerMeters query parameter. Additionally, these values populate the odometer fields in the cloud dashboard.

• GPS calculations can be used to approximate the distance traveled, if Samsara is unable to pull odometer readings from onboard diagnostics. This can be pulled from the Vehicle Stats API endpoints using one of the following query parameters:

  • types=gpsDistanceMeters - this is available for all vehicles and is the distance the vehicle gateway has traveled since it was first installed.
  • types=gpsOdometerMeters - this is only available for vehicles that Samsara is missing onboard odometer readings from. It is calculated via a manual odometer offset and GPS calculations since the offset was provided (see this article). This value populates the odometer fields in the cloud dashboard if the manual offset has been provided.

Here is some sample python code that pulls distance traveled for all vehicles. It uses obdOdometerMeters if available and gpsDistanceMeters otherwise.

import requests
import csv

base_url = 'https://api.samsara.com'
authorization = {
    'Authorization': 'Bearer <<token>>'
}
params = {
    'types': 'obdOdometerMeters,gpsDistanceMeters',
    'startTime': '2021-01-01T00:00:00Z',
    'endTime': '2021-02-01T00:00:00Z'
}

first_meter_measure = {}
last_meter_measure = {}
names = {}

# Paginate through all vehicles and store the first and last odometer/distance values
has_next_page = True
while has_next_page:
    resp = requests.request('GET', base_url+'/fleet/vehicles/stats/history', headers=authorization, params=params).json()
    for vehicle in resp['data']:
        names[vehicle['id']] = vehicle['name']
        if 'obdOdometerMeters' in vehicle:
            if vehicle['id'] not in first_meter_measure:
                first_meter_measure[vehicle['id']] = vehicle['obdOdometerMeters'][0]['value']
            last_meter_measure[vehicle['id']] = vehicle['obdOdometerMeters'][-1]['value']
        else:
            if vehicle['id'] not in first_meter_measure:
                first_meter_measure[vehicle['id']] = vehicle['gpsDistanceMeters'][0]['value']
            last_meter_measure[vehicle['id']] = vehicle['gpsDistanceMeters'][-1]['value']
    has_next_page = resp['pagination']['hasNextPage']
    params['after'] = resp['pagination']['endCursor']

# Write it to a csv
with open('miles_traveled.csv', 'w', newline='') as csvfile:
    writer = csv.DictWriter(csvfile,['vehicle_name', 'miles_traveled'])
    writer.writeheader()
    for vehicle_id in names.keys():
        miles_traveled = (last_meter_measure[vehicle_id] - first_meter_measure[vehicle_id])*0.000621371
        writer.writerow({'vehicle_name': names[vehicle_id], 'miles_traveled': miles_traveled})

🚧

The Distance field in the Activity Report in the cloud dashboard is calculated using Trips. Because Trips are segmented by detecting vehicle movement over a certain threshold, the distance can be slightly underestimated compared to odometer readings or full GPS calculations. This is something Samsara is actively working to improve, but you should use the methods described above for a more accurate measure of distance traveled.