Skip to content
/
List vehicles

List vehicles

Request

List all the vehicles that the authorization token has access to.

Security
oauth2(Required scopes: vehicle:read)
Query
page_beforestring[a-z]{4}[A-Z\d]{26}

Return results from the page after this ID.

Example:page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_afterstring[a-z]{4}[A-Z\d]{26}

Return results from the page before this ID.

Example:page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_sizeinteger, [ 1 .. 100 ]

Specify the number of results to return per page.

Default:25
Example:page_size=10
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum:"user""trim""trim.model""trim.model.make""latest_status_log"
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
EvEnergy-Userstringuser[A-Z\d]{26}

If the client is authenticated using Client Credentials, setting EvEnergy-User to a valid user ID allows requests to be made as if you were directly authenticated as that user.

Example:user01HN2NJ9NMRZBXT1H6FT9N7735
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/vehicles?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=user' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Return a list of vehicles.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
Array [
idstringvhcl[A-Z\d]{26}read-onlyrequired

Unique identifier for the given Vehicle.

Example:"vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
urlstring, (uri)read-onlyrequired
Example:"https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
trimstring or VehicleTrim (object)read-only
One of:

Defaults to a url, but can be expanded to the full Trim resource via the expand query parameter.

string (uri)read-only
userstring or User (object)
One of:

Defaults to a url, but can be expanded to the full User resource via the expand query parameter.

string (uri)
latest_status_log(string or null) or VehicleStatusLog (object)
Example:"https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/"
One of:

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

string or null (uri)
charging_sub_sessionsstring, (uri)

Provides a pre-constructed URL to list charging sub-sessions involving this Vehicle.

Example:"https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H"
integratedanyread-onlyrequired

Whether we have an integration with this vehicle.

  • UNINTEGRATED: This vehicle is not integrated
  • ACTIVE: This vehicle is integrated and the connection is working.
  • INACTIVE: This vehicle has been integrated but the connection has been severed, usually because the user needs to reconnect it.
Enum:"UNINTEGRATED""ACTIVE""INACTIVE"
battery_size_watt_hoursinteger, [ 1000 .. 300000 ]required

The nominal battery capacity of the vehicle in watt-hours according to the vehicle integration or trim. Editable via PATCH only for unintegrated vehicles; sending it for an integrated vehicle is rejected. Setting it flags the battery size as user-provided. Stored to the nearest 0.01 kWh (10 Wh), so the value read back may be rounded.

Example:60000
effective_battery_size_watt_hoursintegerread-onlyrequired

The effective battery capacity of the vehicle in watt-hours, accounting for estimated degradation based on odometer reading. This is the value used by the smart charging scheduler.

Example:60000
maximum_charge_limit_percentageinteger, [ 50 .. 100 ]required

The target state of charge of the car as a percentage between 50 and 100. The car will not be smart charged above this value. Can be null if target charge level has not been set or we don't know the car's battery size.

Default:100
descriptionstring, <= 200 charactersread-onlyrequired

Human-readable label for the vehicle.

Example:"My Volvo C40"
disabledbooleanread-onlyrequired

Whether the vehicle has been disabled and can no longer be smart-charged or controlled. Set when the user unenrolls the vehicle, when an integrated vehicle is switched to unintegrated ('dumb'), or when the owning account is pending deletion. Disabled vehicles that have not been permanently deleted are still returned by this endpoint. This is independent of integrated: a disabled vehicle can still report integrated=ACTIVE (e.g. pending deletion), and a healthy never-integrated vehicle is not disabled.

Example:false
smart_charging_enabledbooleanrequired

Whether smart (dynamic) charging is enabled for this vehicle.

Example:true
vehicle_classstring or nullrequired

Class of vehicle, passenger or commercial.

Enum:"PASSENGER""COMMERCIAL"null
Example:"PASSENGER"
]
Response
[
  {
    "id": "vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "url": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "trim": "https://api.ev.energy/v2/trim/vehicle_trim01HRFHBCM7VBSWRPVYFBQMH2BR",
    "user": "https://api.ev.energy/v2/user/user01HN2NJ9NMRZBXT1H6FT9N7735",
    "latest_status_log": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.994584Z/",
    "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "integrated": "UNINTEGRATED",
    "battery_size_watt_hours": 60000,
    "effective_battery_size_watt_hours": 60000,
    "maximum_charge_limit_percentage": 100,
    "description": "My Volvo C40",
    "disabled": false,
    "smart_charging_enabled": true,
    "vehicle_class": "PASSENGER"
  }
]