Two small APIs around the Dutch day-ahead power price. Energy Prices answers what power costs, per quarter or per hour, and how cheap or dear that moment is compared to the rest of its day. Cheapest answers when to use it: give it how long a device runs and when it has to be done, and it returns the cheapest moments. Home Assistant asks, and decides itself what to switch. I use them day to day for planning appliances, charging and fair billing.
Architecture & platform
Energy Prices
Two APIs that tell Home Assistant when to use power
Executive summary
- Energy Prices. The Dutch day-ahead power price per quarter or per hour, for today and tomorrow, with a position for every slot: how cheap or dear it is within its own day, from 0 to 100%. Kept in a store of its own, so the history grows and can be backfilled.
- Cheapest. A question instead of a list: "I need power for 2¼ hours, done by 7:00. When?" Split for a load that may pause, contiguous for one that may not.
- Home Assistant. A price chart, cheap and expensive windows, a planner for appliances, charging in the cheapest hours, billing every kWh at the price of that moment, and what-if models for a battery or solar panels.
- How it grew. Templates in one Home Assistant first, copied to the next installations, and only then the generic part abstracted into an API, tested once and asked the same way everywhere.
What it is, in short
With a dynamic energy contract, the price of power changes every hour, and since October 2025 the day-ahead market even sets it per quarter. Around 13:00 each day the prices for tomorrow are published. That is useful information, but a long list of prices is not yet an answer. What you want to know is simpler: is now a good moment, and if not, when is?
So there are two APIs. Energy Prices serves the prices themselves, ready for a chart or a sensor. Cheapest takes the question one step further and returns a plan. Cheapest reuses Energy Prices: both read the same stored prices, and a token decides which of the two a client may ask.
Those stored prices are a store of my own, not a pass-through to the market. A few times a day, most of them in the afternoon when tomorrow is published, the prices are fetched and kept per quarter. They stay. The history grows by itself, and days that are missing hours can be fetched again afterwards, so a gap is repaired instead of remembered. That history is what makes a month or a year of prices one call away.
Energy Prices: what does power cost?
One call returns a local day, or a range of days, per hour or per quarter. Every slot
carries its price in EUR/kWh and its position_percentage: 0 is the
cheapest slot of that day, 100 the dearest. The slot that is running now is repeated
under current, so a home automation can poll one URL and read one field.
The position is computed within the slot's own day on purpose. An automation that acts on "the cheapest hours of today" should not see today's labels shift when tomorrow's prices arrive in the afternoon.
Because every price is kept, the same endpoint also looks back. A range of up to three days comes per hour or per quarter; a longer one, up to a year per day or up to five years per month, comes per bucket with the cheapest, dearest and average price of each, and how many hours of it are known. That is enough to compare this winter with the last one, or to feed a model that needs a year of prices.
| Parameter | Meaning |
|---|---|
date | One local day (Europe/Amsterdam), defaults to today |
from, to | A range of local days, inclusive, instead of date |
resolution | 60 (hour, default) or 15 (quarter), or day or month for a longer range |
GET /api/v0/energy/prices?from=2026-11-14&to=2026-11-15&resolution=60
{
"bidding_zone": "NL",
"timezone": "Europe/Amsterdam",
"resolution": "60",
"unit": "EUR/kWh",
"basis": "Day-ahead market price, excluding VAT, energy tax and supplier surcharge.",
"summary_by_day": {
"2026-11-14": { "min": 0.0857, "max": 0.1931, "average": 0.1312 }
},
"current": {
"starts_at": "2026-11-14T11:00:00+01:00",
"price": 0.1068,
"position_percentage": 20
},
"prices": [
{
"date": "2026-11-14",
"starts_at": "2026-11-14T00:00:00+01:00",
"ends_at": "2026-11-14T01:00:00+01:00",
"price": 0.1105,
"position_percentage": 23
}
// … one entry per hour
]
} The price is the bare market price, without VAT, energy tax or a supplier's margin. That keeps the API neutral: it does not need to know anyone's contract. Turning it into what you actually pay happens in Home Assistant, further down.
Cheapest: when should I use it?
Cheapest answers one question: I need power for hours hours, between
from and until. When is it cheapest? Fractions are fine, so
a dishwasher that runs 2 hours and 15 minutes asks for 2.25. There are two ways to
answer, and the device decides which one fits.
- Split picks the cheapest slots wherever they fall. Good for a
load that may stop and start, such as a battery charger or a boiler. A
min_blockkeeps the runs from getting too short. - Contiguous picks the one unbroken stretch with the lowest average. Good for a load that may not be interrupted, such as a dishwasher or a washing machine.
| Parameter | Meaning |
|---|---|
hours | Required. How long to use power, 0.25 to 48, fractions allowed |
mode | split (default) or contiguous |
from, until | The window, with offset; from now to 48 hours later by default, at most 72 hours |
resolution | 60 (hour, default) or 15 (quarter) |
min_block | Split only: every run of picked slots lasts at least this many hours |
GET /api/v0/energy/cheapest?hours=2.25&mode=contiguous&resolution=15&until=2026-11-15T07:00:00+01:00
{
"mode": "contiguous",
"hours": 2.25,
"complete": true,
"selected_hours": 2.25,
"average_price": 0.0861,
"horizon_end": "2026-11-16T00:00:00+01:00",
"slots": [
{
"starts_at": "2026-11-15T02:45:00+01:00",
"ends_at": "2026-11-15T03:00:00+01:00",
"price": 0.0874
}
// … nine quarters in a row
]
}
The answer also says whether it is complete. Before 13:00, tomorrow's
prices are not there yet, so a window that reaches into tomorrow cannot always be
filled. Instead of an error you then get what there is, with complete
false and horizon_end telling you how far the known prices reach. An
automation can wait for the afternoon and ask again.
In Home Assistant
Home Assistant does the asking and the switching. The APIs know about prices and time; Home Assistant knows about the house, the devices and the contract. That split keeps both sides simple.
One sensor, a whole day of prices
A single REST sensor fetches today and tomorrow every fifteen minutes and keeps the
whole list as attributes. Everything else reads from that one sensor: the price now,
the next price, today's minimum and maximum, and the chart. The token lives in
secrets.yaml, never in the configuration itself.
rest:
- resource_template: "https://<api-host>/api/v0/energy/prices?from={{ now().date() }}&to={{ (now() + timedelta(days=1)).date() }}"
headers:
Authorization: !secret energy_api_authorization
scan_interval: 900
sensor:
- name: energy_price_raw
value_template: "{{ value_json.current.price }}"
json_attributes: [prices, summary_by_day, current] Min 27.0 · avg 37.6 · max 51.0 ct/kWh all-in
37.0 ct/kWh now
Cheap, normal or expensive
The API does not say what is cheap; that depends on your contract and on what you find worth waiting for. So Home Assistant labels every hour itself, from the price and the position, as cheap, normal or expensive. An hour counts as cheap when its all-in price is under a ceiling in cents, or when it sits low enough in its day. Both ceilings are plain helpers on the dashboard. That one label is easy to build automations on: run the boiler when it is cheap, warn when a heavy device starts in an expensive hour.
A planner: when to switch on?
The planner on the price dashboard uses both APIs on behalf of a person. Pick a device, or enter how long it runs, whether it may be interrupted, how soon it must be done and how much it uses per run. Press calculate, and it tells you when to start, when it is done and what that saves compared to starting right now, in all-in cents. Devices you use often are saved as presets, so the dishwasher is one tap.
Saves about 30 ct compared to starting now (18:05), at 2.5 kWh. At these times you pay 34.1 ct per kWh on average (all-in); starting now, 46.1 ct.
- 23:00 – 00:00
- 03:00 – 06:00
Saves about 19 ct compared to starting now (18:05), at 2 kWh. At these times you pay 35.0 ct per kWh on average (all-in); starting now, 44.6 ct.
The same call works without a person in the loop. A script takes a device, a run time and a deadline (by default the next 7:00), asks for the cheapest stretch, waits until it starts, switches the device on and, after the run time, off again.
From market price to what you pay
Billing is the quiet one. A camper and a shepherd's hut on the same yard draw their shore power through a metering plug each. Every step of the meter is charged at the all-in price of that moment, so a dynamic contract is shared fairly: power used at night is cheaper than power used at six in the evening, and the monthly statement shows it.
The what-if models are the curious one. One of them simulates a battery that charges in the cheapest hours and powers the house in the dearest, on the real consumption and the real prices, and works out the payback time before anything is bought. Another values a solar forecast at the price of the moment the sun would deliver. Both only need the prices; the decision to invest comes later, with data instead of a guess.
How it grew: template, copy, API
The APIs did not start as APIs. They grew the way I let most software grow, as described in let software emerge: simple first, repeat it, and only then pull out what turns out to be generic.
- Simple, in Home Assistant. It began as a price integration and a handful of templates in one installation: the price now, a cheap window, a colour on a chart. Good enough to learn what was actually needed.
- Repeat it. Then a second installation wanted the same, and a third: a house, a camper, a shepherd's hut. The templates were copied and adapted on purpose. Do repeat yourself: the copies show which part is the same everywhere and which part belongs to one place.
- Abstract the generic part. What was the same everywhere moved out: keeping prices with their history, the position within a day, and the planner. Finding the cheapest unbroken stretch, cutting the last slot short for a fractional hour, the 23- and 25-hour days around a clock change, prices that are not published yet: that is logic that wants tests, not Jinja. Written once, tested once, asked the same way by every installation.
What stayed in Home Assistant is what differs per place: the contract and its
surcharges, what counts as cheap, which devices to switch and when they must be
done. The configuration describes the house; the arithmetic over the market sits
behind a contract. The
API is at v0 and only grows: new fields and endpoints arrive next to the
old ones, so an installation that works today keeps working.
Who can use it
For now the APIs run for my own installations. Whether they open up to others, and on what terms, is not decided yet. If you have a dynamic contract and Home Assistant and this is the kind of thing you would like to use, or build something like it for your own situation, I would like to hear from you at solutions@czyk.nl.