Skip to content
/
List EVSEs

List EVSEs

Request

List all the EVSEs that the authorization token has access to.

Security
oauth2(Required scopes: evse: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:"user""model""model.make""latest_status_log""ct_clamp"
cpidstring

Filter EVSEs by chargepoint ID (exact match).

Example:cpid=SHIR100001
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
EvEnergy-Userstringuser[A-Z\d]{26}

If the client is authenticated using Client Credentials, setting EvEnergy-User to a valid user ID allows requests to be made as if you were directly authenticated as that user.

Example:user01HN2NJ9NMRZBXT1H6FT9N7735
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/evses?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=user&cpid=SHIR100001' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of EVSEs.

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
Array [
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
userstring or User (object)read-only
Example:"https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
One of:
string (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"
]
Response
[
  {
    "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": { … },
    "lifecycle_state": "COMMISSIONED",
    "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5"
  }
]