Architecture & platform

Energy Prices

On this page
  1. What it is, in short
  2. Energy Prices
  3. Cheapest
  4. In Home Assistant
  5. How it grew
  6. Who can use it

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.

REST API Home Assistant Dynamic energy prices

Two APIs that tell Home Assistant when to use power

± 12 min read Published

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.

Day-ahead prices flow from the market into two endpoints, which Home Assistant asks and acts on Source The two APIs Home Assistant Day-ahead market tomorrow published daily around 13:00 Own price store every quarter, kept; history grows, gaps are backfilled fetched a few times a day Energy Prices what does power cost, per quarter or hour, and where does this slot sit in its day (0–100%)? GET /prices Cheapest I need power for N hours before this time: which slots, or which unbroken stretch? GET /cheapest Price now and later dashboard, all-in price Cheap or expensive? HA labels each hour itself When to switch on planner, charging, appliances both read the same store, never the market directly; a token decides which of the two a client may ask
The market publishes tomorrow's prices once a day; they land in a store of their own and stay there. Energy Prices answers what power costs; Cheapest answers when to use it. Home Assistant only asks, and decides itself what to switch.

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.

ParameterMeaning
dateOne local day (Europe/Amsterdam), defaults to today
from, toA range of local days, inclusive, instead of date
resolution60 (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_block keeps 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.
One day of hourly prices, with the slots Cheapest picks in split mode and in contiguous mode Split: the 4 cheapest hours, wherever they fall Contiguous: the cheapest unbroken 3 hours 00:0006:0012:0018:0023:00 an illustrative day; the night and the sunny middle are cheap, the evening is dear
A battery charger may stop and start, so it gets the cheapest hours wherever they are. A dishwasher may not, so it gets the one stretch with the lowest average. Same prices, same question, a different answer.
ParameterMeaning
hoursRequired. How long to use power, 0.25 to 48, fractions allowed
modesplit (default) or contiguous
from, untilThe window, with offset; from now to 48 hours later by default, at most 72 hours
resolution60 (hour, default) or 15 (quarter)
min_blockSplit 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]
Power price 14 Nov 14:00 – 15 Nov 24:00 · per hour

Min 27.0 · avg 37.6 · max 51.0 ct/kWh all-in

37.0 ct/kWh now

0 30 60 18:0015 Nov06:0012:0018:00 ▼ 27.0 ▲ 51.0 now
QuarterHourDayMonth
The price dashboard in Home Assistant, simplified. Green is cheap, red is dear, and the colour follows the position within each day. Around 13:00 tomorrow is published, so by the afternoon the chart reaches to midnight the next day.

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.

Uninterrupted: a dishwasher gets one start time.
Split: a bike battery may pause, so it charges in two blocks.

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

The bare market price becomes the all-in price in Home Assistant, which then feeds billing, planning and what-if models Market price from the API, EUR/kWh × VAT factor, e.g. 1.21 + Surcharges energy tax, supplier = All-in price what you pay Fair billing every metered kWh at the price of that moment, not a monthly average When to switch on the planned slot against starting right now, in cents What would it earn? a battery or solar panels, simulated before you buy them
The API stays neutral: it serves the market price, without taxes or a supplier's margin. Home Assistant knows your contract, so it adds those itself and calculates on with the price you actually 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.

  1. 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.
  2. 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.
  3. 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.