Write Live Telematics Data to a CSV File

Stream live vehicle GPS pings with odometer decorations from the vehicle stats feed into a CSV file.

This recipe follows the /fleet/vehicles/stats/feed endpoint and writes each GPS ping to data.csv. It uses decorations to include odometer readings alongside each GPS event when available.

import csv
import os
import time

import requests

url = "https://api.samsara.com/fleet/vehicles/stats/feed"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['SAMSARA_API_TOKEN']}",
}

params = {
    "types": "gps",
    "decorations": "obdOdometerMeters",
}

with open("data.csv", "w", newline="") as csvfile:
    writer = csv.writer(csvfile)
    writer.writerow(["vehicleId", "timestamp", "latitude", "longitude", "odometer"])

    while True:
        response = requests.request("GET", url, headers=headers, params=params).json()

        for vehicle in response["data"]:
            for gps_ping in vehicle["gps"]:
                if "decorations" in gps_ping:
                    odometer = gps_ping["decorations"]["obdOdometerMeters"]["value"]
                else:
                    odometer = None

                writer.writerow([
                    vehicle["id"],
                    gps_ping["time"],
                    gps_ping["latitude"],
                    gps_ping["longitude"],
                    odometer,
                ])

        params["after"] = response["pagination"]["endCursor"]

        if response["pagination"]["hasNextPage"] is False:
            time.sleep(5)

How it works

1. Use the requests and csv modules

   The script uses requests for API calls and csv to write response data in CSV format.

2. Call /fleet/vehicles/stats/feed

   The /fleet/vehicles/stats/feed endpoint lets you follow a live feed of vehicle telematics data.

3. Configure the Authorization header

   Provide your API token in the Authorization HTTP header. See Authentication for details.

4. Select telematics data types

   The types parameter contains the primary stat type. This recipe uses gps.

5. Add decorations

   The decorations parameter adds ancillary stats to the primary stat event. This recipe adds obdOdometerMeters to each GPS ping when available.

6. Create the CSV file

   The script opens data.csv and writes headers for vehicle ID, timestamp, latitude, longitude, and odometer.

7. Use the end cursor

   The endCursor represents the last stat event received. Pass it as after in the next request to retrieve new feed updates.

8. Handle missing odometer values

   If Samsara cannot read an odometer value for a GPS ping, the decorations object is omitted and the script writes None.

Example decorated GPS reading

{
  "gps": [
    {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "time": "2021-03-30T00:00:00Z",
      "decorations": {
        "obdOdometerMeters": {
          "value": 1000
        }
      }
    }
  ]
}

For a list of available stat types, see Telematics.