Skip to main content

Overview

Three endpoints together give a complete picture of a vehicle’s current health: All three join on the vehicle IDDeviceId in position data, vehicleId in battery health, and the {id} path parameter in DTC codes. These are all the same legacy integer vehicle identifier.
DTC description and severity fields are present in the schema but are empty in the current backend. Display the raw code value and resolve meaning externally via the SAE J1979 or ISO 15031-6 standard. See Known Issues.

Step 1 — Get live position and status

GetLastPositionData returns the latest GPS fix for a single vehicle. Key health fields:
cURL
Python

Step 2 — Get battery health predictions

GetCompanyVehiclesBatteryHealth returns a paged list of battery predictions. Iterate over all pages using numberOfPages:
Python
Each item in items contains: Each prediction object has:
  • BatteryPredictionValue — label such as "Good", "Fair", "Poor"
  • PredictionConfidence — label such as "High", "Medium", "Low"
  • predictionForDay — integer (days ahead this prediction applies to)

Step 3 — Get DTC fault codes

GET /api/devices/{id}/dtc-codes returns the active diagnostic trouble codes from the vehicle’s OBD-II / CAN handler. The response is an array of arrays — flatten and deduplicate by code:
Python
description and severity on DtcDto are empty in the current backend. Only code is populated. Resolve fault meanings via the SAE J1979 / ISO 15031-6 standard or your OEM documentation.

Step 4 — Join on vehicle ID

With all three data sources fetched, merge them into a single per-vehicle record:

Limitations

  • DTC description and severity are empty. The DtcDto.description and DtcDto.severity fields are present in the schema but the backend does not populate them. Display the raw code value and resolve the meaning externally using the SAE J1979 or ISO 15031-6 fault code database.
  • Safety score is a separate call. GetSafetyScore returns per-trip riskLevel / riskScore (0–100) / duration / distance for a single vehicle over a date range. It is not included here because it operates at trip granularity, not vehicle-snapshot granularity — use it alongside trip replay for driver safety dashboards.
  • Battery prediction results are company-wide. GetCompanyVehiclesBatteryHealth fetches all vehicles in the company. For large fleets, cache this response and join locally rather than calling it once per vehicle.

Gotchas

  • DeviceId = vehicleId = DTC {id}. All three endpoints use the same integer vehicle identifier under different field names.
  • UtcTime has no Z suffix but is always UTC — treat it as UTC when parsing.
  • Voltage is external battery voltage. InternalBatteryVoltage (on the PositionDto) is the device’s internal backup battery, not the vehicle’s 12 V battery. Use Voltage for vehicle health.