`octo_api.api`

The primary interface to the Octopus Energy API.

Note

The Octopus Energy API uses the term “Grid Supply Point” (GSP) to refer to what are actually the 14 former Public Electricity Suppliers. The GSP terminology has been used here to better reflect the REST API.

Classes:

OctoAPI(api_key)

The primary interface to the Octopus Energy API.

class OctoAPI(api_key)[source]

Bases: object

The primary interface to the Octopus Energy API.

Parameters: api_key (str) – API key to access the Octopus Energy API.

If you are an Octopus Energy customer, you can generate an API key from your online dashboard.

Attributes:

`API_BASE`	The base URL of the Octopus Energy API.
`API_KEY`	The API key to access the Octopus Energy API.

Methods:

`get_consumption`(mpan, serial_number, fuel[, …])	Return a list of consumption values for half-hour periods for a given meter-point and meter.
`get_grid_supply_point`(postcode)	Returns the grid supply point for the given postcode.
`get_meter_point_details`(mpan)	Retrieve the details of a meter-point.
`get_product_info`(product_code[, …])	Retrieve the details of a product (including all its tariffs) for a particular point in time.
`get_products`([is_variable, is_green, …])	Returns a list of energy products.
`get_tariff_charges`(product_code, …[, …])	Returns a list of time periods and their associated unit rates charges.

API_BASE

Type: SlumberURL

The base URL of the Octopus Energy API.

API_KEY

Type: Secret

The API key to access the Octopus Energy API.

get_consumption(mpan, serial_number, fuel, period_from=None, period_to=None, page_size=100, reverse=False, group_by=None)[source]

Return a list of consumption values for half-hour periods for a given meter-point and meter.

Unit of measurement:

Electricity meters: kWh
SMETS1 Secure gas meters: kWh
SMETS2 gas meters: m³

Attention

Half-hourly consumption data is only available for smart meters. Requests for consumption data for non-smart meters will return an empty response payload.

Parameters

mpan (str) – The electricity meter-point’s MPAN or gas meter-point’s MPRN.
serial_number (str) – The meter’s serial number.
fuel (Literal['electricity', 'gas'])
period_from (Optional[datetime]) – Show consumption for periods which start at or after the given datetime. This parameter can be provided on its own. Default None.
period_to (Optional[datetime]) – Show consumption for periods which start at or before the given datetime. This parameter also requires providing the period_from parameter to create a range. Default None.
page_size (int) – Page size of returned results. Default is 100, maximum is 25,000 to give a full year of half-hourly consumption details.
reverse (bool) – Returns the results ordered from most oldest to newest. By default the results are from most recent backwards.
group_by (Optional[str]) –
The grouping of the consumption data. By default the consumption is returned in half-hour periods.

Possible alternatives are:
- 'hour'
- 'day'
- 'week'
- 'month'
- 'quarter'

Return type

PaginatedResponse[Consumption]

get_grid_supply_point(postcode)[source]

Returns the grid supply point for the given postcode.

Parameters: postcode (str)
Raises: ValueError if the postcode cannot be mapped to a GSP.
Return type: Region

get_meter_point_details(mpan)[source]

Retrieve the details of a meter-point.

This can be used to get the GSP of a given meter-point.

Parameters: mpan (str) – The electricity meter-point’s MPAN.
Return type: MeterPointDetails
Returns

get_product_info(product_code, tariffs_active_at=None)[source]

Retrieve the details of a product (including all its tariffs) for a particular point in time.

Parameters

product_code (str) – The code of the product to be retrieved, for example VAR-17-01-11.
tariffs_active_at (Optional[datetime]) – The point in time in which to show the active charges. Defaults to current datetime. Default None.

Example

>>> api.get_product_info(product_code='VAR-17-01-11')
octo_api.products.DetailedProduct(
    available_from='2017-01-11T10:00:00+00:00',
    available_to='2018-02-15T00:00:00+00:00',
    brand='S_ENERGY',
    code='7-01-11',
    description='This variable tariff always offers great value - driven by our'
                'belief that prices should be fair for the long term, not just a'
                'fixed term. We aim for 50% renewable electricity on this tariff.',
    display_name='pus',
    full_name='ctopus January 2017 v1',
    is_business=False,
    is_green=False,
    is_prepay=False,
    is_restricted=False,
    is_tracker=False,
    is_variable=True,
    links=[
        {
            'href': 'https://api.octopus.energy/v1/products/VAR-17-01-11/',
            'method': 'GET',
            'rel': 'self'
        }
    ],
    term=None,
    tariffs_active_at='2020-10-26T11:15:17.208285+00:00',
    single_register_electricity_tariffs=RegionalTariffs(['direct_debit_monthly']),
    dual_register_electricity_tariffs=RegionalTariffs(['direct_debit_monthly']),
    single_register_gas_tariffs=RegionalTariffs(['direct_debit_monthly']),
    sample_quotes=RegionalQuotes([dual_fuel_dual_rate, dual_fuel_single_rate, electricity_dual_rate, electricity_single_rate]),
    sample_consumption={
        'electricity_single_rate': {'electricity_standard': 2900},
        'electricity_dual_rate': {
            'electricity_day': 2436,
            'electricity_night': 1764
        },
        'dual_fuel_single_rate': {
            'electricity_standard': 2900,
            'gas_standard': 12000
        },
        'dual_fuel_dual_rate': {
            'electricity_day': 2436,
            'electricity_night': 1764,
            'gas_standard': 12000
        }
    },
)

Return type: DetailedProduct

get_products(is_variable=None, is_green=None, is_tracker=None, is_prepay=None, is_business=False, available_at=None)[source]

Returns a list of energy products.

By default, the results only include public energy products. Authenticated organisations will also see products available to their organisation.

Parameters

is_variable (Optional[bool]) – Show only variable products. Default None.
is_green (Optional[bool]) – Show only green products. Default None.
is_tracker (Optional[bool]) – Show only tracker products. Default None.
is_prepay (Optional[bool]) – Show only pre-pay products. Default None.
is_business (bool) – Show only business products. Default False.
available_at (Optional[datetime]) – Show products available for new agreements on the given datetime. Defaults to the current datetime, effectively showing products that are currently available.

Example

>>> api.get_products()[0]
octo_api.products.Product(
    available_from='2016-01-01T:00:00:00+00:00',
    available_to=None,
    brand='AFFECT_ENERGY',
    code='1201',
    description='Affect Standard Tariff',
    display_name='Affect Standard Tariff',
    full_name='Affect Standard Tariff',
    is_business=False,
    is_green=False,
    is_prepay=False,
    is_restricted=False,
    is_tracker=False,
    is_variable=True,
    links=[
        {
            'href': 'https://api.octopus.energy/v1/products/1201/',
            'method': 'GET',
            'rel': 'self'
        }
    ],
    term=None,
    direction='IMPORT',
)

Return type: PaginatedResponse[Product]

get_tariff_charges(product_code, tariff_code, fuel, rate_type, period_from=None, period_to=None, page_size=100)[source]

Returns a list of time periods and their associated unit rates charges.

If the tariff has a fixed unit rate the list will only contain one element.

Parameters

product_code (str) – The code of the product to be retrieved, for example VAR-17-01-11.
tariff_code (str) –
The code of the tariff to be retrieved, for example E-1R-VAR-17-01-11-A. From what I can tell the format is:
```
<E for electricity><optional hyphen><1R for single rate?><the product code>-<the grid supply point>
```
fuel (Literal['electricity', 'gas'])
rate_type (RateType)
period_from (Optional[datetime]) – Show charges active from the given datetime (inclusive). This parameter can be provided on its own. Default None.
period_to (Optional[datetime]) – Show charges active up to the given datetime (exclusive). You must also provide the period_from parameter in order to create a range. Default None.
page_size (int) – Page size of returned results. Default is 100, maximum is 1,500 to give up to a month of half-hourly prices.

Note

If you’re using this API to query future unit-rates of the Agile Octopus product, note that day-ahead prices are normally created by 4pm in the Europe/London timezone. Further, the market index used to calculate unit rates is based in the CET timezone (UTC+1) and so its “day” corresponds to 11pm to 11pm in UK time. Hence, if you query today’s unit rates before 4pm, you’ll get 46 results back rather than 48.

Return type: PaginatedResponse[RateInfo]

octo_api.api

`octo_api.api`