Skip to content
/
List status logs for a ve...

List status logs for a vehicle

Request

List the historical status logs for a specific Vehicle. Used to find out the state of the Vehicle at each point it reported in to ev.energy.

Security
oauth2(Required scopes: vehicle:read)
Path
vehicle_idstringvhcl[A-Z\d]{26}required

The ID of the specific vehicle to retrieve.

Example:vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
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
sampled_at__gtestring, (date-time)

Filters for logs sampled at or after this datetime.

Example:sampled_at__gte=2024-04-17T09:39:45.984584Z
sampled_at__ltestring, (date-time)

Filters for logs sampled at or before this datetime.

Example:sampled_at__lte=2024-04-17T09:39:45.984584Z
expandArray of strings

Specify a url field to expand into a nested resource.

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

Specify the version of this endpoint to use.

Value:2
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&sampled_at__gte=2024-04-17T09%3A39%3A45.984584Z&sampled_at__lte=2024-04-17T09%3A39%3A45.984584Z&expand=vehicle' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

List all the status logs for a specific Vehicle, sorted newest first.

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 [
urlstring, (uri)read-only
Example:"https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-01-01T11:11:11.1111Z/"
logged_atstring, (date-time)read-only

The date and time this status information was received and stored.

sampled_atstring, (date-time)

The date and time when this data was recorded. Likely to be earlier than logged_at, but how much earlier depends on the integration and other factors.

vehiclestring or Vehicle (object)
One of:
string (uri)
state_of_charge_percentageinteger or nullread-only

How full the vehicle's battery is, as a percentage. Will be null if we are unable to get this information from the vehicle's telematics.

Example:70
is_chargingboolean or nullread-only

Is the vehicle currently receiving charge? Will be null if we are unable to get this information from the vehicle's telematics.

Default:false
is_plugged_inboolean or nullread-only

Is the vehicle currently connected to an EVSE? Will be null if we are unable to get this information from the vehicle's telematics.

Default:false
charge_rate_wattsinteger or null

The current rate of charge being received, in watts. Will be null if we are unable to get this information from the Vehicle integration.

estimated_charge_rate_wattsinteger or nullread-only

The charge rate in watts estimated from the change in battery charge level. Useful when the Vehicle integration does not report charge_rate_watts directly. Will be null if it cannot be estimated.

charge_level_watt_hoursinteger or nullread-only

The battery charge level in watt hours. Will be null if we are unable to get this information from the Vehicle integration.

target_charge_level_percentageinteger or nullread-only

The target charge level as a percentage. Will be null if we are unable to get this information from the Vehicle integration.

target_charge_level_watt_hoursinteger or nullread-only

The target charge level in watt hours. Will be null if we are unable to get this information from the Vehicle integration.

charge_energy_added_watt_hoursinteger or nullread-only

The amount of energy added during the most recent charge, as reported by the vehicle, in watt hours. Will be null if we are unable to get this information from the Vehicle integration.

minutes_to_full_chargeinteger or nullread-only

The number of minutes the vehicle predicts until it is fully charged. Will be null if we are unable to get this information from the Vehicle integration.

current_typestring or nullread-only

The current type of the EVSE the vehicle is connected to (AC or DC). Will be null if we are unable to get this information from the Vehicle integration.

Enum:"AC - Typically home chargers""DC - Typically OTG chargers"null
is_completeboolean or nullread-only

Whether the vehicle has reached the target charge level. Will be null if we are unable to get this information from the Vehicle integration.

odometer_metersinteger or nullread-only

The vehicle's odometer reading in meters. Will be null if we are unable to get this information from the Vehicle integration.

data_sourcestring or nullread-only

The integration that originated this data.

statestring or nullread-only

The state of the vehicle. Will be null if we are unable to get this information from the Vehicle integration.

Enum:"DRIVING""RECENTLY_FINISHED_DRIVING""STATIONARY""IN_SERVICE""PLUGGED_IN_NOT_CHARGING""PLUGGED_IN_CHARGING""PLUGGED_IN_COMPLETE""PLUGGED_IN_NEAR_READY_BY_TIME""PLUGGED_IN_ALMOST_COMPLETE""UNKNOWN"
]
Response
[
  {
    "url": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-01-01T11:11:11.1111Z/",
    "logged_at": "2019-08-24T14:15:22Z",
    "sampled_at": "2019-08-24T14:15:22Z",
    "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "state_of_charge_percentage": 70,
    "is_charging": false,
    "is_plugged_in": false,
    "charge_rate_watts": 0,
    "estimated_charge_rate_watts": 0,
    "charge_level_watt_hours": 0,
    "target_charge_level_percentage": 0,
    "target_charge_level_watt_hours": 0,
    "charge_energy_added_watt_hours": 0,
    "minutes_to_full_charge": 0,
    "current_type": "AC - Typically home chargers",
    "is_complete": true,
    "odometer_meters": 0,
    "data_source": "string",
    "state": "DRIVING"
  }
]