Skip to content
/
Retrieve an EVSE Site

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

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

List EVSE Sites

Request

List all available EVSE Sites

Security
oauth2(Required scopes:
site:read
)
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
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/evse_sites \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

OK

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 [
idstringsite[A-Z\d]{26}read-only
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7"
evsesArray of strings(uri)read-only

A list of all EVSEs that are currently associated with this site.

cpms_connectionstring or nullread-only

The type of ChargePoint Management System that this site is connected to, if there is one.

Enumnull"CHARGEPOINT""SWTCH"
cpms_connection_display_namestring or null

A human-readable name for the Chargepoint Management System that the site is connected to.

Example: "ChargePoint"
user_connectedboolean or nullread-only

When authenticated as a specific user (eg. via the Authorisation Code grant type) or when the EvEnergy-User header is set to a valid user ID, this field will indicate whether the user is currently connected to this EVSE Site's CPMS. If the request is not made in the context of a user, or the site does not have a CPMS connection, this field will be null.

]
Response
application/json
[
  {
    "id": "site01JX2SZ0WAFTDYVYY0JRAYREY7",
    "url": "https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7",
    "evses": [ … ],
    "cpms_connection": null,
    "cpms_connection_display_name": "ChargePoint",
    "user_connected": true
  }
]

Retrieve an EVSE Site

Request

Retrieve a single, specific EVSESite's details.

Security
oauth2(Required scopes:
site:read
)
Path
evse_site_idstringsite[A-Z\d]{26}required

Unique identifier for a single EVSE Site.

Example: site01JX2SZ0WAFTDYVYY0JRAYREY7
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value2
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/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a single EVSE Site.

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
idstringsite[A-Z\d]{26}read-only
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7"
evsesArray of strings(uri)read-only

A list of all EVSEs that are currently associated with this site.

cpms_connectionstring or nullread-only

The type of ChargePoint Management System that this site is connected to, if there is one.

Enumnull"CHARGEPOINT""SWTCH"
cpms_connection_display_namestring or null

A human-readable name for the Chargepoint Management System that the site is connected to.

Example: "ChargePoint"
user_connectedboolean or nullread-only

When authenticated as a specific user (eg. via the Authorisation Code grant type) or when the EvEnergy-User header is set to a valid user ID, this field will indicate whether the user is currently connected to this EVSE Site's CPMS. If the request is not made in the context of a user, or the site does not have a CPMS connection, this field will be null.

Response
application/json
{
  "id": "site01JX2SZ0WAFTDYVYY0JRAYREY7",
  "url": "https://api.ev.energy/v2/evse_sites/site01JX2SZ0WAFTDYVYY0JRAYREY7",
  "evses": [
    "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5"
  ],
  "cpms_connection": null,
  "cpms_connection_display_name": "ChargePoint",
  "user_connected": true
}

List CPMS Providers

Request

Get a list of all the ChargePoint Management System Providers that we integrate with.

Security
oauth2
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
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/cpms_providers?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

OK

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 [
idany
Enum"CHARGEPOINT""SWTCH"
urlstring
Example: "https://api.ev.energy/v2/cpms_providers/CHARGEPOINT/"
namestring
iconstring or null(uri)
]
Response
application/json
[
  {
    "id": "CHARGEPOINT",
    "url": "https://api.ev.energy/v2/cpms_providers/CHARGEPOINT/",
    "name": "string",
    "icon": "http://example.com"
  }
]

Retrieve a CPMS Provider

Request

Get details on a single CPMS provider.

Security
oauth2
Path
cpms_provider_idstringrequired

The ID of the specific provider to retrieve.

Value"CHARGEPOINT"
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/cpms_providers/{cpms_provider_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

OK

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
idany
Enum"CHARGEPOINT""SWTCH"
urlstring
Example: "https://api.ev.energy/v2/cpms_providers/CHARGEPOINT/"
namestring
iconstring or null(uri)
Response
application/json
{
  "id": "CHARGEPOINT",
  "url": "https://api.ev.energy/v2/cpms_providers/CHARGEPOINT/",
  "name": "string",
  "icon": "http://example.com"
}

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