Electric vehicle data diagnostics and API tools
Explore the data and API tools you can use to track electric vehicles.
Before you begin
For the purposes of this article, 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 Electric Vehicle Make/Model Support Reference.
The GO Plan Rate Plan is required to use these data diagnostics and API.
Electric vehicle data diagnostics
Learn how data diagnostics give you raw signals from an EV.
Data diagnostics
Fault diagnostics and Diagnostic Trouble Codes (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
Review the data that shows an EV powertrain type and charge level.
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. |
EV driving energy
Review the data on energy that enters and leaves an EV battery as it drives and idles.
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). |
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
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
Review the data on charging state, power, and energy for AC and DC charging.
Core concepts
- HV Battery: The high-voltage (HV) battery of a BEV or PHEV.
- AC versus 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). |
AC charging
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. |
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. |
Additional EV diagnostic signals: non-standard support
Review the data that only some EV makes and models send.
The following are supported on select EV makes and models that make this information accessible.
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: °C 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: °C 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: °C 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 |
Fuel Cell Electric Vehicle (FCEV) data diagnostics
Review the data on hydrogen fuel level and use for fuel cell EVs.
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. |
Electric vehicle API tools
Learn how to get EV events through the MyGeotab API.
Events
Events generated by EV rules can be retrieved via the ExceptionEvent object.
Visit the Geotab developer site for more information.
EV groups
Learn how built-in groups sort EVs by powertrain type, and how to filter on them.
There are automatically populated, built-in groups that allow you to quickly find and filter on EVs.
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:
GroupElectricHybridgPluginId: Contains all detected Battery Electric Vehicle (BEV) and detected Plug-in Hybrid (PHEV)GroupBatteryElectricVehicleId(underGroupElectricHybridgPluginId): Contains all detected fully electric Battery Electric Vehicle (BEVs)GroupPluginHybridElectricVehicleId(underGroupElectricHybridgPluginId): 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:
| <code>groupSearch: {"id":"GroupBatteryElectricVehicleId"}</code> |
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:
| <code>"groupFilterCondition":{"relation":"And","groupFilterConditions":[{"groupId":"b5B1C"},{"groupId":"GroupBatteryElectricVehicleId"}]}</code> |
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. 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 ofGroupManuallyClassifiedPowertrainId(for example, removing theGroupBatteryElectricVehicleIdthat was assigned automatically by MyGeotab will result in the asset becoming part ofGroupManuallyClassifiedPowertrainId). - Calling
Set<Device>and adding any powertrain group ID to an asset will also result in that asset becoming part ofGroupManuallyClassifiedPowertrainId(for example, addingGroupBatteryElectricVehicleIdwill result in the asset becoming part ofGroupManuallyClassifiedPowertrainIdandGroupBatteryElectricVehicleId).
- Calling
- If an asset is manually classified:
- Calling
Set<Device>and removing any powertrain group IDs from an asset will NOT removeGroupManuallyClassifiedPowertrainId. As long as the asset is assigned toGroupManuallyClassifiedPowertrainId, Geotab will NOT attempt to automatically classify the asset into any powertrain group. - Calling
Set<Device>and removingGroupManuallyClassifiedPowertrainIdwill 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 timeGroupManuallyClassifiedPowertrainIdis removed, in order to keep track of when an asset is automatically classified back into a powertrain group. - Calling
Set<Device>and ONLY removingGroupManuallyClassifiedPowertrainIdwill 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.
- Calling
Charge events
Review the ChargeEvent object, which summarizes where, when, and how much EVs charged.
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 |
|---|---|---|
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 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 (approximately 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 |
|---|---|---|
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. |
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 and 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.
Fuel and energy used
Review the data on the energy and fuel a vehicle uses as it drives and idles.
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.
FuelAndEnergyUsed
The FuelAndEnergyUsed object can be requested from the API using the Get(...) and GetFeed(...) methods.
See FuelAndEnergyUsedSearch below to specify search filters on FuelAndEnergyUsed.
Properties | Type | Description |
|---|---|---|
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
FuelAndEnergyUsedSearch and can be passed into Get(...) to filter FuelAndEnergyUsed results.
Properties | Type | Description |
|---|---|---|
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. |
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 and 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 (for example, TotalFuelUsed - IdlingFuelUsedL = Driving fuel used).
Battery capacity and state of health
Review the data on how an EV battery wears over time.
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 |
|---|---|---|
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. |
BatteryStateOfHealthSearch
BatteryStateOfHealthSearch is the object used to specify the arguments when searching for BatteryStateOfHealth data, and can be passed into Get(...) to filter results.
Properties | Type | Description |
|---|---|---|
object | Search for BatteryStateOfHealth data 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. |
BatteryStateOfHealth frequently asked questions
Range capability
Review the RangeEstimate object, which reports how far an EV can drive on one full charge.
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 |
|---|---|---|
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 |
|---|---|---|
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. |
Real-time EV insights
Review the EVStatusInfo object, which reports the last known state of an EV.
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 |
|---|---|---|
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:
|
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.
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 |
|---|---|---|
object | Search for RangeEstimates using a device ID or GroupSearch. See Filtering on Detected EVs: EV Groups. |
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.