> ## Documentation Index
> Fetch the complete documentation index at: https://developers.podero.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Electric Vehicle State

> Read-only state data and current readings from electric vehicles

# Electric Vehicle State

Electric vehicle state parameters provide real-time charging status and battery information. These fields are read-only and automatically updated from the manufacturer's API.

<Note>
  State data is sourced from Smartcar webhooks and updates whenever the vehicle reports a change.
</Note>

## Charging Status

<ResponseField name="is_plugged_in" type="boolean">
  Indicates whether the charging cable is connected to the vehicle.

  **Example:** `true`
</ResponseField>

<ResponseField name="is_charging" type="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`
</ResponseField>

<ResponseField name="current_state_last_updated_at" type="datetime">
  Timestamp when the device state was last updated from the manufacturer's API.

  Use this to determine data freshness.

  **Example:** `2023-03-22T13:54:34.000Z`
</ResponseField>

## Charging Power

<ResponseField name="charge_rate_w" type="integer">
  Current charging rate in Watts.

  **Example:** `7400`
</ResponseField>

## Battery Information

<ResponseField name="battery_level" type="integer">
  Current battery charge level in percent.

  **Example:** `90`

  **Range:** 0-100
</ResponseField>

<ResponseField name="battery_capacity_kwh" type="float">
  Total battery capacity in kilowatt-hours.

  **Example:** `79.5`
</ResponseField>

<ResponseField name="is_fully_charged" type="boolean">
  Whether the battery has reached the vehicle's charge limit.

  **Example:** `false`
</ResponseField>

<ResponseField name="driving_range" type="integer">
  Estimated driving range based on the current battery level, in kilometers.

  **Example:** `280`
</ResponseField>

<ResponseField name="boost_state" type="enum">
  Current state of a boost charge. Use this to drive the charge now UI — see [Setting Preferences](/partner-api/user-journeys/end-user/setting-preferences) for how to trigger a boost.

  | Value         | Meaning                                          |
  | ------------- | ------------------------------------------------ |
  | `available`   | A boost can be triggered                         |
  | `requested`   | Boost triggered, charge starting                 |
  | `ongoing`     | Actively charging via boost                      |
  | `unavailable` | Vehicle full, already charging, or not connected |

  **Example:** `available`
</ResponseField>

## Usage Examples

### Get Vehicle State

<CodeGroup>
  ```bash cURL theme={null}
  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'
  ```

  ```python Python theme={null}
  response = requests.get(
      f'https://app.podero.com/api/partners/v2.0/org/{org_id}/users/{user_id}/electric-vehicles/{device_id}',
      headers={
          'Authorization': f'Bearer {auth_token}',
          'Accept': 'application/json'
      }
  )

  vehicle = response.json()

  # Access state fields
  battery_level = vehicle['battery_level']
  is_charging = vehicle['is_charging']
  is_plugged_in = vehicle['is_plugged_in']
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.podero.com/api/partners/v2.0/org/${orgId}/users/${userId}/electric-vehicles/${deviceId}`,
    {
      headers: {
        'Authorization': `Bearer ${authToken}`,
        'Accept': 'application/json'
      }
    }
  );

  const vehicle = await response.json();

  // Access state fields
  const batteryLevel = vehicle.battery_level;
  const isCharging = vehicle.is_charging;
  const isPluggedIn = vehicle.is_plugged_in;
  ```
</CodeGroup>

## Charging States Explained

<Tabs>
  <Tab title="Charging">
    **Conditions:** `is_plugged_in: true`, `is_charging: true`

    Vehicle is actively drawing power and charging the battery.

    **Typical Duration:** 1-8 hours depending on battery size and charge rate
  </Tab>

  <Tab title="Connected, Not Charging">
    **Conditions:** `is_plugged_in: true`, `is_charging: false`

    Vehicle is connected but not actively charging. This is normal during optimized charging - waiting for low-price periods.

    **Typical Duration:** Variable, can be several hours
  </Tab>

  <Tab title="Not Connected">
    **Conditions:** `is_plugged_in: false`

    Vehicle is not connected to a charger. Battery level remains static (minus any driving consumption).

    **Typical Duration:** Until plugged in
  </Tab>
</Tabs>

## Best Practices

<AccordionGroup>
  <Accordion title="Data Polling">
    * 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
  </Accordion>

  <Accordion title="Charge Monitoring">
    * Highlight when vehicle is waiting for optimal charging time
    * Provide context for why charging may be paused
    * Use `battery_level` to show charge progress to the user
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="EV Attributes" icon="sliders" href="/partner-api/reference/electric-vehicles/attributes">
    Writable parameters and configuration
  </Card>

  <Card title="Dashboard Integration" icon="chart-line" href="/partner-api/user-journeys/end-user/dashboard-integration">
    Building end-user dashboards
  </Card>
</CardGroup>