Skip to content

EVSE

A resource that represents a single, physical piece of hardware for supplying electricity to an electric vehicle.

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

Unique identifier for the given EVSE.

Example:"evse01HSH04KDEWF6Z4DB2J77J74K5"
urlstring, (uri)read-onlyrequired
Example:"https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5"
cpidstringread-onlyrequired

A unique identifier for the chargepoint. The format varies by manufacturer and model.

Example:"SHIR100001"
modelstring or Model (object)read-only
One of:
string (uri)read-only
user(string or null) or User (object)read-only
Example:"https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
One of:

Defaults to a url, but can be expanded to the full User resource via the expand query parameter. Null when the EVSE has no owner, or when an organisation calls and the owner is not a member of it.

string or null (uri)read-only
latest_status_log(string or null) or EVSEStatusLog (object)read-only
Example:"https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/"
One of:

An expandable reference to the most recent status log for this EVSE. This can be requested or expanded to get the most accurate information we have on the device's current status.

Inferring reachability: v2 deliberately does not expose a discrete online/offline state on the EVSE resource — the boundary is fuzzy and prone to misuse. To decide whether an EVSE is currently reachable, expand latest_status_log (or fetch it separately) and compare its sampled_at timestamp against your own staleness threshold (for example: a charger silent for more than 15 minutes is likely unreachable).

string or null (uri)read-only
ct_clamp(string or null) or CTClamp (object)read-only
One of:

An expandable reference to the CT clamp associated with this EVSE. Will be null if no CT clamp is installed.

string or null (uri)read-only
lock_modestring or nullread-only

Lock mode of the EVSE. UNLOCKED allows free charging, SMART only allows charging within smart-charging hours, LOCKED blocks all charging.

Enum:"UNLOCKED""SMART""LOCKED"null
Example:"UNLOCKED"
locationobject or null

The geographic location of the EVSE as a latitude/longitude point.

Why smart charging needs it: the location tells ev.energy which electricity grid the charger sits on, which drives the core smart-charging decisions:

  • Carbon optimisation — selects the local carbon-intensity feed so charging is shifted to the lowest-carbon periods.
  • Timezone — resolves the charger's timezone so time-of-day charging schedules and tariff windows are applied in local time.
  • Programs and solar — determines the eligible grid/demand-response programs and the relevant solar forecast.

Without an accurate location the scheduler cannot reliably optimise charging for cost and carbon.

When it is set: during commissioning, where the supplied postcode/address is geocoded to a latitude/longitude (or, for app-linked chargers, copied from the owner's home location). It can be corrected later via PATCH. Null when the location has not yet been determined.

Example:
{
  "latitude": 51.5074,
  "longitude": -0.1278
}
lifecycle_statestring or nullread-only

The most recently recorded stage of the EVSE's onboarding lifecycle. Null when no stage has been recorded for it yet, which is normal for a charger that has only just been created.

Enum:"CREATED_LINKED""INSTALLED""COMMISSIONED""DECOMMISSIONED""UNKNOWN""PROBABLY_INSTALLED""UNPAIRED""PENDING""ENROLLED"null
Example:"COMMISSIONED"
charging_sub_sessionsstring, (uri)

Provides a pre-constructed URL to list charging sub-sessions involving this EVSE.

Example:"https://api.ev.energy/charging_sub_sessions/?evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5"
{
  "id": "evse01HSH04KDEWF6Z4DB2J77J74K5",
  "url": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
  "cpid": "SHIR100001",
  "model": "https://api.ev.energy/v2/evse_models/emod01HS9A004X5TB5JCMHENB5Z446",
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735",
  "latest_status_log": "https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/",
  "ct_clamp": "https://api.ev.energy/v2/ct_clamps/ctcl01HSH04KDEWF6Z4DB2J77J74K5",
  "lock_mode": "UNLOCKED",
  "location": {
    "latitude": 51.5074,
    "longitude": -0.1278
  },
  "lifecycle_state": "COMMISSIONED",
  "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5"
}