Skip to content
/
List carbon feeds

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

CarbonFeed

A carbon feed representing a source of carbon intensity data for a specific region or grid.

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

Unique identifier for the carbon feed.

Example: "cabf01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)read-onlyrequired
Example: "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735"
namestringread-onlyrequired

Human-readable name for the carbon feed.

Example: "UK National Grid"
{
  "id": "cabf01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "UK National Grid"
}

CarbonIntensity

A carbon intensity data point representing CO2 emissions per unit of electricity generated.

started_atstring(date-time)read-onlyrequired

When this interval began.

Example: "2024-01-15T10:00:00Z"
interval_secondsintegerread-onlyrequired

The number of seconds that this interval lasts for.

Example: 1800
co2_intensity_grams_per_kilowatt_hourintegerread-onlyrequired

Carbon intensity in gCO2/kWh.

Example: 245
created_atstring(date-time)read-onlyrequired

When this record was created (ISO 8601 datetime).

Example: "2024-01-15T09:45:00Z"
{
  "started_at": "2024-01-15T10:00:00Z",
  "interval_seconds": 1800,
  "co2_intensity_grams_per_kilowatt_hour": 245,
  "created_at": "2024-01-15T09:45:00Z"
}

List carbon feeds

Request

List all carbon feeds visible to the authenticated client. Carbon feeds represent sources of carbon intensity data for specific regions or grids.

Security
oauth2(Required scopes:
carbon: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
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/carbon_feeds?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of carbon feeds, sorted by name.

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 [
idstringcabf[A-Z\d]{26}read-onlyrequired

Unique identifier for the carbon feed.

Example: "cabf01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)read-onlyrequired
Example: "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735"
namestringread-onlyrequired

Human-readable name for the carbon feed.

Example: "UK National Grid"
]
Response
application/json
[
  {
    "id": "cabf01HN2NJ9NMRZBXT1H6FT9N7735",
    "url": "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735",
    "name": "UK National Grid"
  }
]

Retrieve a carbon feed

Request

Retrieve a specific carbon feed, representing a source of carbon intensity data for a region or grid.

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

Uniquely identify a specific carbon feed.

Example: cabf01HN2NJ9NMRZBXT1H6FT9N7735
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/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns information about a single carbon feed.

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
idstringcabf[A-Z\d]{26}read-onlyrequired

Unique identifier for the carbon feed.

Example: "cabf01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)read-onlyrequired
Example: "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735"
namestringread-onlyrequired

Human-readable name for the carbon feed.

Example: "UK National Grid"
Response
application/json
{
  "id": "cabf01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "UK National Grid"
}

List carbon intensity data

Request

Returns a paginated list of carbon intensity data points for a specific carbon feed. Carbon intensity represents the amount of CO2 emissions per unit of electricity generated, measured in grams of CO2 per kilowatt-hour (gCO2/kWh).

Use started_at__gte and started_at__lte to filter by time range.

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

Uniquely identify a specific carbon feed.

Example: cabf01HN2NJ9NMRZBXT1H6FT9N7735
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 Value"carbon_feed"
started_at__gtestring(date-time)

Filter for entries on or after this datetime (ISO 8601).

Example: started_at__gte=2024-01-15T10:00:00Z
started_at__ltestring(date-time)

Filter for entries on or before this datetime (ISO 8601).

Example: started_at__lte=2024-01-15T12:00:00Z
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/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735/carbon_intensities?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=carbon_feed&started_at__gte=2024-01-15T10%3A00%3A00Z&started_at__lte=2024-01-15T12%3A00%3A00Z' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of carbon intensity data points, sorted by started_at descending.

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/json
urlstring(uri)read-only
Example: "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735/carbon_intensities"
carbon_feedstring(uri)read-only
Example: "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735"
carbon_intensitiesArray of objects(CarbonIntensity)read-only

A list of carbon intensity data points.

Response
application/json
{
  "url": "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735/carbon_intensities",
  "carbon_feed": "https://api.ev.energy/v2/carbon_feeds/cabf01HN2NJ9NMRZBXT1H6FT9N7735",
  "carbon_intensities": [
    { … }
  ]
}

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

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