Retrieve periodic energy usage intervals for a charging sub-session

Request

Retrieve periodic energy usage intervals for a specific charging sub-session. This is the endpoint to use to find out when energy was actually delivered to the vehicle.

A sub-session's start/end only mark when its charging mode was active — within that window, energy delivery may begin late (e.g. smart charging waiting for an off-peak period), finish early (e.g. the target charge level was reached), or occur in several separate bursts. The intervals returned here report the actual delivery.

By default, intervals are regular fixed-length periods. If you are looking for intervals that cover the whole time energy is being delivered (which are therefore of irregular length) — for example to find the actual charging windows — use the merge_consecutive_intervals query parameter. Gaps where no energy flowed are returned as intervals with zero energy delivered; filter them out with energy_delivered_watt_hours__gt=0 if you only want the charging windows.

See Understanding charging data for how charging sessions, sub-sessions and energy usage intervals relate.

Security

oauth2(Required scopes: charging_session:read)

Path

charging_sub_session_idstringcsub[A-Z\d]{26}required

Uniquely identify a specific charging sub-session.

Example:csub01HSH04KDEWF6Z4DB2J77J74K5

Query

expandArray of strings

Specify a url field to expand into a nested resource.

Items Value:"charging_sub_session"

energy_delivered_watt_hours__gtinteger

Filters for values greater than a value.

Example:energy_delivered_watt_hours__gt=0

merge_consecutive_intervalsboolean

Request consecutive intervals of energy delivery (and intervals of no delivery) to be merged into combined periods of irregular length.

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/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage?expand=charging_sub_session&energy_delivered_watt_hours__gt=0&merge_consecutive_intervals=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns information about a single charging sub-session's energy usage.

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

urlstring, (uri)read-only

Example:"https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage"

currencystringread-only

The currency that prices for intervals are quoted in. Note that we always use the smallest unit of the currency.

Example:"GBP"

charging_sub_sessionstring, (uri)read-only

Example:"https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5"

intervalsArray of objects(UsageInterval)read-only

A list of energy usage intervals for this charging sub-session.

last_updated_atstring, (date-time)

The datetime when the energy usages were last updated at.

Response

{
  "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage",
  "currency": "GBP",
  "charging_sub_session": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
  "intervals": [
    { … }
  ],
  "last_updated_at": "2019-08-24T14:15:22Z"
}