Skip to content
/
Charging sub-session ende...

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

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.

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

Webhooks

Endpoints for configuring and managing webhooks.

Operations