Skip to content
/
Retrieve a specific statu...

ev.energy v2 API (2.0)

The official API for ev.energy, version 2.

Download OpenAPI description
ev.energy-API-v2.json
ev.energy-API-v2.yaml
Overview
URL
developers.ev.energy
ev.energy developers
developers@ev.energy
License
Proprietary
Languages
Servers
Mock server
https://developers.ev.energy/_mock/ev.energy-api-v2
Live API for both production and sandbox requests.
https://api.ev.energy/v2
Staging server for internal testing only.
https://api-staging.ev.energy/v2

Carbon

Endpoints for interacting with carbon intensity data.

Schemas
Operations

Charging Sessions

Endpoints related to records of charging.

Schemas
Operations
Webhooks

CSV

Endpoints that return CSV responses only and are not linkable to other endpoint data.

EVSEs

Endpoints for interacting with EVSEs.

Schemas
Operations

Notifications

Endpoints for communicating notifications.

Operations

Programs

Endpoints related to incentivised charging programs.

Operations

Rebates

Endpoints for interacting with rebates.

Schemas
Operations

Root

The root endpoint which lists all the top-level collections.

Operations

Schedules

Schema definitions for charging schedules.

Schemas

Sites

Endpoints for interacting with sites containing multiple EVSEs.

Operations

Solar

Endpoints for interacting with solar arrays and inverters.

Operations

Subscriptions

Endpoints for interacting with user subscriptions.

Operations

Support Tickets

Endpoints for interacting with customer support tickets.

Schemas
Operations

Tariffs

Endpoints related to energy suppliers and their tariffs.

Schemas
Operations

Users

Endpoints for interacting with users.

Schemas
Operations

Vehicles

Endpoints for interacting with vehicles.

Schemas

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.

Value2
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
Linkstring

Provides links to the previous and next pages of data, if they exist.

Example: "<https://api.ev.energy/v2/vehicles?page_size=25&page_before=2024-04-18T08:53:52.225655Z>; rel=\"previous\", <https://api.ev.energy/v2/vehicles?page_size=25&page_after=2024-04-18T08:53:52.225655Z>; rel=\"next\""
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.

Value2
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/jsonArray [
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.

]
Response
application/json
[
  {
    "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
  }
]

Retrieve a specific status log for a vehicle

Request

A single status log for a particular vehicle is uniquely identified by the timestamp it was logged at.

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

The ID of the specific vehicle to retrieve.

Example: vhcl01HRFF3SEVSCRAV9B3CHVDFN0H
sampled_atstring(date-time)required

The time the log's data was recorded on the device.

Example: 2024-04-17T09:39:45.984584Z
Query
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.

Value2
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/status_logs/2024-04-17T09:39:45.984584Z?expand=vehicle' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns the Vehicle status logged at a specific time.

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.

Value2
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
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.

Response
application/json
{
  "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
}

List API error logs for a vehicle

Request

List the historical API error logs for a specific Vehicle. These logs capture errors that occurred when attempting to communicate with the vehicle's telematics API.

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
logged_at__gtestring(date-time)

Filters for logs logged at or after this datetime.

Example: logged_at__gte=2024-04-17T09:39:45.984584Z
logged_at__ltestring(date-time)

Filters for logs logged at or before this datetime.

Example: logged_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.

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

Responses

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

Headers
Linkstring

Provides links to the previous and next pages of data, if they exist.

Example: "<https://api.ev.energy/v2/vehicles?page_size=25&page_before=2024-04-18T08:53:52.225655Z>; rel=\"previous\", <https://api.ev.energy/v2/vehicles?page_size=25&page_after=2024-04-18T08:53:52.225655Z>; rel=\"next\""
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.

Value2
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/jsonArray [
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/error_logs/2024-04-17T09:39:45.984584Z/"
logged_atstring(date-time)read-only

The date and time when this error was logged by the ev.energy system.

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

The HTTP status code of the error response from the vehicle telematics API.

Example: 401
controllerstringread-only

The vehicle controller/integration that was being used when the error occurred.

Example: "ENODE"
error_codestringread-only

The error code received from the provider or determined by the ev.energy system.

Example: "AUTHENTICATION_ERROR"
error_typestringread-only

The error type received from the provider or determined by the ev.energy system.

Example: "VehicleAPIUnauthorized"
request_idstringread-only

The request ID that resulted in this error. Used for tracing and debugging.

Example: "56rst-z2jku-tty9t-0dn2f-qazow"
commandstringread-only

The command/method that was being executed when the error occurred.

Example: "START_CHARGE"
error_detailstringread-only

Detailed information about the error.

internal_command_idstring or null(uuid)read-only

Internal UUID to track the command dispatch. This can be used to correlate errors with commands.

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
]
Response
application/json
[
  {
    "url": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H/error_logs/2024-04-17T09:39:45.984584Z/",
    "logged_at": "2019-08-24T14:15:22Z",
    "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "status_code": 401,
    "controller": "ENODE",
    "error_code": "AUTHENTICATION_ERROR",
    "error_type": "VehicleAPIUnauthorized",
    "request_id": "56rst-z2jku-tty9t-0dn2f-qazow",
    "command": "START_CHARGE",
    "error_detail": "string",
    "internal_command_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
]

Webhooks

Endpoints for configuring and managing webhooks.

Operations