✱ NOTE: If you are viewing this document on support.geotab.com, the API StatusData ID and Code table columns may be difficult to read. For an improved reading experience, we recommend you read the document here instead.

Preliminary notes

For the purposes of this guide, the term Electric Vehicle (EV) refers to plug-in hybrid EVs (PHEV) and battery EVs (BEV). The term does not include conventional hybrids, as they do not plug into an electric power source.

For a list of supported EV makes and models, refer to this spreadsheet.

The GO Plan rate plan is required to use these data diagnostics & API.

EV data diagnostics

! IMPORTANT: What about fault diagnostics/Diagnostic Trouble Codes (DTCs)?

Fault diagnostics/DTCs are communicated via the OBDII standard. However, since a main aspect of OBDII is emissions reporting, BEVs are unlikely to support OBDII because they lack tailpipe emissions - even though there are many fault diagnostics unrelated to emissions.

As a result, we do not support fault diagnostics for EVs that do not support OBDII.

Data diagnostics represent raw data signals received from the vehicle via the telematics device.

1. EV and FCEV data diagnostic values are retrievable via the StatusData object.

2. Visit the Geotab developer site for more information about retrieving diagnostic signals using the StatusData object.

3. EV data diagnostics basics

4. API StatusData ID	Code	Portal Name	Description
   DiagnosticEvPowertrainTypeId	9*	EV powertrain type (1 = unspecified / 2 = unspecified / 3 = unspecified / 4 = BEV / 5 = PHEV / 6 = FCEV)	Unit: as described The detected EV powertrain, using data communicated by the vehicle. 4 = BEV 5 = PHEV 6 = FCEV All other values should be interpreted as not detected as an EV, or not yet enough data. For a vehicle’s electric powertrain to be detected, the EV must be supported, and, in the case of a BEV or PHEV, it must have charged at least once. ✱ NOTE: EVs are automatically placed in groups for easy retrieval based on this diagnostic. We recommend you use group-based filtering. For the MyGeotab API, see Filtering on Detected EVs: EV Groups. For the MyGeotab Portal, see Finding and filtering EVs: powertrain and fuel type automatic groups. *Code is relative to the AI Model Source.
   DiagnosticStateOfChargeId	2118	Generic state of charge	Unit: % Refers to usable battery charge. While driving and charging, battery charge is reported every 1% change in value.

5. EV driving energy

6. Core

7. API StatusData ID	Code	Portal Name	Description
   DiagnosticElectricEnergyInId	3277	Electric vehicle battery total energy in while driving (since telematics device install)	Unit: kWh Total energy added to the battery from all non-charging sources since the GO device was installed, such as regenerative braking, driving down a hill, and engine charging in a hybrid. This is total energy when the vehicle is moving (speed > 0) and stationary/idling (speed = 0).
   DiagnosticElectricEnergyOutId	3278	Electric vehicle battery total energy out while driving (since telematics device install)	Unit: kWh Total energy leaving the battery since the GO device was installed, consumed for driving and operating the vehicle. This includes propulsion, and all auxiliary loads. This is total energy when the vehicle is moving (speed > 0) and stationary/idling (speed = 0).

8. ✱ NOTE: EV Electric Energy used is the difference between out (3277) and in (3278). Therefore, if there is more energy generated than consumed over a time period, the EV energy used will be negative.

9. Idling

10. API StatusData ID	Code	Portal Name	Description
    DiagnosticTotalLifetimeEnergyInWhileIdlingId	3339	Electric vehicle battery total energy in while idling (since telematics install)	Unit: kWh Total idling (speed = 0) energy added to the battery from all non-charging sources since the GO device was installed.
    DiagnosticTotalLifetimeEnergyOutWhileIdlingId	3340	Electric vehicle battery total energy out while idling (since telematics install)	Unit: kWh Total idling (speed = 0) energy leaving the battery since the GO device was installed.

11. For internal debugging only

12. ! IMPORTANT:This diagnostic is intended for internal debugging purposes. Geotab does not recommend customer use of this diagnostic, as accuracy is not guaranteed.

13. API StatusData ID	Code	Portal Name	Description
    a4kUpYGyQ4E2uoQTp-ed0Ow	2111	HV battery voltage	Unit: Volt Used by the GO device to calculate other diagnostics, such as Electric vehicle battery total energy out while driving (since telematics install) or Electric vehicle battery total energy in during DC charging (since telematics install).

14. EV charging

15. Core concepts

16. 1. HV Battery — The high-voltage (HV) battery of a BEV or PHEV.
    2. AC vs. DC Charging — During Alternating Current (AC) charging, power must be converted to Direct Current (DC) power prior to storage in the EV’s HV battery. The conversion happens in the EV’s on-board charger. In contrast, DC power is stored directly in the EV’s HV battery.

17. Charging status

18. API StatusData ID	Code	Portal Name	Description
    DiagnosticElectricVehicleChargingStateId	3289	Electric vehicle charging state (0 = not charging / 1 = AC charging / 2 = DC charging)	Unit: as described A value other than 0 indicates that the vehicle is charging; this is reported in real-time. Values of 1 or 2 additionally indicate the type of charging (AC or DC charging).

19. AC charging

20. API StatusData ID	Code	Portal Name	Description
    DiagnosticTotalLifetimeOnBoardChargerEnergyInDuringACChargingInId	3287	Electric vehicle on-board charger total energy in during AC charging (since telematics device install)	Unit: kilowatt hours (kWh) The total energy going into the EV’s on-board charger during AC charging since the GO device was installed.
    DiagnosticOnBoardChargerACInputPowerId	3292	Electric vehicle on-board charger AC input power	Unit: Watt (W) The power of the original AC charging source, going into the EV’s on-board charger.
    DiagnosticOnBoardChargerAcInputVoltageId	3290	Electric vehicle on-board charger AC input voltage	Unit: Volt The voltage of the original AC charging source, going into the vehicle’s on-board charger.
    DiagnosticTotalLifetimeOnBoardChargerEnergyOutDuringACChargingId	3288	Electric vehicle on-board charger total energy out during AC charging (since telematics device install)	Unit: kilowatt hours (kWh) The total energy going out of the EV’s on-board charger during AC charging since the GO device was installed.
    DiagnosticOnBoardChargerPowerDCOutId	3293	Electric vehicle on-board charger DC output power	Unit: Watt (W) The power going out of the EV’s on-board charger after converting AC power to DC power.
    DiagnosticTotalLifetimeBatteryEnergyInDuringACChargingId	3283	Electric vehicle battery total energy in during AC charging (since telematics device install)	Unit: kilowatt hours (kWh) The total energy going into the HV battery via AC charging since the GO device was installed.
    DiagnosticTotalLifetimeBatteryEnergyOutDuringACChargingId	3284	Electric vehicle battery total energy out during AC charging (since telematics device install)	Unit: kilowatt hours (kWh) The total energy going out of the HV battery during AC charging since the GO device was installed.
    DiagnosticElectricVehicleBatteryPowerId	3294	Electric vehicle battery power	Unit: Watt (W) Power measured at the battery. During DC charging, this is the only power reading available. During AC charging, this is available if higher quality power data sources are not available. A positive value indicates power is flowing out of the battery, such as for propulsion and auxiliary loads. A negative value indicates power is flowing into the battery, such as for charging from the plug, charging from the engine, and regenerative braking.

21. DC charging

22. API StatusData ID	Code	Portal Name	Description
    DiagnosticTotalLifetimeBatteryEnergyInDuringDCChargingId	3285	Electric vehicle battery total energy in during DC charging (since telematics device install)	Unit: kilowatt hours (kWh) The total energy going into the HV battery during DC charging since the GO device was installed.
    DiagnosticTotalLifetimeBatteryEnergyOutDuringDCChargingId	3286	Electric vehicle battery total energy out during DC charging (since telematics device install)	Unit: kilowatt hours (kWh) The total energy going out of the HV battery during DC charging since the GO device was installed.
    DiagnosticElectricVehicleBatteryPowerId	3294	Electric vehicle battery power	Unit: Watt (W) Power measured in the battery. During DC charging, this is the only power reading available. During AC charging this is available if higher quality power data sources are not available. A positive value indicates power is flowing out of the battery, such as for propulsion and auxiliary loads. A negative value indicates power is flowing into the battery, such as for charging from the plug, charging from the engine, and regenerative braking.

23. Additional EV Diagnostic Signals — non-standard support

24. The following are supported on select EV makes/models that make this information accessible.

25. API StatusData ID	Code	Portal Name	Description	Availability Limitations
    awCleUGqS10SjVyRrbg5kLA	2997	Electric vehicle battery charge remaining	Energy (kWh) remaining in the battery, which may be usable or actual.	Non-standard support
    aiC3laRAhVEOzOSvicbN9og	3254	Generic EV battery state of health	Unit: % Battery health, as reported by the vehicle.	Non-standard support
    aCiOQmMpe702NzD3cVCx4oA	3255	Generic EV battery maximum temperature	Unit: Celsius The maximum temperature of the battery at a specific point in time, across multiple measurement points.	Non-standard support
    az2JRiedliES6bw7pEe_UZg	3256	Generic EV battery minimum temperature	Unit: Celsius The minimum temperature of the battery at a specific point in time, across multiple measurement points.	Non-standard support
    anZTfpLFXgUq_iOB1Q-S9oA	3268	Generic EV battery median temperature	Unit: Celsius The median temperature of the battery at a specific point in time, across multiple measurement points.	Non-standard support
    aFGR6Q9guoUeiaAZI1fD6oQ	2659	Electric vehicle distance remaining	Unit: meters (m) Distance remaining, as calculated and reported by the EV.	Non-standard support

26. Fuel Cell Electric Vehicle (FCEV) data diagnostics

27. API StatusData ID	Code	Portal Name	Description
    DiagnosticFuelLevelId	98	Fuel level (percentage)	Unit: % Hydrogen fuel tank level.
    ahnXTf3D7m0KFnffudgKiEA	3297	Total hydrogen fuel used (since telematics device install)	Unit: grams Total hydrogen consumed since the GO device was installed.
    a-K-AomBxB0q6e1tZvzE8Wg	3296	Total idle hydrogen fuel used (since telematics device install)	Unit: grams Total hydrogen consumed while idling since the GO device was installed.

28. MyGeotab API

29. Exceptions

2. Exceptions to EV rules can be retrieved via the ExceptionEvent object

Visit the Geotab developer site for more information.

EV groups

There are automatically populated, built-in groups that allow you to quickly find and filter on EVs.

EVs are automatically classified based on their unique powertrain types:

1. GroupElectricHybridgPluginId: Contains all detected Battery Electric Vehicle (BEV) and detected Plug-in Hybrid (PHEV)
2. GroupBatteryElectricVehicleId (under GroupElectricHybridgPluginId): Contains all detected fully electric Battery Electric Vehicle (BEVs)
3. GroupPluginHybridElectricVehicleId (under GroupElectricHybridgPluginId): Contains all detected Plug-in Hybrid (PHEV)
4. GroupFuelCellElectricVehicleId: Contains all detected Fuel Cell Electric Vehicle (FCEV)

If you only want a specific EV powertrain (for example, Battery Electric Vehicles) to be returned when calling Get<Device>, you can specify the following:

groupSearch: {“id”:”GroupBatteryElectricVehicleId”}.

If you want to filter for a specific group (for example, Las Vegas) but only get back Battery Electric Vehicles in this group, you can use the following:

"groupFilterCondition":{"relation":"And","groupFilterConditions":[{"groupId":"b5B1C"},{"groupId":"GroupBatteryElectricVehicleId"}]}

Changing automatic group classifications

If the Device object does not have any built-in group IDs, it can be added by calling Set<Device> with the respective EV powertrain group ID. Set<Device> can also be used to modify or remove group IDs. Please refer to the additional notes below if you are performing this action.

1. If an asset is originally automatically classified:
2. 1. Calling Set<Device> and removing any automatically classified (by MyGeotab) asset group ID will result in that asset becoming part of GroupManuallyClassifiedPowertrainId (for example, removing the GroupBatteryElectricVehicleId that was assigned automatically by MyGeotab will result in the asset becoming part of GroupManuallyClassifiedPowertrainId).
   2. Calling Set<Device> and adding any powertrain group ID to an asset will also result in that asset becoming part of GroupManuallyClassifiedPowertrainId (for example, adding GroupBatteryElectricVehicleId will result in the asset becoming part of GroupManuallyClassifiedPowertrainId and GroupBatteryElectricVehicleId).
2. If an asset is manually classified:
3. 1. Calling Set<Device> and removing any powertrain group IDs from an asset will NOT remove GroupManuallyClassifiedPowertrainId. As long at the asset is assigned to GroupManuallyClassifiedPowertrainId, Geotab will NOT attempt to automatically classify the asset into any powertrain group.
   2. Calling Set<Device> and removing GroupManuallyClassifiedPowertrainId will result in that asset becoming part of the automatic classification queue again in MyGeotab (for example, if the asset has a corresponding powertrain automatically identified by the system, it will add the group ID in its next update). If you are performing this action, we recommend that you remove any other powertrain group IDs that the asset is associated with at the same time GroupManuallyClassifiedPowertrainId is removed, in order to keep track of when an asset is automatically classified back into a powertrain group.
   3. Calling Set<Device> and ONLY removing GroupManuallyClassifiedPowertrainId will still keep any group IDs the asset was previously associated with. However, this asset is now part of the automatic classification queue. If the system determines a new powertrain type, the group ID will be replaced with a new corresponding group ID.

Charge Events

The ChargeEvent data object summarizes important details about EV charging: where vehicles have been charging, when vehicles have been charging, and how much energy was delivered to the vehicles.

ChargeEvent

The ChargeEvent object can be requested from the API using the Get(...) and GetFeed(...) methods.

See ChargeEventSearch below to specify search filters on ChargeEvents.

ChargeEventSearch

ChargeEventSearch is the object used to specify the arguments when searching for a ChargeEvent, and can be passed into Get(...) to filter results.

ChargeEvents Frequently Asked Questions

Why does FuelAndEnergyUsed return different energy consumption values, when compared to ChargeEvents?

These two objects measure different things:

1. FuelAndEnergyUsed reports energy that leaves the battery while the vehicle is driving / idling.
2. ChargeEvents report energy that enters the charging port of the vehicle, while the vehicle is charging.

3. Because of losses in internal vehicle components, these measurements will be different.

4. Fuel and Energy used

5. The FuelAndEnergyUsed data object allows you to track the energy (BEVs and PHEVs) and fuel (ICE vehicles and PHEVs) used while driving (including idling and auxiliary energy use). This is key to understanding the energy efficiency of vehicles in your fleet.

6. FuelAndEnergyUsed

7. The FuelAndEnergyUsed object can be requested from the API using the Get(...) and GetFeed(...) methods.

8. See FuelAndEnergyUsedSearch below to specify search filters on FuelAndEnergyUsed.

9. Properties	Type	Description
   device	object	The device associated with the fuel and/or energy data
   DateTime	string*	The UTC date and time, following the ISO 8601 standard.
   Id	string*	The unique identifier for the specific Entity object in the Geotab system
   TotalEnergyUsedKwh	number	The amount of energy used in Kwh. Includes driving and idling.
   TotalFuelUsed	number	The volume of fuel used in Liters. Includes driving and idling.
   TotalIdlingEnergyUsedKwh	number	The amount of idling energy used in Kwh.
   TotalIdlingFuelUsedL	number	The volume of idling fuel used in Liters

10. FuelAndEnergySearch

11. FuelAndEnergyUsedSearch and can be passed into Get(...) to filter FuelAndEnergyUsed results.

12. Properties	Type	Description
    DeviceSearch	object	Search using a device ID or GroupSearch. See Filtering on Detected EVs: EV Groups.
    fromDate	string*	Search for results on or after a specific UTC date and time, following the ISO 8601 standard.
    toDate	string*	Search for results on or before a specific UTC date and time, following the ISO 8601 standard.

13. FuelAndEnergyUsed Frequently Asked Questions

14. Why does FuelAndEnergyUsed return different energy consumption values, when compared to ChargeEvents?

15. These two objects measure different things:

3. FuelAndEnergyUsed reports energy that leaves the battery while the vehicle is driving / idling.
4. ChargeEvents report energy that enters the charging port of the vehicle, while the vehicle is charging.

Because of losses in internal vehicle components, these measurements will be different.

What duration or distance does each record cover?

Each FuelAndEnergyUsed record covers the fuel and/or energy used per MyGeotab Trip.

Does TotalFuelUsed and TotalEnergyUsedKwh include TotalIdlingFuelUsedL and TotalIdlingEnergyUsedKwh values?

TotalFuelUsed and TotalEnergyUsedKwh already include their respective idling property values in the calculation. To get the driving only fuel or energy values, the idling property values must be subtracted from the total property values (e.g. TotalFuelUsed - IdlingFuelUsedL = Driving fuel used).

Battery Capacity and State of Health

The BatteryStateOfHealth data object allows you to track high voltage battery degradation over the lifetime of your BEVs and PHEVs. We use historical driving and charging data to estimate usable battery capacity.

BatteryStateOfHealth

The BatteryStateOfHealth object can be requested from the API using the Get(...) method.

See BatteryStateOfHealthSearch below to specify search filters when requesting data.

BatteryStateOfHealthSearch

BatteryStateOfHealthSearch is the object used to specify the arguments when searching for BatteryStateOfHealth data, and can be passed into Get(...) to filter results.

BatteryStateOfHealth Frequently Asked Questions

How is Battery State of Health calculated? Why is it null for some vehicles?

Battery State of Health = (usable battery capacity) / (original usable battery capacity)

Usable battery capacity is calculated for each specific vehicle. It is Geotab’s estimate of how much energy the battery can store, based on recent driving and charging events. One month of regular driving / charging is typically enough to generate a usable battery capacity estimate.

Original usable battery capacity is crowd-sourced from all vehicles with the same make / model / year / trim. The calculation of original capacity requires low odometer data from many different vehicles. Crowd-sourcing original capacity information also allows us to calculate State of Health for a vehicle, even if it was not connected to Geotab when it was new.

When the State of Health is blank, it is likely because we are missing original capacity data. The most common reasons for missing original capacity are:

1. We do not have enough crowd-sourced low odometer data for vehicles of the same make / model / year / trim.
2. We cannot decode the VIN number for this vehicle. (VIN is used to determine make / model / year/ trim)

Why is usable battery capacity increasing over time? I was expecting to see batteries degrade!

Temperature Matters: Similar to how your phone battery might drain faster in the cold, EV batteries are also affected by temperature. In colder weather, the chemical reactions inside the battery slow down, meaning it naturally has less usable energy, so our system reports a lower capacity. When it gets warmer, the battery performs better, and you'll see the reported capacity go back up. Seasonal variation is normal and does not mean that your battery is getting “better” or “worse” in the long run.

Software Buffers: Vehicle manufacturers use software buffers to protect the battery and extend its life. The vehicle’s computer will not allow drivers to charge the battery to its full, physical capacity; the vehicle computer will instead allow drivers to store a "usable" amount of energy, determined by the vehicle software. Since Geotab measures usable capacity (energy available to the driver), the vehicle’s battery management software can influence Geotab’s measurements. It is possible that your usable battery capacity could change after a vehicle software update.

Short-term ups and downs (caused by temperature fluctuations or vehicle software updates) are different from the gradual, long-term battery degradation that naturally occurs in all batteries over time. We recommend tracking your battery’s health over several years, to understand its true aging.

Range Capability

The RangeEstimate data object reports the distance an EV can travel on a single full charge. The range estimate is based on historical energy consumption, distance traveled, and battery capacity. You can use RangeEstimates to track changes in EV range over time, in order to understand seasonal range variation, or losses in range due to long-term battery degradation.

RangeEstimate

The RangeEstimate object can be requested from the API using the Get(...) method.

See RangeEstimateSearch below to specify search filters when requesting data.

Why is RangeEstimate null for some vehicles?

The most likely reason for a null range estimate is that there is not enough recent driving data available for this vehicle. RangeEstimates can require up to 30 days of historical driving data, and become more accurate the more data is collected.

RangeEstimateSearch

RangeEstimateSearch is the object used to specify the arguments when searching for RangeEstimate data, and can be passed into Get(...) to filter results.

Real-Time EV Insights

The EVStatusInfo data object reports the last known state of an EV, including real-time remaining range. If the EV is currently charging, EVStatusInfo provides an estimate of charge complete time (when the battery will reach a certain state of charge).

EVStatusInfo

The EVStatusInfo object can be requested from the API using the Get(...) method.

See EVStatusInfoSearch below to specify search filters when requesting data.

EVStatusInfoSearch

EVStatusInfoSearch is the object used to specify the arguments when searching for EVStatusInfo, and can be passed into Get(...) to filter results.

✱ NOTE: Unlike other data objects, you cannot search for EVStatusInfo using a fromDate and toDate. EVStatusInfo will always return the most recent data.

EVStatusInfo Frequently Asked Questions

Why are “real time range” estimates null for some vehicles?

The most likely reason for a null range estimate is that there is not enough recent driving data available for this vehicle. Range estimates can require up to 30 days of historical driving data, and become more accurate the more data is collected.

Why are “time to charge” estimates null for some vehicles?

We can only estimate charge complete times for vehicles that are currently charging and have not yet reached the target state of charge. Charge complete time estimates will be null for vehicles that are not currently charging.

Charge complete time estimates will also be null if there is not a valid battery capacity estimate for this vehicle. Battery capacity estimates require up to 60 days of historical driving and charging data.