Skip to main content

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

is_plugged_in
boolean
Indicates whether the charging cable is connected to the vehicle.Example: true
is_charging
boolean
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
is_fully_charged
boolean
Indicates that the target charge level has been reached and charging has stopped.Example: true
charge_rate_w
integer
Current charging rate in Watts.Returns 0 when not charging.Example: 11050
charge_time_remaining
integer
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
datetime
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

Battery Information

battery_level
integer
Current battery charge level in percent.Example: 90Range: 0-100
battery_capacity_kwh
integer
Total battery capacity in kilowatt-hours.Example: 80
driving_range
integer
Estimated remaining driving range in kilometers based on current battery level.May not be available for all vehicle models.Example: 390

Energy Consumption

consumption_last_day_kwh
float
Energy consumption for charging in the previous day in kWh.Example: 32.5
consumption_last_week_kwh
float
Energy consumption for charging in the previous week in kWh.Example: 120.1
consumption_last_month_kwh
float
Energy consumption for charging in the previous month in kWh.Example: 451.3
consumption_last_updated_utc
datetime
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")
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

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

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