Electric Vehicle State
Electric vehicle state parameters provide real-time charging status, battery information, and consumption metrics. These fields are read-only and automatically updated from the manufacturerâs API.
State data refresh frequency depends on the manufacturerâs API. Tesla updates every 5-10 minutes when active, others may vary.
Charging Status
Indicates whether the charging cable is connected to the vehicle. Example: true
Indicates whether charging is currently in progress. A vehicle can be plugged in but not actively charging (waiting for low-price period, charge limit reached, etc.). Example: true
Indicates that the target charge level has been reached and charging has stopped. Example: true
Current charging rate in Watts. Returns 0 when not charging. Example: 11050
Estimated time to reach target charge level in seconds. Returns 0 when not charging or fully charged. Example: 6250 (approximately 1 hour 44 minutes)
charge_state_last_updated_at
Timestamp when the charge state was last updated from the manufacturerâs API. Use this to determine data freshness. Example: 2023-03-22T13:54:34.000Z
Current battery charge level in percent. Example: 90Range: 0-100
Total battery capacity in kilowatt-hours. Example: 80
Estimated remaining driving range in kilometers based on current battery level. May not be available for all vehicle models. Example: 390
Energy Consumption
Energy consumption for charging in the previous day in kWh. Example: 32.5
consumption_last_week_kwh
Energy consumption for charging in the previous week in kWh. Example: 120.1
consumption_last_month_kwh
Energy consumption for charging in the previous month in kWh. Example: 451.3
consumption_last_updated_utc
Timestamp when consumption data was last calculated. Example: 2023-03-22T13:54:34.000Z
Usage Examples
Get Vehicle State
curl -X GET \
'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/electric-vehicles/{device_id}' \
-H 'Authorization: Bearer {auth_token}' \
-H 'Accept: application/json'
Display Charging Status
def format_charging_status ( vehicle ):
"""
Format vehicle state for dashboard display
"""
if not vehicle[ 'is_plugged_in' ]:
status = "Not connected"
detail = "Vehicle is not plugged in"
elif vehicle[ 'is_fully_charged' ]:
status = "Fully charged"
detail = f " { vehicle[ 'battery_level' ] } % - { vehicle[ 'driving_range' ] } km range"
elif vehicle[ 'is_charging' ]:
time_remaining = vehicle[ 'charge_time_remaining' ] // 60 # Convert to minutes
status = "Charging"
detail = f " { vehicle[ 'battery_level' ] } % - { vehicle[ 'charge_rate_w' ] } W - { time_remaining } min remaining"
else :
status = "Connected, not charging"
detail = f " { vehicle[ 'battery_level' ] } % - Waiting for optimal charging time"
return {
'status' : status,
'detail' : detail,
'battery_level' : vehicle[ 'battery_level' ],
'range_km' : vehicle[ 'driving_range' ],
'is_charging' : vehicle[ 'is_charging' ]
}
# Example usage
vehicle = get_vehicle(org_id, user_id, device_id)
status = format_charging_status(vehicle)
print ( f "Status: { status[ 'status' ] } " )
print ( f "Details: { status[ 'detail' ] } " )
Calculate Charging Progress
def calculate_charging_progress ( vehicle ):
"""
Calculate charging progress and estimates
"""
current_level = vehicle[ 'battery_level' ]
current_kwh = vehicle[ 'battery_capacity_kwh' ] * (current_level / 100 )
if vehicle[ 'is_charging' ] and vehicle[ 'charge_rate_w' ] > 0 :
# Calculate time estimates
time_remaining_min = vehicle[ 'charge_time_remaining' ] / 60
time_remaining_hours = time_remaining_min / 60
# Estimate target level based on charge rate
charge_per_hour = vehicle[ 'charge_rate_w' ] / 1000 # kW
kwh_to_add = charge_per_hour * time_remaining_hours
target_kwh = current_kwh + kwh_to_add
target_percent = (target_kwh / vehicle[ 'battery_capacity_kwh' ]) * 100
return {
'current_level' : current_level,
'target_level' : round (target_percent, 1 ),
'time_remaining_min' : round (time_remaining_min),
'charge_rate_kw' : round (vehicle[ 'charge_rate_w' ] / 1000 , 1 ),
'kwh_to_add' : round (kwh_to_add, 2 )
}
return {
'current_level' : current_level,
'status' : 'not_charging'
}
# Example usage
progress = calculate_charging_progress(vehicle)
if progress.get( 'status' ) != 'not_charging' :
print ( f "Current: { progress[ 'current_level' ] } %" )
print ( f "Target: { progress[ 'target_level' ] } %" )
print ( f "Time remaining: { progress[ 'time_remaining_min' ] } minutes" )
print ( f "Charge rate: { progress[ 'charge_rate_kw' ] } kW" )
Monitor Consumption Trends
def analyze_ev_consumption ( vehicle ):
"""
Analyze EV charging consumption patterns
"""
daily = vehicle[ 'consumption_last_day_kwh' ]
weekly = vehicle[ 'consumption_last_week_kwh' ]
monthly = vehicle[ 'consumption_last_month_kwh' ]
# Calculate averages
avg_daily_from_week = weekly / 7
avg_daily_from_month = monthly / 30
# Estimate costs (example rate: 0.30 EUR/kWh)
energy_rate = 0.30
cost_yesterday = daily * energy_rate
cost_this_week = weekly * energy_rate
cost_this_month = monthly * energy_rate
return {
'consumption' : {
'yesterday' : daily,
'this_week' : weekly,
'this_month' : monthly,
'avg_per_day_week' : round (avg_daily_from_week, 2 ),
'avg_per_day_month' : round (avg_daily_from_month, 2 )
},
'estimated_cost' : {
'yesterday' : round (cost_yesterday, 2 ),
'this_week' : round (cost_this_week, 2 ),
'this_month' : round (cost_this_month, 2 )
}
}
# Example usage
analysis = analyze_ev_consumption(vehicle)
print ( f "Yesterday: { analysis[ 'consumption' ][ 'yesterday' ] } kWh (âŦ { analysis[ 'estimated_cost' ][ 'yesterday' ] } )" )
print ( f "This week: { analysis[ 'consumption' ][ 'this_week' ] } kWh (âŦ { analysis[ 'estimated_cost' ][ 'this_week' ] } )" )
print ( f "Average: { analysis[ 'consumption' ][ 'avg_per_day_week' ] } kWh/day" )
Check Readiness for Trip
from datetime import datetime
def check_trip_readiness ( vehicle , required_range_km = 300 , departure_time = None ):
"""
Check if vehicle will be ready for a planned trip
"""
current_range = vehicle[ 'driving_range' ]
battery_level = vehicle[ 'battery_level' ]
# Check if already ready
if current_range >= required_range_km:
return {
'ready' : True ,
'message' : f "Vehicle ready with { current_range } km range" ,
'battery_level' : battery_level
}
# Check if charging
if vehicle[ 'is_charging' ]:
time_remaining_min = vehicle[ 'charge_time_remaining' ] / 60
if departure_time:
time_until_departure = (departure_time - datetime.now()).total_seconds() / 60
if time_remaining_min <= time_until_departure:
return {
'ready' : True ,
'message' : f "Will be ready in { round (time_remaining_min) } minutes" ,
'estimated_range' : vehicle[ 'driving_range' ] + ( 100 - battery_level) * 4 # Rough estimate
}
else :
return {
'ready' : False ,
'message' : f "Charging will take { round (time_remaining_min) } minutes, only { round (time_until_departure) } minutes until departure" ,
'action' : 'Consider adjusting charge deadline or departure time'
}
return {
'ready' : 'charging' ,
'message' : f "Charging in progress ( { battery_level } %), { round (time_remaining_min) } minutes remaining"
}
# Not charging and not ready
return {
'ready' : False ,
'message' : f "Current range { current_range } km insufficient, requires { required_range_km } km" ,
'action' : 'Plug in vehicle or adjust charge policy'
}
Dashboard Integration
Battery Status Visualization
def get_battery_display ( vehicle ):
"""
Generate battery display data with color coding
"""
level = vehicle[ 'battery_level' ]
# Determine color based on level
if level >= 80 :
color = 'green'
icon = 'đ'
elif level >= 50 :
color = 'blue'
icon = 'đ'
elif level >= 20 :
color = 'yellow'
icon = 'đĒĢ'
else :
color = 'red'
icon = 'đĒĢ'
# Charging indicator
if vehicle[ 'is_charging' ]:
icon = 'âĄ'
status_text = f "Charging at { vehicle[ 'charge_rate_w' ] } W"
elif vehicle[ 'is_fully_charged' ]:
status_text = "Fully charged"
elif vehicle[ 'is_plugged_in' ]:
status_text = "Connected, not charging"
else :
status_text = "Not connected"
return {
'level' : level,
'color' : color,
'icon' : icon,
'status_text' : status_text,
'range_km' : vehicle[ 'driving_range' ],
'range_display' : f " { vehicle[ 'driving_range' ] } km"
}
Charging States Explained
Charging
Connected, Not Charging
Fully Charged
Not Connected
Conditions: is_plugged_in: true, is_charging: true, charge_rate_w > 0Vehicle is actively drawing power and charging the battery. Typical Duration: 1-8 hours depending on battery size and charge rate
Conditions: is_plugged_in: true, is_charging: falseVehicle is connected but not actively charging. This is normal during optimized charging - waiting for low-price periods. Typical Duration: Variable, can be several hours
Conditions: is_plugged_in: true, is_fully_charged: true, is_charging: falseVehicle has reached target charge level and stopped charging. Typical Duration: Until unplugged or new charge session starts
Conditions: is_plugged_in: falseVehicle is not connected to a charger. Battery level remains static (minus any driving consumption). Typical Duration: Until plugged in
Best Practices
Poll vehicle state every 5-10 minutes when plugged in
Reduce polling to 15-30 minutes when not plugged in
Check charge_state_last_updated_at to avoid unnecessary calls
Show last update timestamp to users for transparency
Display driving_range prominently for user awareness
Consider range may vary based on driving conditions
Alert users when range drops below critical threshold (< 50 km)
Compare range to typical daily driving needs
Convert charge_time_remaining from seconds to hours:minutes for display
Show charge rate in kW (divide charge_rate_w by 1000)
Highlight when vehicle is waiting for optimal charging time
Provide context for why charging may be paused
Track consumption trends over time
Calculate estimated costs based on energy contract prices
Compare consumption to driving patterns
Identify opportunities for further optimization