find_cheapest_window

The cheapest (or lowest-carbon) run of `duration_hours` starting from the next half hour and finishing by the next `finish_by` – when to set a washing machine or dishwasher's delay timer.

read-only

Argument	Type	Description
kwh	number	Energy the run uses, kWh (0-20), for its cost – on the energy label, or kW times hours. Leave out for no cost.
export	string	How export is paid: `paired` (the tariff's own export tariff, default), `fixed` (with export_rate), `fit` (the Feed-in Tariff's deemed export: paid whatever is exported, so the sun used at home gives nothing up), `none`, or an export tariff's key from list_tariffs?direction=export (used where the tariff can have it, else its own).
region*	string	Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each.
tariff	string	A tariff's key from list_tariffs (default `agile`), eg `go`, `edf-go-electric`, `eon-next-drive`.
optimise	string	`cost` (default) or `carbon` (NESO's regional forecast, about two days ahead).
finish_by	string	Local time it must finish by, HH:MM (default 07:00) – the next one at least `duration_hours` away.
solar_kwp	number	The home's solar panels, kWp (0.2-50): the answer then counts their forecast spare sun – see the docs' Solar panels section.
export_rate	number	A fixed export rate, p/kWh (0-100).
solar_pitch	number	Their angle from flat, degrees (0-90, default 35).
solar_facing	string	The way they face: S, SE, SW, E, W, NE, NW or N – or a bearing in degrees (south is 180). Default S.
duration_hours	number	How long it runs, 0.5-12 in half hours (default 3.5).
solar_inverter_kw	number	The inverter's limit, kW (0.5-50), if smaller than the panels.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "region"
  ],
  "properties": {
    "kwh": {
      "type": "number",
      "maximum": 20,
      "minimum": 0,
      "description": "Energy the run uses, kWh (0-20), for its cost – on the energy label, or kW times hours. Leave out for no cost."
    },
    "export": {
      "enum": [
        "paired",
        "fixed",
        "fit",
        "none",
        "agile-outgoing",
        "outgoing",
        "prime-outgoing",
        "flux-export",
        "octopus-seg",
        "eon-next-flex-export",
        "eon-next-export-exclusive",
        "eon-next-export-premium",
        "edf-seg-variable",
        "edf-seg-variable-value",
        "edf-export-exclusive"
      ],
      "type": "string",
      "description": "How export is paid: `paired` (the tariff's own export tariff, default), `fixed` (with export_rate), `fit` (the Feed-in Tariff's deemed export: paid whatever is exported, so the sun used at home gives nothing up), `none`, or an export tariff's key from list_tariffs?direction=export (used where the tariff can have it, else its own)."
    },
    "region": {
      "type": "string",
      "description": "Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each."
    },
    "tariff": {
      "type": "string",
      "default": "agile",
      "description": "A tariff's key from list_tariffs (default `agile`), eg `go`, `edf-go-electric`, `eon-next-drive`."
    },
    "optimise": {
      "enum": [
        "cost",
        "carbon"
      ],
      "type": "string",
      "default": "cost",
      "description": "`cost` (default) or `carbon` (NESO's regional forecast, about two days ahead)."
    },
    "finish_by": {
      "type": "string",
      "default": "07:00",
      "description": "Local time it must finish by, HH:MM (default 07:00) – the next one at least `duration_hours` away."
    },
    "solar_kwp": {
      "type": "number",
      "maximum": 50,
      "minimum": 0.2,
      "description": "The home's solar panels, kWp (0.2-50): the answer then counts their forecast spare sun – see the docs' Solar panels section."
    },
    "export_rate": {
      "type": "number",
      "maximum": 100,
      "minimum": 0,
      "description": "A fixed export rate, p/kWh (0-100)."
    },
    "solar_pitch": {
      "type": "number",
      "maximum": 90,
      "minimum": 0,
      "description": "Their angle from flat, degrees (0-90, default 35)."
    },
    "solar_facing": {
      "type": "string",
      "description": "The way they face: S, SE, SW, E, W, NE, NW or N – or a bearing in degrees (south is 180). Default S."
    },
    "duration_hours": {
      "type": "number",
      "default": 3.5,
      "maximum": 12,
      "minimum": 0.5,
      "multipleOf": 0.5,
      "description": "How long it runs, 0.5-12 in half hours (default 3.5)."
    },
    "solar_inverter_kw": {
      "type": "number",
      "maximum": 50,
      "minimum": 0.5,
      "description": "The inverter's limit, kW (0.5-50), if smaller than the panels."
    }
  },
  "additionalProperties": false
}

get_flexibility_events

When the grid operator, NESO, is asking homes in a region to use less electricity (often the evening peak) or more (often in Scotland, when there's more wind than the grid can carry south), through its Demand Flexibility Service: live events from now to the end of tomorrow, usually announced the same morning. Households can sometimes get paid for taking part – but only if they've signed up to a scheme with their energy supplier or another provider (eg Octopus's Saving Sessions), and that provider is taking part in the event; it tells them and says what it pays. These are NESO's requests to such providers. Without a scheme, shifting use still helps the grid but isn't paid.

read-only

Argument	Type	Description
region*	string	Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "region"
  ],
  "properties": {
    "region": {
      "type": "string",
      "description": "Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each."
    }
  },
  "additionalProperties": false
}

get_heat_pump_times

For a typical weekday and weekend day at this time of year (on a fixed-window or flat tariff, today's rates): the cheapest time to reheat hot water (and the cheapest ready by 07:00), and the cost of each kWh of heat by hour – price divided by a generic air-source heat pump's efficiency at that hour's typical temperature.

read-only

Argument	Type	Description
export	string	How export is paid: `paired` (the tariff's own export tariff, default), `fixed` (with export_rate), `fit` (the Feed-in Tariff's deemed export: paid whatever is exported, so the sun used at home gives nothing up), `none`, or an export tariff's key from list_tariffs?direction=export (used where the tariff can have it, else its own).
region*	string	Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each.
tariff	string	A tariff's key from list_tariffs (default `agile`), eg `go`, `edf-go-electric`, `eon-next-drive`.
solar_kwp	number	The home's solar panels, kWp (0.2-50): the answer then counts their forecast spare sun – see the docs' Solar panels section.
export_rate	number	A fixed export rate, p/kWh (0-100).
solar_pitch	number	Their angle from flat, degrees (0-90, default 35).

get_home_battery_times

For a typical weekday and weekend day at this time of year (on a fixed-window or flat tariff, today's rates): the cheapest charge slot to fill a home battery before the 16:00 peak, an optional afternoon top-up, and what it saves a home using `usage` kWh a year – the battery runs the house after its charge until it's empty, through a typical day's use. No export, and not counting the battery's wear; with `solar_kwp`, also how full to charge overnight for the next day's sun.

read-only

Argument	Type	Description
rate	number	Grid charge rate, kW (0.5-15, default 3).
usage	number	The home's electricity use, kWh a year (500-30000, default 2500 – an average home).
export	string	How export is paid: `paired` (the tariff's own export tariff, default), `fixed` (with export_rate), `fit` (the Feed-in Tariff's deemed export: paid whatever is exported, so the sun used at home gives nothing up), `none`, or an export tariff's key from list_tariffs?direction=export (used where the tariff can have it, else its own).
region*	string	Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each.
tariff	string	A tariff's key from list_tariffs (default `agile`), eg `go`, `edf-go-electric`, `eon-next-drive`.
battery

get_prices

Half-hourly prices for a region from midnight today. On Agile (the default) and Agile Outgoing, each is published by Octopus or estimated by Renewably (flagged `estimate`); other tariffs show only their supplier's published prices. An export tariff's are what it pays for export (and take no panels).

read-only

Argument	Type	Description
days	integer	Days from today, 1-5 (default 2: today and tomorrow).
export	string	How export is paid: `paired` (the tariff's own export tariff, default), `fixed` (with export_rate), `fit` (the Feed-in Tariff's deemed export: paid whatever is exported, so the sun used at home gives nothing up), `none`, or an export tariff's key from list_tariffs?direction=export (used where the tariff can have it, else its own).
region*	string	Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each.
tariff	string	A tariff's key from list_tariffs (default `agile`) – an import tariff, or an export tariff from list_tariffs?direction=export (eg `agile-outgoing`), for what it pays.
solar_kwp	number	The home's solar panels, kWp (0.2-50): the answer then counts their forecast spare sun – see the docs' Solar panels section.
export_rate	number	A fixed export rate, p/kWh (0-100).

list_regions

The 14 Agile regions (GSP groups), each with well-known places in it - to place a home by its town. The regions are the local electricity networks' areas, not counties, so some places surprise (Milton Keynes and Coventry are in the East Midlands, Croydon in South East England, York in North East England). The surest way: the first two digits of the 13-digit MPAN on the home's electricity bill (`mpan_prefix`).

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {},
  "additionalProperties": false
}

list_tariffs

The time-of-use and standard tariffs from Octopus, EDF and E.ON Next that the `tariff` parameter accepts – or, with `direction=export`, their export tariffs (for get_prices and `export`), each saying which homes can have it.

read-only

Argument	Type	Description
direction	string	`import` (default) or `export`.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "direction": {
      "enum": [
        "import",
        "export"
      ],
      "type": "string",
      "default": "import",
      "description": "`import` (default) or `export`."
    }
  },
  "additionalProperties": false
}

plan_ev_charging

The cheapest or greenest half hours to charge an electric car by a ready-by time up to four days ahead.

read-only

Argument	Type	Description
day	string	Ready-by day: today, tomorrow, in2 or in3 (default: the next time `time` comes round, at least four hours away).
mpk	number	Miles per kWh, for the per-mile figures (1.5-6, default 3.3).
now	integer	Charge now, % (0-100, default 30).
mode	string	`timer` (one unbroken block, default) or `smart` (any half hours).
time	string	Ready-by local time, HH:MM (default 07:00).
export	string	How export is paid: `paired` (the tariff's own export tariff, default), `fixed` (with export_rate), `fit` (the Feed-in Tariff's deemed export: paid whatever is exported, so the sun used at home gives nothing up), `none`, or an export tariff's key from list_tariffs?direction=export (used where the tariff can have it, else its own).
region*	string	Agile region: a letter A-P or the slug from list_regions (eg `C` or `london`); list_regions lists well-known places in each.

plan_home

A home's past year on every tariff in list_tariffs and at Ofgem's price cap – and what switching tariff, an electric car, a heat pump, solar panels or a battery would save, each added to everything before it (tariff, car, heating, solar, battery). Each of car, heating, solar and battery is something the home has (it explains the bill) or is considering. Totals are electricity, gas at the price cap and petrol or diesel – only what changes.

read-only

Argument	Type	Description
car	string	What the home drives now: `petrol` (default) or `diesel` (counted only with consider_ev=1), `ev` (the bill includes an electric car), or `none`.
gas	number	With heating=gas and consider_heat_pump=1: gas a year on the bill, kWh (1000-60000, default 9500).
kwp	number	Panels, kWp (0.2-50; default 4 on a roof, 0.8 for a plug-in kit, at most 2) – the first roof face's, with more faces.
mpg	number	With consider_ev=1: its real-world mpg (10-120; default the average car on the road, 36 petrol, 42 diesel).
mpk	number	Electric car, miles per kWh at the battery (1.5-6, default 3.3).
ppl	number	With consider_ev=1: what you pay, p/litre (50-400; default the UK weekly average over the past year).
kwp2

plan_home_battery

A home battery's plan from the half hour under way to the end of tomorrow, on the tariff's real prices (Agile's, and Agile Outgoing's, estimated beyond what Octopus has published), half hour by half hour: charge from the grid, hold, run the house (self-use), export, or send the sun to the grid – the cheapest way through, counting the battery's losses and wear. Exporting follows what the export tariff pays for – everything on Octopus's, only what the panels put in on the others – unless `battery_export=all` says the home is paid for what the battery charged from the grid too. A battery without panels gives `export` (Octopus's `outgoing`, `agile-outgoing` or `prime-outgoing`, `eon-next-export-premium` for a battery E.ON fitted, or `fixed` with `export_rate`) and trades on the grid: charging cheap, exporting at the peak. Smart Export Guarantee tariffs pay only for what panels made, so not a battery on its own. `now` is what to set this half hour; `settings` the few changes worth typing into the inverter's app. For a typical home of `usage`; give `soc` (the battery's charge now) for a plan from where it is. Advice and data for the owner's own automation – Renewably never controls a battery.

read-only

Argument	Type	Description
soc	number	The battery's charge now, per cent (0-100). Default: at its reserve.
rate	number	Charge and discharge rate, kW (0.5-15, default 3).
wear	number	The battery's wear for each kWh it gives back, pence (0-20, default 2).
usage	number	The home's electricity use, kWh a year (500-30000, default 2500).

Renewably

Try it

find_cheapest_window Read-only

Renewably

Try it

find_cheapest_window Read-only

Install

Tools (10)

Security checkA100/100