Retrieve a charging sub-session

Request

Retrieve a specific charging sub-session, representing a period of a plug-in episode during which a single charging mode was active. Its start/end mark when the mode started and stopped being active — not plug-in/plug-out times, and not when energy was actually flowing. See Understanding charging data.

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"

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

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

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

Unique identifier for the given Charging sub-session.

Example:"csub01HSH04KDEWF6Z4DB2J77J74K5"

urlstring, (uri)required

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

startstring, (date-time)read-onlyrequired

When this sub-session began — either when the vehicle was plugged in, or when the charging mode changed (e.g. the user activated boost). Not necessarily when energy started flowing; see the energy_usage endpoint for actual delivery intervals.

endstring or null, (date-time)read-onlyrequired

When this sub-session ended — either when the vehicle was unplugged, or when the charging mode changed again. Null while the sub-session is ongoing. Energy delivery often finishes well before this time (e.g. once the target charge level is reached).

modeanyread-onlyrequired

The type of scheduling applied during this period.

SMART: Actively optimised charging

BOOST: Charge immediately

UNMANAGED_HOME: No optimisation, at a home location

UNMANAGED_OTG: No optimisation, at an on-the-go (public) location

MANAGED_OTG: Optimised charging at an on-the-go (public) location

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

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

Example:2300

costinteger or nullread-onlyrequired

Example:634

locationobjectrequired

percentage_addednumber or nullread-only

Example:30

currencystringread-onlyrequired

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 nullrequired

Estimated total CO2 emissions of this sub-session in grams

co2_intensity_grams_per_kilowatt_hourinteger or nullrequired

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

co2_intensity_classificationany or nullread-onlyrequired

One of:

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

anyread-only

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 sub-session

total_pointsinteger

Number of smart points earned during this charging sub-session

total_points_missedinteger or null

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

duration_minutesintegerrequired

How long the vehicle was actively charging for, to the nearest minute. This can be much shorter than the gap between start and end, and does not tell you when within the sub-session energy was delivered — use the energy_usage endpoint for that.

grid_energy_delivered_watt_hoursinteger or nullread-onlyrequired

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

solar_energy_delivered_watt_hoursinteger or nullread-onlyrequired

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

labelsArray of strings or nullread-only

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

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

energy_usagestring or EnergyUsage (object)

One of:

A link to more detailed information about energy usage during the charging sub-session, including the intervals in which energy was actually delivered to the vehicle. Can be expanded.

string (uri)read-only

schedulesstring or Schedules (object)read-only

One of:

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

string (uri)read-only

assessmentstring or ChargingSubSessionAssessment (object)read-only

One of:

A link to the performance assessment for this charging sub-session. Can be expanded. Requires debug:read scope.

string (uri)read-only

flagsstring or ChargingSubSessionFlags (object)read-only

One of:

A link to flags associated with this charging sub-session. Can be expanded.

string (uri)read-only

debug_metadatastring or ChargingSubSessionDebugMetadata (object)read-only

One of:

A link to debug metadata for this charging sub-session. Can be expanded. Requires debug:read scope.

string (uri)read-only

tariffstring or Tariff (object) or nullread-only

One of:

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

string (uri)read-only

carbon_feedstring or CarbonFeed (object) or nullread-only

One of:

The carbon feed used to calculate carbon intensity for this sub-session. Expandable with ?expand=carbon_feed. Requires carbon:read scope.

string (uri)read-only

grid_feedsArray of strings or Array of objectsread-only

One of:

Grid feeds applied to this sub-session. Expandable with ?expand=grid_feeds. Requires grid:read scope.

Array of strings (uri)read-only

solar_mode_typestring or nullread-only

The solar charging mode active for this sub-session. Null when solar charging is not configured.

Enum:"OFF""SOLAR_ONLY""SOLAR_AND_GRID""SOLAR_SMART"null

grid_energy_deliveredstring, (decimal)read-onlydeprecated

Use grid_energy_delivered_watt_hours instead

solar_energy_deliveredstring, (decimal)read-onlydeprecated

Use solar_energy_delivered_watt_hours instead.

Response

{
  "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",
  "assessment": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/assessment",
  "flags": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/flags",
  "debug_metadata": "https://api.ev.energy/v2/charging_sub_sessions/csub01HSH04KDEWF6Z4DB2J77J74K5/debug_metadata",
  "tariff": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "carbon_feed": "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735",
  "grid_feeds": [
    "https://api.ev.energy/v2/grid_feeds/grfd01HN2NJ9NMRZBXT1H6FT9N7735"
  ],
  "solar_mode_type": "OFF",
  "grid_energy_delivered": "string",
  "solar_energy_delivered": "string"
}