Electric Vehicles | MyGeotab | Geotab Developers

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.

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

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

EV data diagnostics basics

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.

API StatusData ID

Code

Portal Name

Description

DiagnosticEvPowertrainTypeId

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.

EV driving energy

Core

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).

✱ 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.

Idling

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.

For internal debugging only

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

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).

EV charging

Core concepts

HV Battery — The high-voltage (HV) battery of a BEV or PHEV.
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.

Charging status

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).

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).

AC charging

API StatusData ID	Code	Portal Name	Description
DiagnosticTotalLifetimeOnBoardChargerEnergyInDuringACChargingId	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.

DC charging

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.

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.

Additional EV Diagnostic Signals — non-standard support

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

API StatusData ID	Code	Portal Name	Description	Availability Limitations
awCIeUqgS10SjVyRrbg5kLA	2997	Electric vehicle battery charge remaining	Energy (kWh) remaining in the battery, which may be usable or actual.	Non-standard support
aiC3aIaRAhVEQzOSvicbN9og	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
aFGR6Q9guoUeiaAZ1fD6oQ	2659	Electric vehicle distance remaining	Unit: meters (m) Distance remaining, as calculated and reported by the EV.	Non-standard support

Fuel Cell Electric Vehicle (FCEV) data diagnostics

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-AomBxBQ6q6e1tZvzE8Wg	3296	Total idle hydrogen fuel used (since telematics device install)	Unit: grams Total hydrogen consumed while idling since the GO device was installed.

MyGeotab API: Exceptions

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

Visit the Geotab developer site for more information.

MyGeotab API: EV groups

EV groups

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

✱ NOTE: 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.

EVs are automatically classified based on their unique powertrain types:

GroupElectricHybridPlugInId: Contains all detected Battery Electric Vehicle (BEV) and detected Plug-in Hybrid (PHEV)
GroupBatteryElectricVehicleId (under GroupElectricHybridPlugInId): Contains all detected fully electric Battery Electric Vehicle (BEVs)
GroupPlugInHybridElectricVehicleId (under GroupElectricHybridPlugInId): Contains all detected Plug-in Hybrid (PHEV)
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.

If an asset is originally automatically classified:
- 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).
- 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).
If an asset is manually classified:
- 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.
- 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.
- 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.

MyGeotab API: Charge Events

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.

Properties	Type	Description
device	object	The device that created the charge event.
startTime	string*	The UTC date and time when the charge event started, following the ISO 8601 standard.
duration	string*	The length of the time the vehicle was charging, formatted as follows: "hh:mm:ss.fffffff", where "fffffff" represents milliseconds.
location	object	Coordinate of the charge event.
chargeType	string*	The electric current type provided by the external power source: "AC" (Alternating Current) or "DC" (Direct Current).
startStateOfCharge	number	The battery charge % (state of charge) at the start of this ChargeEvent.
endStateOfCharge	number	The battery charge % (state of charge) at the end of this ChargeEvent.
energyConsumedKwh	number	The total energy delivered to the vehicle during the ChargeEvent, in kWh.
peakPowerKw	number	During a ChargeEvent, the power typically fluctuates. The maximum or peak value is the best indicator of the sustained power found throughout. ✱ NOTE: Peak power is a good indicator of the EV contribution to facility power demand.
maxACVoltage	number	During a ChargeEvent, the voltage typically fluctuates. The maximum value is the best indicator of the sustained voltage found throughout. ✱ NOTE: In North America, this property can be used to determine if a charge event is SAE Level 1 (120 V AC), SAE Level 2 (~240 V AC).
chargeIsEstimated	boolean	Indicates whether energyConsumedKwh was measured directly — using a primary, preferred vehicle signal — or estimated based on secondary signals.
tripStop	string*	The UTC date and time of the EV's trip stop where the ChargeEvent took place, following the ISO 8601 standard. Charging happens during a trip stop.
odometer	number	The vehicle's odometer reading at the charging time.

ChargeEventSearch

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

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

ChargeEvents Frequently Asked Questions

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

These two objects measure different things:

FuelAndEnergyUsed reports energy that leaves the battery while the vehicle is driving / idling.
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.

MyGeotab API: Fuel and Energy used

Fuel and Energy used

The FuelAndEnergyUsed data object allows you to track the energy (BEVs and PHEVs) and fuel (FCE 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.

FuelAndEnergyUsed

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

See FuelAndEnergySearch below to specify search filters on FuelAndEnergyUsed.

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.

FuelAndEnergySearch

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

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.

FuelAndEnergyUsed Frequently Asked Questions

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

These two objects measure different things:

FuelAndEnergyUsed reports energy that leaves the battery while the vehicle is driving / idling.
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).

MyGeotab API: Battery Capacity and State of Health

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.

Properties	Type	Description
device	object	The device associated with this electric vehicle.
VIN	string*	The vehicle identification number (VIN). Must be 17 characters.
DetectionDate	string*	The date and time (UTC, ISO 8601 format) when the BatteryStateOfHealth was calculated.
CurrentBatteryCapacityMeanKwh	number	The usable battery capacity on the detection date, measured in kWh. The mean value is our best guess at the vehicle’s true usable battery capacity on the detection date.
CurrentBatteryCapacityLowerBoundKwh	number	The lower bound of the vehicle’s usable battery capacity on the detection date, measured in kWh. ✱ NOTE: There is a 90% probability that the true usable battery capacity is between CurrentBatteryCapacityLowerBoundKwh and CurrentBatteryCapacityUpperBoundKwh.
CurrentBatteryCapacityUpperBoundKwh	number	The upper bound of the vehicle’s usable battery capacity on the detection date, measured in kWh. ✱ NOTE: There is a 90% probability that the true usable battery capacity is between CurrentBatteryCapacityLowerBoundKwh and CurrentBatteryCapacityUpperBoundKwh.
OriginalBatteryCapacityMeanKwh	number	The original usable battery capacity, measured in kWh. The mean value is our best guess at the original battery capacity when the vehicle was new. ✱ NOTE: The original capacity is calculated based on data collected from other vehicles of the same make, model, year and trim. This value may be updated as we gather more information on this particular trim.
OriginalBatteryCapacityLowerBoundKwh	number	The lower bound of the vehicle’s usable battery capacity when the vehicle was new, measured in kWh. ✱ NOTE: There is a 90% probability that the true original battery capacity was between OriginalBatteryCapacityLowerBoundKwh and OriginalBatteryCapacityUpperBoundKwh.
OriginalBatteryCapacityUpperBoundKwh	number	The upper bound of the vehicle’s usable battery capacity when the vehicle was new, measured in kWh. ✱ NOTE: There is a 90% probability that the true original battery capacity was between OriginalBatteryCapacityLowerBoundKwh and OriginalBatteryCapacityUpperBoundKwh.
StateOfHealthMean	number	State of health is defined as current battery capacity / original battery capacity. The mean value is our best guess at the true battery State of Health, on the detection date.
StateOfHealthLowerBound	number	The lower bound of the state of health estimate. ✱ NOTE: There is a 90% probability that the true battery state of health is between StateOfHealthLowerBound and StateOfHealthUpperBound.
StateOfHealthUpperBound	number	The upper bound of the state of health estimate. ✱ NOTE: There is a 90% probability that the true battery state of health is between StateOfHealthLowerBound and StateOfHealthUpperBound.

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:

We do not have enough crowd-sourced low odometer data for vehicles of the same make / model / year / trim.
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.

MyGeotab API: Range Capability

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.

Properties	Type	Description
device	object	The device associated with this electric vehicle.
VIN	string*	The vehicle identification number (VIN). Must be 17 characters.
DetectionDate	string*	The date and time (UTC, ISO 8601 format) when the RangeEstimate was calculated.
RangeEstimateMeanKm	number	Our best guess at the vehicle’s true range capability on the detection date. ✱ NOTE: The range estimate represents the distance the vehicle can travel on a single full charge.
RangeEstimateLowerBoundKm	number	The lower bound of the range estimate. ✱ NOTE: There is a 90% probability that the vehicle’s true range capability is between RangeEstimateLowerBoundKm and RangeEstimateUpperBoundKm.
RangeEstimateUpperBoundKm	number	The upper bound of the range estimate. ✱ NOTE: There is a 90% probability that the vehicle’s true range capability is between RangeEstimateLowerBoundKm and RangeEstimateUpperBoundKm.
RangeEstimationMethod	string*	The estimation method used to calculate the range estimates. If the method is BatteryEstimation, the calculation is based on the energy readings coming in and out of the battery. If the method is SoCEstimation, the calculation is based on the detected state-of-charge deltas at the beginning and end of trips.

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.

Properties	Type	Description
DeviceSearch	object	Search for RangeEstimates 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.

MyGeotab API: Real-Time EV Insights

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.

Properties	Type	Description
device	object	The device associated with this electric vehicle.
DateTime	string*	The date and time (UTC, ISO 8601 format) when EVStatusInfo was last updated.
statusData	array of objects	Contains the latest values of the following diagnostic signals: Generic state of charge (%) Electric vehicle charging state (0 = not charging / 1 = AC charging / 2 = DC charging) Electric vehicle battery power (W)
RealTimeRangeRemainingMeanKm	number	The most likely remaining range of the electric vehicle, in kilometers. This represents the distance the electric vehicle can drive, given its current state of charge. ✱ NOTE: EV range can be impacted by a number of factors, including weather, speed, altitude change, payload, and driving style. Because these factors are constantly changing, it is difficult to precisely predict the remaining range of an electric vehicle. Upper and lower bounds are provided to represent the level of certainty in this range remaining estimate.
RealTimeRangeRemainingLowerBoundKm	number	The lower bound on the estimated remaining range. ✱ NOTE: There is a 90% probability that the vehicle’s true remaining range is between RealTimeRangeRemainingLowerBoundKm and RealTimeRangeRemainingUpperBoundKm.
RealTimeRangeRemainingUpperBoundKm	number	The upper bound on the estimated remaining range. ✱ NOTE: There is a 90% probability that the vehicle’s true remaining range is between RealTimeRangeRemainingLowerBoundKm and RealTimeRangeRemainingUpperBoundKm.
TimeToChargeTo80Percent	number	The estimated time (UTC, ISO 8601 format) when the EV battery will reach 80% charge. ✱ NOTE: The EV must be currently charging and have state of charge <80% in order to estimate TimeToChargeTo80Percent.
TimeToChargeTo90Percent	number	The estimated time (UTC, ISO 8601 format) when the EV battery will reach 90% charge. ✱ NOTE: The EV must be currently charging and have state of charge <90% in order to estimate TimeToChargeTo90Percent.
TimeToChargeTo100Percent	number	The estimated time (UTC, ISO 8601 format) when the EV battery will reach 100% charge. ✱ NOTE: The EV must be currently charging and have state of charge <100% in order to estimate TimeToChargeTo100Percent.

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.

Properties	Type	Description
DeviceSearch	object	Search for RangeEstimates using a device ID or GroupSearch. See Filtering on Detected EVs: EV Groups.

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.