API Endpoints

Table of contents

Account endpoint

The account endpoint is available at https://api.octopus.energy/v1/accounts/<account-number>/. This provides you with MPAN /MPRN and serial numbers for each of your meters, as well as what tariffs you are currently on (and those that you were previously on). You will need to replace with your actual account, can be found on your bill or in your account dashboard. The account number is in the format <account-number>.

The account endpoint is available to all customers, but you will need to authenticate with your API key.

Example request
{
  "number": "<account-number>",
  "properties": [
    {
      "id": 1234567,
      "moved_in_at": "2020-11-30T00:00:00Z",
      "moved_out_at": null,
      "address_line_1": "10 Downing Street",
      "address_line_2": "",
      "address_line_3": "",
      "town": "LONDON",
      "county": "",
      "postcode": "W1 1AA",
      "electricity_meter_points": [
        {
          "mpan": "1000000000000",
          "profile_class": 1,
          "consumption_standard": 2560,
          "meters": [
            {
              "serial_number": "1111111111",
              "registers": [
                {
                  "identifier": "1",
                  "rate": "STANDARD",
                  "is_settlement_register": true
                }
              ]
            },
            {
              "serial_number": "2222222222",
              "registers": [
                {
                  "identifier": "1",
                  "rate": "STANDARD",
                  "is_settlement_register": true
                }
              ]
            }
          ],
          "agreements": [
            {
              "tariff_code": "E-1R-VAR-20-09-22-N",
              "valid_from": "2020-12-17T00:00:00Z",
              "valid_to": "2021-12-17T00:00:00Z"
            },
            {
              "tariff_code": "E-1R-VAR-21-09-29-N",
              "valid_from": "2021-12-17T00:00:00Z",
              "valid_to": "2023-04-01T00:00:00+01:00"
            },
            {
              "tariff_code": "E-1R-VAR-22-11-01-N",
              "valid_from": "2023-04-01T00:00:00+01:00",
              "valid_to": null
            }
          ],
          "is_export": false
        }
      ],
      "gas_meter_points": [
        {
          "mprn": "1234567890",
          "consumption_standard": 3448,
          "meters": [
            {
              "serial_number": "12345678901234"
            },
            {
              "serial_number": "09876543210987"
            }
          ],
          "agreements": [
            {
              "tariff_code": "G-1R-VAR-20-09-22-N",
              "valid_from": "2020-12-17T00:00:00Z",
              "valid_to": "2021-12-17T00:00:00Z"
            },
            {
              "tariff_code": "G-1R-VAR-21-09-29-N",
              "valid_from": "2021-12-17T00:00:00Z",
              "valid_to": "2023-04-01T00:00:00+01:00"
            },
            {
              "tariff_code": "G-1R-VAR-22-11-01-N",
              "valid_from": "2023-04-01T00:00:00+01:00",
              "valid_to": null
            }
          ]
        }
      ]
    }
  ]
}

One thing to be aware of with this response is that if you have mutltiple MPANs, it may not be completely obvious which is which. You may be able to work it out by looking at the tariff codes for each mpan. Another thing to be aware of is that variable tariffs will auto-extend when they reach the end, while fixed tariffs switch to the variable tariff when they reach the end of the term.

Products endpoint

To get a list of all currently active products, use end-point https://api.octopus.energy/v1/products/. This endpoint doesn't require authentication. For each record it will give you, among other things, the product code, display name, full name, and a url to get all the tariffs for that product. Don't forget that if it returns more than 100 records, you will have to look at page=2 for the subsequent entries. There are a few parameters that may be useful for this end-point:

  • brand=OCTOPUS_ENERGY - filters on a certain brand
  • is_variable=false - filters on fixed tariffs
  • is_business=false - filters for non-business products
  • available_at=2019-01-01T00:00Z - shows the products that were available at a past data
  • is_green=true
  • is_prepay=true

If you know the product name, you can get a list of all the tariffs available - mostly split by region, and whether single register electricity, dual register electricity or gas. The end-point for this is https://api.octopus.energy/v1/products/AGILE-FLEX-22-11-25/ (or replace with a different product name). Again, this end-point doesn't require authentication. In all cases these results show the current standing charges, and in some cases it also shows the current unit rates (though you can include the parameter tariffs_active_at=2019-01-01T00:00Z to see it as of that historic date). However, it also shows the urls to get the history of standing charges and unit rates for each tariff, which is especially useful for tariffs that change price frequently like AGILE or GO. An example of the response for the AGILE product is shown below: 

{
  "code": "AGILE-FLEX-22-11-25",
  "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,
  "tariffs_active_at": "2023-11-10T00:21:44.970711Z",
  "single_register_electricity_tariffs": {
    "_A": {
      "direct_debit_monthly": {
        "code": "E-1R-AGILE-FLEX-22-11-25-A",
        "standing_charge_exc_vat": 35.52,
        "standing_charge_inc_vat": 37.296,
        "online_discount_exc_vat": 0,
        "online_discount_inc_vat": 0,
        "dual_fuel_discount_exc_vat": 0,
        "dual_fuel_discount_inc_vat": 0,
        "exit_fees_exc_vat": 0,
        "exit_fees_inc_vat": 0,
        "exit_fees_type": "NONE",
        "links": [
          {
            "href": "https://api.octopus.energy/v1/products/AGILE-FLEX-22-11-25/electricity-tariffs/E-1R-AGILE-FLEX-22-11-25-A/standing-charges/",
            "method": "GET",
            "rel": "standing_charges"
          },
          {
            "href": "https://api.octopus.energy/v1/products/AGILE-FLEX-22-11-25/electricity-tariffs/E-1R-AGILE-FLEX-22-11-25-A/standard-unit-rates/",
            "method": "GET",
            "rel": "standard_unit_rates"
          }
        ],
        "standard_unit_rate_exc_vat": 17.77,
        "standard_unit_rate_inc_vat": 18.6585
      }
    },
    ...
   },
}

Consumption endpoints

The most useful API end-point is the consumption API. At its simplest, this provides half-hourly consumption data for any electricity mpan/meter or gas mprn/meter. As an example, you could request https://api.octopus.energy/v1/electricity-meter-points/< MPAN >/meters/< meter serial number >/consumption/?page_size=100&period_from=2023-03-29T00:00Z&period_to=2023-03-29T01:29Z&order_by=period, with authentication.

  • It is recommended to include a period_from and period_to parameter. These should be passed in ISO 8601 format. If you don't include these, an assumption will be made about what range you want. You should include a Z at the end to indicate UTC time, otherwise the results may be incorrect during daylight savings changes.
  • The page_size parameter is optional, but if you don't include it, you will only get the first 100 records. If you want more than 100 records, you will need to request subsequent pages.
  • The order_by parameter is optional, but if you don't include it, the results will be returned ordered by the latest record first. If you want the earliest record first, you should include order_by=period.

The example above was intentionally chosen to show the clock's jumping forward in March. The half hourly periods requested started at 00:00 UTC to the half hour starting before 01:29 UTC - this returns 3 results, but you can see the output format shifting from UTC format to summer-time format in the following response: 

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "consumption": 0.045,
      "interval_start": "2023-03-26T00:00:00Z",
      "interval_end": "2023-03-26T00:30:00Z"
    },
    {
      "consumption": 0.078,
      "interval_start": "2023-03-26T00:30:00Z",
      "interval_end": "2023-03-26T02:00:00+01:00"
    },
    {
      "consumption": 0.082,
      "interval_start": "2023-03-26T02:00:00+01:00",
      "interval_end": "2023-03-26T02:30:00+01:00"
    }
  ]
}

If you don't want to get back your data at half-hourly granularity, you can include a parameter group_by=day, or week or month or quarter. This aggregates half hours into days based on the local time, not the UTC time, so there will be one fewer hour included on the daylight savings in the spring.

This same approach works for an export mpan - it is reported as "consumption", but it will actually be the amount exported.

For gas, you can use an equivalent request: https://api.octopus.energy/v1/gas-meter-points/< MPRN >/meters/< meter serial number >/consumption/?page_size=100&period_from=2023-03-26T00:00:00Z&period_to=2023-03-26T01:00:00Z&order_by=period. One thing to note with gas is that customers on SMETS1 meters get their consumption data pre-converted to kwh, while customers on SMETS2 meters get their consumption data in cubic meters.

Electricity consumption data is returned to the nearest 0.001kwh. For billing, consumption is rounded to the nearest 0.01kwh before multiplying by the price. The rounding method used is rounding half to even, where numbers ending in 5 are rounded up or down, towards the nearest even hundredth decimal place. As a result, 0.015 would be rounded up to 0.02, while 0.025 is rounded down to 0.02.

Price endpoints

Agile prices

The Agile tariff allows users to get all the half-hourly prices between two times by making a request to https://api.octopus.energy/v1/products/AGILE-FLEX-22-11-25/electricity-tariffs/E-1R-AGILE-FLEX-22-11-25-C/standard-unit-rates/?period_from=2023-03-26T00:00Z&period_to=2023-03-26T01:29Z.

  • It is recommended to include a period_from and period_to parameter. These should be passed in ISO 8601 format. If you don't include these, an assumption will be made about what range you want. You should include a Z at the end to indicate UTC time, otherwise the results may be incorrect during daylight savings changes.
  • Note that if you ask for period_from=2020-01-01T02:30Z&period_to=2020-01-01T03:00Z in both end-points, you will get two records from the consumption and one from price. The price endpoint differs from the consumption endpoint in that it will return records only for the exact period requested, while the consumption endpoint will return all records that overlap with the requested period.
  • The price feeds defaults to providing up to 100 records per 'page', so if you are requesting more than 2 days of half-hourly prices you will need to request subsequent pages. You can get the url for these from the "next" field of the results.
  • Unlike consumption, you can't use the order_by parameter to request the results in ascending order, and you can't use group_by parameter to aggregate the results.

The example above was intentionally chosen to show the clock's jumping forward in March. The half hourly periods requested started at 00:00 UTC to the half hour starting before 01:29 UTC - this returns 3 results despite the clock change. You can see the output format stays in UTC format throughout (unlike the consumption end-point). 

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "value_exc_vat": 23.4,
      "value_inc_vat": 24.57,
      "valid_from": "2023-03-26T01:00:00Z",
      "valid_to": "2023-03-26T01:30:00Z",
      "payment_method": null
    },
    {
      "value_exc_vat": 26,
      "value_inc_vat": 27.3,
      "valid_from": "2023-03-26T00:30:00Z",
      "valid_to": "2023-03-26T01:00:00Z",
      "payment_method": null
    },
    {
      "value_exc_vat": 24.3,
      "value_inc_vat": 25.515,
      "valid_from": "2023-03-26T00:00:00Z",
      "valid_to": "2023-03-26T00:30:00Z",
      "payment_method": null
    }
  ]
}

The results include a value excluding VAT, and one including 5% VAT.

If you ever have the wholesale prices but not the retail prices, you can calculate the VAT exclusive prices by dividing the wholesale prices by 10 (to convert from $/MWh to p/kwh), and then multiplying by the multiplier in the following table. If it is for a time between 4 and 7pm, add the peak adder.

RegionMultiplierPeak Adder
A2.113
B2.014
C2.012
D2.213
E2.112
F2.112
G2.112
H2.112
J2.212
K2.212
L2.311
M2.213
N2.113
P2.412

You can also always convert from region C prices to other regions by subtracting 12 (if during peak), dividing by 2, multiplying by the new region's multiplier, adding the new region's peak adder (if during peak).

Go prices

You can request the prices similarly to how you would do it with Agile, eg https://api.octopus.energy/v1/products/GO-VAR-22-10-14/electricity-tariffs/E-1R-GO-VAR-22-10-14-A/standard-unit-rates/?period_from=2023-03-26T00:00Z&period_to=2023-03-26T01:29Z. Unlike Agile, there isn't a record for every half hour, but the response will still give you all the prices you need. In this example, since we have requested prices covering 00:00 until 1:29, it tells us the higher price from the previous morning until 00:30, and then the low price from 00:30 UTC until 3:30 UTC (that is, 4:30 local time). 

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "value_exc_vat": 11.4286,
      "value_inc_vat": 12.00003,
      "valid_from": "2023-03-26T00:30:00Z",
      "valid_to": "2023-03-26T03:30:00Z",
      "payment_method": null
    },
    {
      "value_exc_vat": 42.2354,
      "value_inc_vat": 44.34717,
      "valid_from": "2023-03-25T04:30:00Z",
      "valid_to": "2023-03-26T00:30:00Z",
      "payment_method": null
    }
  ]
}
Fixed price contracts / standard variable price contracts / standing charges

There are a number of fixed price tariffs or standard variable tariffs. For example:

If you request these without a period_start/period_to, the response will show how the price has changed. Alternatively, you can request it for a particular date range and the format will be consistent with GO, for example: https://api.octopus.energy/v1/products/VAR-22-11-01/gas-tariffs/G-1R-VAR-22-11-01-A/standard-unit-rates/?period_from=2023-03-26T00:00Z&period_to=2023-03-26T01:29Z results in: 

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "value_exc_vat": 9.8188,
      "value_inc_vat": 10.30974,
      "valid_from": "2023-01-01T00:00:00Z",
      "valid_to": "2023-03-31T23:00:00Z",
      "payment_method": "DIRECT_DEBIT"
    },
    {
      "value_exc_vat": 9.9775,
      "value_inc_vat": 10.476375,
      "valid_from": "2023-01-01T00:00:00Z",
      "valid_to": "2023-03-31T23:00:00Z",
      "payment_method": "NON_DIRECT_DEBIT"
    }
  ]
}

Note if the valid_to value is null then that indicates that that price is still the active price.

Unlike GO, which shows interchanging peak and off-peak prices, the economy7 tariffs (the ones starting with E-2R) have separate URLs for the day unit rates and the night unit rates.