Skip to content
/
Retrieve a tariff

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

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

Tariff

Note: daily_prices and type are only available under contract. Please reach out to your account manager to find out more.

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

Unique identifier for the given user.

Example: "tari01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735"
supplierstring or Supplier (object)required

The energy company that supplies this tariff.

One of:

The energy company that supplies this tariff.

string(uri)
namestringrequired
Example: "Fangorn Biomass"
currencystringrequired
Example: "GBP"
highlightedboolean

A highlighted tariff is one that is often selected by users.

typeany
Enum"FLAT_RATE""DUAL_RATE""THREE_RATE""DYNAMIC""EXTERNALLY_MANAGED""OTHER"
daily_pricesobject(DailyPrices)[ 1 .. 3 ] properties

The times returned here are localised to the timezone the tariff is in. The timezone is returned in timezone_name.

timezone_namestring
Example: "Europe/London"
price_chart_urlstring or null

The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.

Example: "https://www.example.com/"
{
  "id": "tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "supplier": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "Fangorn Biomass",
  "currency": "GBP",
  "daily_prices": {
    "peak": { … },
    "mid_peak": { … },
    "off_peak": { … }
  }
}

TariffDetail

Note: daily_prices and type are only available under contract. Please reach out to your account manager to find out more.

current_priceinteger or null

The price of the tariff at the current time, given in the smallest unit of the currency of the tariff. For example, 10 means 10 pence.

Example: 10
pricesstring or Array of Price (objects) or nullread-only

Link to prices endpoint by default. When expanded with ?expand=prices, returns the past 24 hours of prices. Requires tariff:prices:read scope.

One of:

Link to prices endpoint by default. When expanded with ?expand=prices, returns the past 24 hours of prices. Requires tariff:prices:read scope.

string(uri)read-only
idstringtari[A-Z\d]{26}read-onlyrequired

Unique identifier for the given user.

Example: "tari01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735"
supplierstring or Supplier (object)required

The energy company that supplies this tariff.

One of:

The energy company that supplies this tariff.

string(uri)
namestringrequired
Example: "Fangorn Biomass"
currencystringrequired
Example: "GBP"
highlightedboolean

A highlighted tariff is one that is often selected by users.

typeany
Enum"FLAT_RATE""DUAL_RATE""THREE_RATE""DYNAMIC""EXTERNALLY_MANAGED""OTHER"
daily_pricesobject(DailyPrices)[ 1 .. 3 ] properties

The times returned here are localised to the timezone the tariff is in. The timezone is returned in timezone_name.

timezone_namestring
Example: "Europe/London"
price_chart_urlstring or null

The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.

Example: "https://www.example.com/"
{
  "id": "tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "supplier": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "Fangorn Biomass",
  "currency": "GBP",
  "daily_prices": {
    "peak": { … },
    "mid_peak": { … },
    "off_peak": { … }
  },
  "current_price": 10,
  "prices": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735/prices"
}

Supplier

An energy company who supplies electricity tariffs.

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

Unique identifier for the given user.

Example: "supl01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735"
namestringrequired
Example: "Rivendell Renewables"
iconstring or null(uri)required
Example: "https://cdn.example.com/rivendell_renewables.jpg"
highlightedboolean

A highlighted supplier is one that is often selected by users.

{
  "id": "supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "Rivendell Renewables",
  "icon": "https://cdn.example.com/rivendell_renewables.jpg",
  "highlighted": true
}

Times

Defines a period of time.

startstring\d\d:\d\d:\d\d
Example: "18:00:00"
endstring\d\d:\d\d:\d\d
Example: "00:00:00"
{
  "start": "18:00:00",
  "end": "00:00:00"
}

PriceSummary

A single price for a certain time range.

pricestring

The price is in major currency units e.g. 0.10 means £0.10.

Example: "0.10"
timesArray of objects(Times)
{
  "price": "0.10",
  "times": [
    { … }
  ]
}

DailyPrices

Information about the tariff's prices for different parts of the day.

peakobject(PriceSummary)required

A single price for a certain time range.

peak.​pricestring

The price is in major currency units e.g. 0.10 means £0.10.

Example: "0.10"
peak.​timesArray of objects(Times)
mid_peakobject(PriceSummary)

A single price for a certain time range.

off_peakobject(PriceSummary)

A single price for a certain time range.

{
  "peak": {
    "price": "0.10",
    "times": [ … ]
  },
  "mid_peak": {
    "price": "0.10",
    "times": [ … ]
  },
  "off_peak": {
    "price": "0.10",
    "times": [ … ]
  }
}

Price

A price for a specific time interval.

started_atstring(date-time)read-onlyrequired

When this price interval began (ISO 8601 datetime).

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

The duration of this price interval in seconds.

Example: 1800
price_minor_unitsintegerread-onlyrequired

The price in minor currency units (e.g., pence for GBP).

Example: 10
{
  "started_at": "2024-01-15T10:00:00Z",
  "interval_seconds": 1800,
  "price_minor_units": 10
}

List suppliers, sorted alphabetically by name.

Request

List all the energy suppliers known by the ev.energy system.

Use the available_for_user_id query parameter to narrow the list to only those relevant to a specific user.

Security
oauth2(Required scopes:
tariff:read
)
Query
pagenumber

The page number to return results for.

Example: page=2
page_sizeinteger[ 1 .. 100 ]

Specify the number of results to return per page.

Default 25
Example: page_size=10
available_for_user_idstringuser[A-Z\d]{26}

Filter to only return resources available in the user's region and program.

Example: available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735
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/suppliers?page=2&page_size=10&available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Return a list of Suppliers.

Headers
Linkstring

Provides links to the previous and next pages of data, if they exist.

Example: "<about:blank>; rel=\"previous\", <https://api.ev.energy/v2/examples/?page=2&page_size=25>; 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 [
idstringsupl[A-Z\d]{26}read-onlyrequired

Unique identifier for the given user.

Example: "supl01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735"
namestringrequired
Example: "Rivendell Renewables"
iconstring or null(uri)required
Example: "https://cdn.example.com/rivendell_renewables.jpg"
highlightedboolean

A highlighted supplier is one that is often selected by users.

]
Response
application/json
[
  {
    "id": "supl01HN2NJ9NMRZBXT1H6FT9N7735",
    "url": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
    "name": "Rivendell Renewables",
    "icon": "https://cdn.example.com/rivendell_renewables.jpg",
    "highlighted": true
  }
]

Retrieve a supplier

Request

Retrieve details for a single, specific energy supplier.

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

The ID of the specific supplier to retrieve.

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

Responses

Return a single supplier.

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

Unique identifier for the given user.

Example: "supl01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735"
namestringrequired
Example: "Rivendell Renewables"
iconstring or null(uri)required
Example: "https://cdn.example.com/rivendell_renewables.jpg"
highlightedboolean

A highlighted supplier is one that is often selected by users.

Response
application/json
{
  "id": "supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "Rivendell Renewables",
  "icon": "https://cdn.example.com/rivendell_renewables.jpg",
  "highlighted": true
}

List tariffs, sorted alphabetically by name.

Request

List all the energy supplier tariffs known by the ev.energy system.

Use the available_for_user_id query parameter to narrow the list to only those relevant to a specific user and supplier query parameter to list only tariffs for a specific supplier.

Security
oauth2(Required scopes:
tariff:read
)
Query
pagenumber

The page number to return results for.

Example: page=2
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. The prices expansion requires tariff:prices:read scope.

Items Enum"supplier""prices"
supplier_idstring

The ID of the supplier to filter by.

available_for_user_idstringuser[A-Z\d]{26}

Filter to only return resources available in the user's region and program.

Example: available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735
include_optionalstring

Include optional tariffs.

Value"daily_prices"
Example: include_optional=daily_prices
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/tariffs?page=2&page_size=10&expand=supplier&supplier_id=string&available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735&include_optional=daily_prices' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Return a list of Tariffs.

Headers
Linkstring

Provides links to the previous and next pages of data, if they exist.

Example: "<about:blank>; rel=\"previous\", <https://api.ev.energy/v2/examples/?page=2&page_size=25>; 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 [
idstringtari[A-Z\d]{26}read-onlyrequired

Unique identifier for the given user.

Example: "tari01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735"
supplierstring or Supplier (object)required

The energy company that supplies this tariff.

One of:

The energy company that supplies this tariff.

string(uri)
namestringrequired
Example: "Fangorn Biomass"
currencystringrequired
Example: "GBP"
highlightedboolean

A highlighted tariff is one that is often selected by users.

typeany
Enum"FLAT_RATE""DUAL_RATE""THREE_RATE""DYNAMIC""EXTERNALLY_MANAGED""OTHER"
daily_pricesobject(DailyPrices)[ 1 .. 3 ] properties

The times returned here are localised to the timezone the tariff is in. The timezone is returned in timezone_name.

timezone_namestring
Example: "Europe/London"
price_chart_urlstring or null

The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.

Example: "https://www.example.com/"
]
Response
application/json
[
  {
    "id": "tari01HN2NJ9NMRZBXT1H6FT9N7735",
    "url": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
    "supplier": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
    "name": "Fangorn Biomass",
    "currency": "GBP",
    "daily_prices": { … }
  }
]

Retrieve a tariff

Request

Retrieve details for a single, specific tariff.

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

The ID of the specific tariff to retrieve.

Example: tari01HN2NJ9NMRZBXT1H6FT9N7735
Query
expandArray of strings

Specify a url field to expand into a nested resource. The prices expansion requires tariff:prices:read scope.

Items Enum"supplier""prices"
available_for_user_idstringuser[A-Z\d]{26}

Filter to only return resources available in the user's region and program.

Example: available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735
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/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735?expand=supplier&available_for_user_id=user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Return a single Tariff.

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
current_priceinteger or null

The price of the tariff at the current time, given in the smallest unit of the currency of the tariff. For example, 10 means 10 pence.

Example: 10
pricesstring or Array of Price (objects) or nullread-only

Link to prices endpoint by default. When expanded with ?expand=prices, returns the past 24 hours of prices. Requires tariff:prices:read scope.

One of:

Link to prices endpoint by default. When expanded with ?expand=prices, returns the past 24 hours of prices. Requires tariff:prices:read scope.

string(uri)read-only
idstringtari[A-Z\d]{26}read-onlyrequired

Unique identifier for the given user.

Example: "tari01HN2NJ9NMRZBXT1H6FT9N7735"
urlstring(uri)required
Example: "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735"
supplierstring or Supplier (object)required

The energy company that supplies this tariff.

One of:

The energy company that supplies this tariff.

string(uri)
namestringrequired
Example: "Fangorn Biomass"
currencystringrequired
Example: "GBP"
highlightedboolean

A highlighted tariff is one that is often selected by users.

typeany
Enum"FLAT_RATE""DUAL_RATE""THREE_RATE""DYNAMIC""EXTERNALLY_MANAGED""OTHER"
daily_pricesobject(DailyPrices)[ 1 .. 3 ] properties

The times returned here are localised to the timezone the tariff is in. The timezone is returned in timezone_name.

timezone_namestring
Example: "Europe/London"
price_chart_urlstring or null

The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.

Example: "https://www.example.com/"
Response
application/json
{
  "id": "tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "url": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735",
  "supplier": "https://api.ev.energy/v2/suppliers/supl01HN2NJ9NMRZBXT1H6FT9N7735",
  "name": "Fangorn Biomass",
  "currency": "GBP",
  "daily_prices": {
    "peak": { … },
    "mid_peak": { … },
    "off_peak": { … }
  },
  "current_price": 10,
  "prices": "https://api.ev.energy/v2/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735/prices"
}

List prices for a tariff

Request

Returns all prices for the specified tariff. Results are ordered by start time (most recent first).

Use started_at__gte and started_at__lte to filter by time range.

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

The ID of the specific tariff to retrieve.

Example: tari01HN2NJ9NMRZBXT1H6FT9N7735
Query
started_at__gtestring(date-time)

Filter for prices starting at or after this datetime (ISO 8601).

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

Filter for prices starting at or before this datetime (ISO 8601).

Example: started_at__lte=2024-01-15T10:00:00Z
pagenumber

The page number to return results for.

Example: page=2
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/tariffs/tari01HN2NJ9NMRZBXT1H6FT9N7735/prices?started_at__gte=2024-01-15T10%3A00%3A00Z&started_at__lte=2024-01-15T10%3A00%3A00Z&page=2&page_size=10' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a paginated list of prices for the specified tariff.

Headers
Linkstring

Provides links to the previous and next pages of data, if they exist.

Example: "<about:blank>; rel=\"previous\", <https://api.ev.energy/v2/examples/?page=2&page_size=25>; 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 [
started_atstring(date-time)read-onlyrequired

When this price interval began (ISO 8601 datetime).

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

The duration of this price interval in seconds.

Example: 1800
price_minor_unitsintegerread-onlyrequired

The price in minor currency units (e.g., pence for GBP).

Example: 10
]
Response
application/json
[
  {
    "started_at": "2024-01-15T10:00:00Z",
    "interval_seconds": 1800,
    "price_minor_units": 10
  }
]

Users

Endpoints for interacting with users.

Schemas
Operations

Vehicles

Endpoints for interacting with vehicles.

Schemas

Webhooks

Endpoints for configuring and managing webhooks.

Operations