Retrieve a charging sub-session

Carbon

Endpoints for interacting with carbon intensity data.

SchemasOperations

Charging Sessions

Endpoints related to records of charging.

SchemasOperationsWebhooks

DispatcherLog

Records when a Dispatch Command was sent to an EVSE or Vehicle.

logged_atstring(date-time)read-only

The date and time when the dispatch command was logged.

charging_sub_sessionstring or SubSession (object)read-only

The charging sub-session associated with this dispatch log.

One of:

The charging sub-session associated with this dispatch log.

string(uri)read-only

schedule_valid_period_startstring(date-time)read-only

The start of the validity period for the schedule that generated this dispatch command.

schedule_created_atstring(date-time)read-only

When the schedule that generated this dispatch command was created.

internal_command_idstring(uuid)read-only

Internal identifier for tracking the dispatch command.

Example: "12345678-1234-5678-1234-567812345678"

device_typestringread-only

The type of device the Dispatch Command was sent to.

Enum"EVSE""VEHICLE"

reason_not_sentstring or nullread-only

If the dispatch command was not sent, provides a reason.

{
  "logged_at": "2019-08-24T14:15:22Z",
  "charging_sub_session": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
  "schedule_valid_period_start": "2019-08-24T14:15:22Z",
  "schedule_created_at": "2019-08-24T14:15:22Z",
  "internal_command_id": "12345678-1234-5678-1234-567812345678",
  "device_type": "EVSE",
  "reason_not_sent": "string"
}

List charging sub sessions

Request

List all charging sub sessions visible to the authenticated client.

Security

oauth2(Required scopes:

charging_session: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"evse""evse.latest_status_log""evse.model""evse.model.make""evse.user""vehicle""vehicle.latest_status_log""vehicle.trim""vehicle.trim.model""vehicle.trim.model.make"

evse_idstringevse[A-Z\d]{26}

Filter to only resources related to the given EVSE.

Example: evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5

vehicle_idstringvhcl[A-Z\d]{26}

Filter to only resources related to the given Vehicle.

Example: vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H

user_idstring

Filter collection to only resources owned by a specific user.

Example: user_id=me

energy_delivered_watt_hours__gteinteger

Filters for values greater than or equal to a value.

Example: energy_delivered_watt_hours__gte=500

energy_delivered_watt_hours__lteinteger

Filters for values less than or equal to a value.

Example: energy_delivered_watt_hours__lte=500

is_finishedboolean

Filters for sessions that are finished.

Example: is_finished=false

modestring

Filters sessions to only return sessions with this mode.

Enum"SMART""BOOST""UNMANAGED_HOME""UNMANAGED_OTG""MANAGED_OTG"

Example: mode=SMART

start__gtstring(date-time)

Only return sessions that started after the passed date

start__ltstring(date-time)

Only return sessions that started before the passed date

end__gtstring(date-time)

Only return sessions that ended after the passed date

end__ltstring(date-time)

Only return sessions that ended before the passed date

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/charging_sub_sessions?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=evse&evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5&vehicle_id=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H&user_id=me&energy_delivered_watt_hours__gte=500&energy_delivered_watt_hours__lte=500&is_finished=false&mode=SMART&start__gt=2019-08-24T14%3A15%3A22Z&start__lt=2019-08-24T14%3A15%3A22Z&end__gt=2019-08-24T14%3A15%3A22Z&end__lt=2019-08-24T14%3A15%3A22Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of charging sub sessions, 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=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H>; rel=\"previous\", <https://api.ev.energy/v2/vehicles?page_size=25&page_after=vhcl01HRFF3SEVSCRAV9B3CHVDFN0H>; 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 [

idstringcsub[A-Z\d]{26}read-only

Unique identifier for the given Charging sub-session.

Example: "csub01HSH04KDEWF6Z4DB2J77J74K5"

urlstring(uri)

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

startstring(date-time)read-only

endstring or null(date-time)read-only

modeanyread-only

The type of scheduling applied during this period.

smart: Actively optimised charging

boost: Charge immediately

unmanaged: No optimisation

Enum"SMART""BOOST""UNMANAGED_HOME""UNMANAGED_OTG""MANAGED_OTG"

vehicle(string or null) or Vehicle (object)

One of:

string or null(uri)

evse(string or null) or EVSE (object)

One of:

string or null(uri)

energy_delivered_watt_hoursintegerread-only

Net energy delivered to the vehicle during this sub-session in Wh.

Example: 2300

costinteger or nullread-only

Example: 634

locationobject

percentage_addednumber or nullread-only

Example: 30

currencystringread-only

Example: "GBP"

savings_costinteger or nullread-only

Cost Savings in Minor Unit of Currency.

savings_co2_gramsinteger or nullread-only

Savings of Carbon in Grams of CO2.

incentive_earnedinteger or nullread-only

Incentive earned in minor unit of currency.

Example: 99

total_co2_gramsinteger or null

Estimated total CO2 emissions of this session in grams

co2_intensity_grams_per_kilowatt_hourinteger or null

Estimated CO2 emissions per unit of electricity in grams per kilowatt hour

co2_intensity_classificationanyread-only

Classification of the estimated CO2 intensity value. Can be null.

Enum"very low""low""moderate""high""very high"

cost_per_kilowatt_hourinteger or null

Average cost per kilowatt hour of energy delivered during this charging session

total_pointsinteger

Number of smart points earning during this charging session

total_points_missedinteger or null

Difference between the number of smart points earned in this session and the number that would have been earned by Smart charging

duration_minutesinteger

How long the vehicle was actively charging for, to the nearest minute

grid_energy_delivered_watt_hoursintegerread-only

Grid energy delivered during this charging sub-session in watt hours (Wh).

solar_energy_delivered_watt_hoursintegerread-only

Solar energy delivered during this charging sub-session in watt hours (Wh).

labelsArray of strings or nullread-only

Labels categorizing this charging session (e.g., service territory, pricing period).

Enum"OUTSIDE""OFF_PEAK""SUMMER_PEAK""MIXED""OTHER""PRIMARY""AWAY""CONED""ORU"

energy_usagestring or EnergyUsage (object)

A link to more detailed information about energy usage during the charging sub-session. Can be expanded.

One of:

A link to more detailed information about energy usage during the charging sub-session. Can be expanded.

string(uri)read-only

schedulesstring or Array of ScheduleInterval (objects)read-only

A link to schedule information for the charging sub-session. Can be expanded.

One of:

A link to schedule information for the charging sub-session. Can be expanded.

string(uri)read-only

tariffstring or Tariff (object) or nullread-only

The electricity import tariff. Expandable with ?expand=tariff. Requires tariff:read scope.

One of:

The electricity import tariff. Expandable with ?expand=tariff. Requires tariff:read scope.

string(uri)read-only

grid_energy_deliveredstring(decimal)Deprecatedread-only

Use grid_energy_delivered_watt_hours instead

solar_energy_deliveredstring(decimal)Deprecatedread-only

Use solar_energy_delivered_watt_hours instead.

]

Response

application/json

[
  {
    "id": "csub01HSH04KDEWF6Z4DB2J77J74K5",
    "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
    "start": "2019-08-24T14:15:22Z",
    "end": "2019-08-24T14:15:22Z",
    "mode": "SMART",
    "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "evse": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
    "energy_delivered_watt_hours": 2300,
    "cost": 634,
    "location": { … },
    "percentage_added": 30,
    "currency": "GBP",
    "savings_cost": 0,
    "savings_co2_grams": 0,
    "incentive_earned": 99,
    "total_co2_grams": 0,
    "co2_intensity_grams_per_kilowatt_hour": 0,
    "co2_intensity_classification": "very low",
    "cost_per_kilowatt_hour": 0,
    "total_points": 0,
    "total_points_missed": 0,
    "duration_minutes": 0,
    "grid_energy_delivered_watt_hours": 0,
    "solar_energy_delivered_watt_hours": 0,
    "labels": [ … ],
    "energy_usage": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage",
    "schedules": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules",
    "tariff": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
    "grid_energy_delivered": "string",
    "solar_energy_delivered": "string"
  }
]

Retrieve a charging sub-session

Request

Retrieve a specific charging sub-session, representing a period of charging in a single mode.

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 Enum"evse""evse.latest_status_log""evse.model""evse.model.make""evse.user""vehicle""vehicle.latest_status_log""vehicle.trim""vehicle.trim.model""vehicle.trim.model.make"

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/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5?expand=evse' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns information about a single charging sub-session.

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

idstringcsub[A-Z\d]{26}read-only

Unique identifier for the given Charging sub-session.

Example: "csub01HSH04KDEWF6Z4DB2J77J74K5"

urlstring(uri)

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

startstring(date-time)read-only

endstring or null(date-time)read-only

modeanyread-only

The type of scheduling applied during this period.

smart: Actively optimised charging

boost: Charge immediately

unmanaged: No optimisation

Enum"SMART""BOOST""UNMANAGED_HOME""UNMANAGED_OTG""MANAGED_OTG"

vehicle(string or null) or Vehicle (object)

One of:

string or null(uri)

evse(string or null) or EVSE (object)

One of:

string or null(uri)

energy_delivered_watt_hoursintegerread-only

Net energy delivered to the vehicle during this sub-session in Wh.

Example: 2300

costinteger or nullread-only

Example: 634

locationobject

percentage_addednumber or nullread-only

Example: 30

currencystringread-only

Example: "GBP"

savings_costinteger or nullread-only

Cost Savings in Minor Unit of Currency.

savings_co2_gramsinteger or nullread-only

Savings of Carbon in Grams of CO2.

incentive_earnedinteger or nullread-only

Incentive earned in minor unit of currency.

Example: 99

total_co2_gramsinteger or null

Estimated total CO2 emissions of this session in grams

co2_intensity_grams_per_kilowatt_hourinteger or null

Estimated CO2 emissions per unit of electricity in grams per kilowatt hour

co2_intensity_classificationanyread-only

Classification of the estimated CO2 intensity value. Can be null.

Enum"very low""low""moderate""high""very high"

cost_per_kilowatt_hourinteger or null

Average cost per kilowatt hour of energy delivered during this charging session

total_pointsinteger

Number of smart points earning during this charging session

total_points_missedinteger or null

Difference between the number of smart points earned in this session and the number that would have been earned by Smart charging

duration_minutesinteger

How long the vehicle was actively charging for, to the nearest minute

grid_energy_delivered_watt_hoursintegerread-only

Grid energy delivered during this charging sub-session in watt hours (Wh).

solar_energy_delivered_watt_hoursintegerread-only

Solar energy delivered during this charging sub-session in watt hours (Wh).

labelsArray of strings or nullread-only

Labels categorizing this charging session (e.g., service territory, pricing period).

Enum"OUTSIDE""OFF_PEAK""SUMMER_PEAK""MIXED""OTHER""PRIMARY""AWAY""CONED""ORU"

energy_usagestring or EnergyUsage (object)

A link to more detailed information about energy usage during the charging sub-session. Can be expanded.

One of:

A link to more detailed information about energy usage during the charging sub-session. Can be expanded.

string(uri)read-only

schedulesstring or Array of ScheduleInterval (objects)read-only

A link to schedule information for the charging sub-session. Can be expanded.

One of:

A link to schedule information for the charging sub-session. Can be expanded.

string(uri)read-only

tariffstring or Tariff (object) or nullread-only

The electricity import tariff. Expandable with ?expand=tariff. Requires tariff:read scope.

One of:

The electricity import tariff. Expandable with ?expand=tariff. Requires tariff:read scope.

string(uri)read-only

grid_energy_deliveredstring(decimal)Deprecatedread-only

Use grid_energy_delivered_watt_hours instead

solar_energy_deliveredstring(decimal)Deprecatedread-only

Use solar_energy_delivered_watt_hours instead.

Response

application/json

{
  "id": "csub01HSH04KDEWF6Z4DB2J77J74K5",
  "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
  "start": "2019-08-24T14:15:22Z",
  "end": "2019-08-24T14:15:22Z",
  "mode": "SMART",
  "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
  "evse": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
  "energy_delivered_watt_hours": 2300,
  "cost": 634,
  "location": {
    "name": "Home",
    "coordinates": { … },
    "postal_code": "string",
    "address_1": "string",
    "timezone": "Europe/London"
  },
  "percentage_added": 30,
  "currency": "GBP",
  "savings_cost": 0,
  "savings_co2_grams": 0,
  "incentive_earned": 99,
  "total_co2_grams": 0,
  "co2_intensity_grams_per_kilowatt_hour": 0,
  "co2_intensity_classification": "very low",
  "cost_per_kilowatt_hour": 0,
  "total_points": 0,
  "total_points_missed": 0,
  "duration_minutes": 0,
  "grid_energy_delivered_watt_hours": 0,
  "solar_energy_delivered_watt_hours": 0,
  "labels": [
    "OUTSIDE"
  ],
  "energy_usage": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/energy_usage",
  "schedules": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules",
  "tariff": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "grid_energy_delivered": "string",
  "solar_energy_delivered": "string"
}

Retrieve periodic energy usage intervals for a charging sub-session

Request

Retrieve periodic energy usage intervals for a specific charging sub-session.

If you are looking for intervals that cover the whole time energy is being delivered (which are therefore of irregular length) use the merge_consecutive_intervals query parameter.

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.

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

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/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

application/json

{
  "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"
}

Retrieve schedules for a charging sub-session

Request

Retrieve schedules for a specific charging sub-session.

Schedules represent charging instructions for a charging session. Each schedule specifies a current (in milliamps) and a time period during which that current should be applied.

Security

oauth2(Required scopes:

chargingsession: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"

started_at__gtestring(date-time)

Filter schedules with started_at greater than or equal to this datetime.

started_at__ltestring(date-time)

Filter schedules with started_at less than or equal to this datetime.

schedule_plan_idstringscpl[A-Z\d]{26}

Filter schedules generated from a specific schedule plan.

Example: schedule_plan_id=scpl01HSH04KDEWF6Z4DB2J77J74K5

only_most_recently_createdboolean

Only show the most recently created schedule for each time period

Default true

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/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules?expand=charging_sub_session&started_at__gte=2019-08-24T14%3A15%3A22Z&started_at__lte=2019-08-24T14%3A15%3A22Z&schedule_plan_id=scpl01HSH04KDEWF6Z4DB2J77J74K5&only_most_recently_created=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

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

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/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules"

charging_sub_sessionstring or SubSession (object)read-only

The charging sub-session these schedules belong to. Defaults to a url, but can be expanded to the full ChargingSubSession resource via the expand query parameter.

One of:

The charging sub-session these schedules belong to. Defaults to a url, but can be expanded to the full ChargingSubSession resource via the expand query parameter.

string(uri)read-only

schedulesArray of objects(ScheduleInterval)read-only

A list of schedule intervals for this charging sub-session.

Response

application/json

{
  "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedules",
  "charging_sub_session": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
  "schedules": [
    { … }
  ]
}

Retrieve schedule plans for a charging sub-session

Request

Retrieve schedule plans for a specific charging sub-session.

Schedule plans represent the charging plan parameters used to generate schedules for a charging session. Each plan contains information about the ready-by time, charging requirements, and constraints that were used to create the charging schedule.

Security

oauth2(Required scopes:

debug: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"

created_at__gtestring(date-time)

Filter schedule plans with created_at greater than or equal to this datetime.

created_at__ltestring(date-time)

Filter schedule plans with created_at less than or equal to this datetime.

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/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedule_plans?expand=charging_sub_session&created_at__gte=2019-08-24T14%3A15%3A22Z&created_at__lte=2019-08-24T14%3A15%3A22Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns schedule plans for a charging sub-session.

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/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedule_plans"

charging_sub_sessionstring or SubSession (object)read-only

The charging sub-session these schedule plans belong to. Defaults to a url, but can be expanded to the full ChargingSubSession resource via the expand query parameter.

One of:

The charging sub-session these schedule plans belong to. Defaults to a url, but can be expanded to the full ChargingSubSession resource via the expand query parameter.

string(uri)read-only

schedule_plansArray of objects(SchedulePlan)read-only

A list of schedule plans for this charging sub-session.

Response

application/json

{
  "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/schedule_plans",
  "charging_sub_session": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
  "schedule_plans": [
    { … }
  ]
}

List dispatcher logs

Request

List all dispatcher logs for a charging session. These logs record Dispatch Command attempts to EVSEs or Vehicles.

Security

oauth2(Required scopes:

debug:read

)

Query

expandArray of strings

Specify a url field to expand into a nested resource.

Items Value"charging_sub_session"

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

Filter dispatcher logs to a specific charging sub-session.

Example: charging_sub_session_id=csub01HSH04KDEWF6Z4DB2J77J74K5

logged_at__gtestring(date-time)

Only return logs that were logged at or after the passed date.

logged_at__ltestring(date-time)

Only return logs that were logged at or before the passed date.

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/dispatcher_logs?expand=charging_sub_session&charging_sub_session_id=csub01HSH04KDEWF6Z4DB2J77J74K5&logged_at__gte=2019-08-24T14%3A15%3A22Z&logged_at__lte=2019-08-24T14%3A15%3A22Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of dispatcher logs, 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.

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 [

logged_atstring(date-time)read-only

The date and time when the dispatch command was logged.

charging_sub_sessionstring or SubSession (object)read-only

The charging sub-session associated with this dispatch log.

One of:

The charging sub-session associated with this dispatch log.

string(uri)read-only

schedule_valid_period_startstring(date-time)read-only

The start of the validity period for the schedule that generated this dispatch command.

schedule_created_atstring(date-time)read-only

When the schedule that generated this dispatch command was created.

internal_command_idstring(uuid)read-only

Internal identifier for tracking the dispatch command.

Example: "12345678-1234-5678-1234-567812345678"

device_typestringread-only

The type of device the Dispatch Command was sent to.

Enum"EVSE""VEHICLE"

reason_not_sentstring or nullread-only

If the dispatch command was not sent, provides a reason.

]

Response

application/json

[
  {
    "logged_at": "2019-08-24T14:15:22Z",
    "charging_sub_session": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
    "schedule_valid_period_start": "2019-08-24T14:15:22Z",
    "schedule_created_at": "2019-08-24T14:15:22Z",
    "internal_command_id": "12345678-1234-5678-1234-567812345678",
    "device_type": "EVSE",
    "reason_not_sent": "string"
  }
]

Charging sub-session createdWebhook

Request

A charging sub-session is created, representing a period of charging in a single mode.

Security

oauth2

Bodyapplication/json

Returns information about the charging sub-session that has been created.

typestring

Value"charging_sub_session.created"

timestampstring(date-time)

The timestamp of the event described by this webhook

dataobject(ChargingSubSession)

The charging sub session being created

application/json

{
  "type": "charging_sub_session.created",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "id": "csub01HSH04KDEWF6Z4DB2J77J74K5",
    "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
    "start": "2019-08-24T14:15:22Z",
    "end": null,
    "mode": "smart",
    "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "evse": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
    "energy_delivered_watt_hours": 0,
    "cost": 0,
    "percentage_added": 0,
    "location": { … },
    "currency": "GBP"
  }
}

Responses

Return a 200 status to indicate that the data was received successfully.

Charging sub-session endedWebhook

Request

A charging sub-session has ended, representing a period of charging in a single mode.

Security

oauth2

Bodyapplication/json

Returns information about the charging sub-session that ended.

typestring

Value"charging_sub_session.ended"

timestampstring(date-time)

The timestamp of the event described by this webhook

dataobject(ChargingSubSession)

The charging sub session being created

application/json

{
  "type": "charging_sub_session.ended",
  "timestamp": "2022-11-03T20:26:10.344522Z",
  "data": {
    "id": "csub01HSH04KDEWF6Z4DB2J77J74K5",
    "url": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5",
    "start": "2019-08-24T14:15:22Z",
    "end": "2019-08-24T14:15:22Z",
    "mode": "smart",
    "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "evse": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
    "energy_delivered_watt_hours": 2300,
    "cost": 634,
    "percentage_added": 30,
    "location": { … },
    "currency": "GBP"
  }
}

Responses

Return a 200 status to indicate that the data was received successfully.

Carbon

Charging Sessions

DispatcherLog

List charging sub sessions

Request

Responses

Was this helpful?

Retrieve a charging sub-session

Request

Responses

Was this helpful?

Retrieve periodic energy usage intervals for a charging sub-session

Request

Responses

Was this helpful?

Retrieve schedules for a charging sub-session

Request

Responses

Was this helpful?

Retrieve schedule plans for a charging sub-session

Request

Responses

Was this helpful?

List dispatcher logs

Request

Responses

Was this helpful?

Charging sub-session createdWebhook

RequestExpand all

Responses

Was this helpful?

Charging sub-session endedWebhook

RequestExpand all

Responses

Was this helpful?

CSV

EVSEs

Notifications

Programs

Rebates

Root

Schedules

Sites

Solar

Subscriptions

Support Tickets

Tariffs

Users

Vehicles

Webhooks

ev.energy v2 API (2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Request

Request