For certain maintenance and planning systems, you may want to generate work orders for planned or preventative maintenance based on vehicle usage, such as odometer or engine runtime.

This guide explains how to use the Vehicle Stats APIs to pull odometer and/or engine runtime data in order to generate work orders for planned maintenance.

The Vehicle Stats APIs

There are 3 different endpoints that you can choose from when determining how to retrieve odometer and/or engine runtime data:

• Retrieve the most recent stat readings for all vehicles:
  • API Endpoint: GET /fleet/vehicles/stats
• Retrieve historical stat readings over a given time range:
  • API Endpoint: GET /fleet/vehicles/stats/history
• Follow a feed of vehicle stats
  • API Endpoint: GET /fleet/vehicles/stats/feed

See the Telematics guide for a full explanation of these endpoints and for some sample code.

Odometer

Samsara supports two types of odometer readings:

1. Odometer directly from on-board diagnostics (OBD)
2. An approximation of odometer based on GPS measurements

Samsara will default to OBD odometer when the gateway can read it from the ECU. If Samsara cannot read OBD odometer from the ECU, Samsara will fall back to using GPS based odometer. This GPS-based odometer is only available if OBD odometer cannot be read. GPS-based odometer requires fleet admins to manually enter an odometer offset in order to calculate the approximation. See this knowledge base article for details.

The vehicle stats APIs allow you to retrieve both types of odometer values for your fleet using the following fields:

• obdOdometerMeters
• gpsOdometerMeters

When calling one of the vehicle stats APIs, you should submit both types of odometer to the types parameter to make sure that you're retrieving odometer values for all vehicles in your fleet. For example, the following call retrieves the most recent odometer readings for all vehicles in the fleet:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats?types=obdOdometerMeters,gpsOdometerMeters' \
--header 'Authorization: Bearer <<token>>'

The response will contain the odometer readings for vehicles that provide it via on-board diagnostics and those that use that GPS approximation. (Reminder: Samsara uses one odometer type or the other, but not both on the same vehicle).

{
    "data": [
        {
            "id": "281474977075805",
            "name": "Little Red",
            "obdOdometerMeters": {
                "time": "2020-11-02T05:37:42Z",
                "value": 241253891
            }
        },
        {
            "id": "281474977075806",
            "name": "Big Red",
            "gpsOdometerMeters": {
                "time": "2020-11-02T05:37:42Z",
                "value": 241253891
            }
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Engine Runtime

Samsara supports two types of engine runtime readings:

1. Engine runtime directly from on-board diagnostics (OBD)
2. An approximation of engine runtime based on when the gateway receives power from the engine (synthetic engine runtime)

Samsara will default to OBD engine runtime when the gateway can read it from the ECU. If Samsara cannot read OBD engine runtime from the ECU, Samsara will fall back to using synthetic engine runtime. Synthetic engine runtime is only available if OBD engine runtime cannot be read. Synthetic engine runtime requires fleet admins to manually enter an engine runtime offset in order to calculate the approximation. See this knowledge base article for details.

The vehicle stats APIs allow you to retrieve both types of engine runtime values by using the following fields:

• obdEngineSeconds
• syntheticEngineSeconds

When calling one of the vehicle stats APIs, you should submit both to the types parameter to make sure that you're retrieving engine runtime values for all vehicles in your fleet. For example, the following call retrieves the most recent engine runtime readings for all vehicles in the fleet:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats?types=obdEngineSeconds,syntheticEngineSeconds' \
--header 'Authorization: Bearer <<token>>'

The response will contain the engine runtime readings for vehicles that provide it via on-board diagnostics and synthetic approximation. (Reminder: Samsara uses one odometer type or the other, but not both on the same vehicle).

{
    "data": [
        {
            "id": "281474977075805",
            "name": "Little Red",
            "obdEngineSeconds": {
                "time": "2020-11-02T05:39:09Z",
                "value": 31599405
            }
        },
        {
            "id": "281474977075806",
            "name": "Big Red",
            "syntheticEngineSeconds": {
                "time": "2020-11-02T05:39:09Z",
                "value": 31599405
            }
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}