The REST API is a simple way for customers and partner organisations to access the Octopus Energy platform.

A request at its most basic level is a URL made up of 3 parts: a base URL, an end-point, and parameters. For request where you are updating or creating data, you will also need to include a request body. To read more about what request bodies each end-point accepts, please see the REST API reference documentation.

All API requests should use a base URL of: https://api.octopus.energy/v1/. Note, all API requests must be made over HTTPS.

The end-point relates to the kind of data you are requesting. For example, if you want to retrieve a list of products, you would use the end-point https://api.octopus.energy/v1/products. To see all end-points available to you, please see the REST API reference documentation.

The parameters are optional and are used to filter the data. For example, if you wanted to retrieve a list of products that are for a specific brand and that are green, you would use the following parameters: https://api.octopus.energy/v1/products?brand=OCTOPUS_ENERGY&is_green=true. The first parameter is always preceded by a question mark, while subsequent parameters are preceded by ampersands, as in the example above.

Some API end-points accept datetime strings as parameters. These should be passed in ISO 8601 format. Eg:

We strongly recommend that timezone information is included on all datetime parameters. If no timezone information is included, the “Europe/London” timezone will be assumed and results may vary between GMT and British Summer Time.

The response comes back as json, which is a flexible format that can be directly read, or easily unpacked by a downstream application. For example, here is a truncated response from https://api.octopus.energy/v1/products/:

{
  "count": 40,
  "next": null,
  "previous": null,
  "results": [
    {
      "code": "AGILE-FLEX-22-11-25",
      "direction": "IMPORT",
      "full_name": "Agile Octopus November 2022 v1",
      "display_name": "Agile Octopus",
      "description": "With Agile Octopus, you get access to half-hourly energy prices, tied to wholesale prices and updated daily.  The unit rate is capped at 100p/kWh (including VAT).",
      "is_variable": true,
      "is_green": true,
      "is_tracker": false,
      "is_prepay": false,
      "is_business": false,
      "is_restricted": false,
      "term": null,
      "available_from": "2022-11-25T00:00:00Z",
      "available_to": null,
      "links": [
        {
          "href": "https://api.octopus.energy/v1/products/AGILE-FLEX-22-11-25/",
          "method": "GET",
          "rel": "self"
        }
      ],
      "brand": "OCTOPUS_ENERGY"
    },
    ...
    ]
}
                                

At the top of the response it will tell you the number of records returned in the response (in this case 103). If the number of records exceeds the page_size (usually 100), you will have to explicitly ask for the next page - if so this will be given in the "next" field of the response.

In many cases, like the example above, you can access the API without the need to authenticate. However, some end-points such as accessing account specific deta will require authentication. This is performed via HTTP Basic Auth. To perform a request requiring authentication, you must provide your API key as the username value. You do not need to provide a password. You can retrieve your API key by loggin in to your account. For example using cURL you can perform an authenticated request like so:

Note the colon after $API_KEY which prevents cURL from asking for a password.

There are lots of different ways to request data from the REST API and process it.

The simplest way to access the data is in your web browser. If it is an end-point that requires authentication, your browser should prompt you for your username and password, in which case just enter your API key in the username field and leave the password blank.

cURL is a free command line tool that comes with a lot of systems, and allows you to make API requests and process responses.

For example, in the command line interface, you can run the following command to get a json response:

If it is a request that requires authentication, you can do this replacing $API_KEY with your API key for example:

cURL has a lot of other functionality, for example to parse the response and do calculations and save it into csv format.

Python is a popular programming language for data analysis and manipulation. It is free and open source, and has a lot of libraries that make it easy to make API requests and process the responses.

For example, you can use the requests library to make a request and get a json response:

import requests
url = "https://api.octopus.energy/v1/products?brand=OCTOPUS_ENERGY&is_prepay=true"
response = requests.get(url=url)
r = requests.get(url)
output_dict = r.json()
                            

If it is a request that requires authentication, you can do this replacing $API_KEY with your API key for example:

import requests
url = "https://api.octopus.energy/v1/accounts/<account-number>/'"
api_key = "$API_KEY"
response = requests.get(url=url, auth=(api_key, ''))
r = requests.get(url)
output_dict = r.json()
                            

Python has a lot of other functionality, for example to request, parse and display a table of prices from the Agile tariff you can do the following:

import requests
import pandas as pd
url = "https://api.octopus.energy/v1/products/AGILE-18-02-21/electricity-tariffs/E-1R-AGILE-18-02-21-C/standard-unit-rates/?period_from=2020-03-29T00:00Z&period_to=2020-03-29T02:29Z"
r = requests.get(url)
output_dict = r.json()
print('output_dict=')
print(output_dict)

valid_from = [x['valid_from'] for x in output_dict['results']]
value_exc_vat = [x['value_exc_vat'] for x in output_dict['results']]
prices = pd.Series(value_exc_vat, index=valid_from)
print('prices=')
print(prices)
                            

Which will give you the following output:

output_dict=
{'count': 5, 'next': None, 'previous': None, 'results': [{'value_exc_vat': -1.04, 'value_inc_vat': -1.092, 'valid_from': '2020-03-29T02:00:00Z', 'valid_to': '2020-03-29T02:30:00Z', 'payment_method': None}, {'value_exc_vat': 0.2, 'value_inc_vat': 0.21, 'valid_from': '2020-03-29T01:30:00Z', 'valid_to': '2020-03-29T02:00:00Z', 'payment_method': None}, {'value_exc_vat': 0.6, 'value_inc_vat': 0.63, 'valid_from': '2020-03-29T01:00:00Z', 'valid_to': '2020-03-29T01:30:00Z', 'payment_method': None}, {'value_exc_vat': 3.6, 'value_inc_vat': 3.78, 'valid_from': '2020-03-29T00:30:00Z', 'valid_to': '2020-03-29T01:00:00Z', 'payment_method': None}, {'value_exc_vat': 1.5, 'value_inc_vat': 1.575, 'valid_from': '2020-03-29T00:00:00Z', 'valid_to': '2020-03-29T00:30:00Z', 'payment_method': None}]}
prices=
2020-03-29T02:00:00Z   -1.04
2020-03-29T01:30:00Z    0.20
2020-03-29T01:00:00Z    0.60
2020-03-29T00:30:00Z    3.60
2020-03-29T00:00:00Z    1.50
dtype: float64