# Renewably API

> Cheapest and greenest times to use electricity in Great Britain, as JSON: half-hourly prices on Octopus Agile (with estimates up to four days ahead) and other time-of-use tariffs from Octopus, EDF and E.ON Next; when to run an appliance; EV charging plans; heat pump and home battery times; and which tariff suits a household, from its past year. Free, no key, read-only (GET).

Times are ISO 8601 in UK local time; prices are pence per kWh including VAT; units are in field names (`_p_per_kwh`, `_kwh`, `_pounds`). Regions are a letter A-P or a slug from /regions; tariffs a key from /tariffs (default Agile). Errors are JSON with a code, a message saying what to change, and a docs link. Credit the CC BY sources listed in each response's `meta.sources` when showing the data. Free for personal and non-commercial use (terms in the docs); contact: [hello@renewably.uk](mailto:hello@renewably.uk).

## Use it

- [OpenAPI spec](https://renewably.uk/api/v1/openapi.json): every parameter and field, with a worked example per endpoint
- [Docs](https://renewably.uk/api/v1/docs): conventions, caching, rate limits, errors and each endpoint in detail
- [MCP server](https://renewably.uk/mcp): Streamable HTTP, no key - a tool per endpoint, for AI assistants

## Endpoints

- [Index](https://renewably.uk/api/v1/): Links to every endpoint.
- [Regions](https://renewably.uk/api/v1/regions): The 14 Agile regions (GSP groups).
- [Tariffs](https://renewably.uk/api/v1/tariffs): The time-of-use and standard tariffs from Octopus, EDF and E.ON Next that the `tariff` parameter accepts.
- [Prices](https://renewably.uk/api/v1/prices): Half-hourly import prices for a region from midnight today.
- [Cheapest window](https://renewably.uk/api/v1/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.
- [EV charging plan](https://renewably.uk/api/v1/ev-plan): The cheapest or greenest half hours to charge an electric car by a ready-by time up to three days ahead - the same as the /ev-charging/ planner, with the same parameters.
- [Heat pump times](https://renewably.uk/api/v1/heat-pump): 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.
- [Home battery charge times](https://renewably.uk/api/v1/home-battery): 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.
- [Tariff comparison](https://renewably.uk/api/v1/tariff-comparison): What a household would have paid over the past year on each tariff in /tariffs, and at Ofgem's price cap (the baseline) - from its yearly electricity as on its bill, how much of its everyday use can move, an electric car, a heat pump, solar panels and a home battery - at each tariff's actual prices for the region, as on the /tariff-comparison/ page.
- [Spoken answer](https://renewably.uk/api/v1/say): One sentence for a voice assistant to read aloud - an iPhone Shortcut ("Hey Siri, Renewably price"), an Alexa skill, anything that speaks text.

## Optional

- [Full docs as one file](https://renewably.uk/llms-full.txt)