Language

DE NL FR DA EN CS

Home Assistant · price and CO2

Two equally supported ways to get price and CO2 data into Home Assistant

There are two fully supported paths: a native HACS integration with UI-based setup, or a plain REST sensor you paste into YAML. Both use the same API and return current values, live window state and the most useful time windows.

Add the HACS integration Open live JSON Home Assistant forum thread

HACS integration: UI setup, its own entities, currently a custom repository (not yet listed in the HACS default store)
REST sensor: one endpoint for price, CO2 and useful time windows, no HACS required
clear separation between base price, CO2 and total-price support - identical on both paths

Which path fits you?

Both paths call the same summary endpoint and return the same data. The difference is setup and maintenance.

Option A HACS integration Set up through a dialog in the Home Assistant UI, with diagnostic sensors, an optional retail price and a configurable poll interval. Requires HACS and, for now, manually adding it as a custom repository. Option B REST sensor (this page) Paste one YAML block, done. No HACS needed, full control over your YAML config - a good fit if you already manage your Home Assistant config in Git.

Open-source repository for the HACS integration: github.com/BackupBaTTerY/energypriceforecast-home-assistant. Both paths can run side by side, as long as you don't create duplicate entity IDs.

Start free, plan further when needed

The Home Assistant setup remains available without an API key for up to 48 hours. If you want to plan larger loads across several days, you can try Private Pro with up to 120 hours free for 14 days.

View Private Pro

API migration

New integrations should now use https://api.energypriceforecast.eu/api/v1/.... Some older project URLs still work for existing setups, but they should no longer be treated as the reference path for new integrations.

Setting up the HACS integration

While the integration isn't in the HACS default store yet, add the repository manually once.

Open HACS, then the "⋮" menu → Custom repositories.
Add repository URL https://github.com/BackupBaTTerY/energypriceforecast-home-assistant, category Integration, add it.
Search for "Energy Price Forecast EU", download it, then restart Home Assistant.
Settings → Devices & Services → Add Integration, search for "Energy Price Forecast EU" and pick your market plus any optional settings.

The button above ("Add the HACS integration") opens steps 1 and 2 automatically if HACS is already installed.

Build a price chart with AI (HACS integration)

Two sensors carry raw_today/raw_tomorrow attributes - a list of price time slots, made for charting with the community card apexcharts-card (installed separately via HACS): the always-on sensor ending in _price_series (day-ahead/spot price) and, if you enabled retail pricing during setup, the sensor ending in _retail_current_price (assumption-based all-in price). Both also carry a raw_forecast attribute: the entries beyond the published day-ahead window - the actual ML/weather-based forecast. This prompt builds the matching Lovelace card for you.

Show the copyable prompt

Help me build a Home Assistant Lovelace card that charts electricity prices from the Energy Price Forecast EU integration using the apexcharts-card custom card.

The integration creates a sensor whose entity_id ends in "_price_series" (day-ahead/spot price, the exact name depends on my chosen market, for example sensor.energy_price_forecast_eu_de_price_forecast_series) and, if I enabled retail pricing, a second sensor ending in "_retail_current_price" (assumption-based all-in price) with the same attribute shape. Each sensor's state is its current price; its attributes raw_today, raw_tomorrow and raw_forecast are each a list of objects shaped like {"start": ISO8601 timestamp, "end": ISO8601 timestamp, "value": number}. raw_today/raw_tomorrow only ever cover the published day-ahead window (known prices, never estimated); raw_forecast holds only the entries beyond that window - the actual ML/weather-based forecast. The value's unit matches the market's currency (for example EUR/kWh).

My actual entity_id is:  Devices & Services > Energy Price Forecast EU, or Developer Tools > States, filtering for "price_series" or "retail_current_price">

Before writing YAML, ask me:
1. Do I already have HACS and the apexcharts-card custom card installed? If not, tell me to install apexcharts-card via HACS first (category: Frontend/Plugin).
2. Should I chart the spot/day-ahead price (_price_series) or my retail all-in price (_retail_current_price), if I have that enabled?
3. Should the chart show today only, today and tomorrow together, or known prices plus forecast (raw_today + raw_tomorrow + raw_forecast) as two visually distinct series (e.g. solid vs dashed, different colors)?
4. Do I also want the cheapest-hours window highlighted, if I enabled that feature? (binary_sensor ...is_in_cheapest_hours / sensor ...cheapest_hours_next_start)
5. Do I want a bar chart per hour or a line/area chart?

Rules for your result:
- Use only the raw_today / raw_tomorrow / raw_forecast attributes I described. Do not invent other attributes or a different data shape.
- Use apexcharts-card's data_generator to turn the attribute list into a chart series - do not assume the card accepts the attribute directly as a series.
- If I asked for known prices and forecast as separate series, use two series against the same entity (one summing raw_today+raw_tomorrow, one for raw_forecast), each with its own data_generator, and set extend_to: false on both - otherwise apexcharts-card visually extends the last value to the edge of the graph, which is misleading here.
- Quote any string value (title, name, tooltip format) that itself contains a colon, like "Known: forecast" or "dd.MM. HH:mm" - an unquoted colon inside a YAML value breaks parsing.
- Produce a complete, correctly indented YAML block for a manual Lovelace card (type: custom:apexcharts-card).
- Tell me exactly where to paste it (Dashboard > Edit > Add card > Manual).
- If information is missing, ask - do not guess my entity_id or market.

Recommended endpoint

For Home Assistant, /api/v1/home-assistant/summary is the simplest entry point. It returns not just raw values, but already computed windows for cheapest, greenest and combined use.

https://api.energypriceforecast.eu/api/v1/home-assistant/summary?country=de&hours=48&window_hours=4

Priceflat.current_price and flat.cheapest_window_*.

CO2flat.current_co2_g_kwh and flat.greenest_window_*.

Combinedflat.combined_window_* for the price/CO2 compromise.

Quick start for copy and paste (REST sensor path)

If you picked the REST sensor path, this is intentionally simple: paste the YAML block, adjust the market, reload Home Assistant.

Paste the YAML block below into configuration.yaml or into a package file that Home Assistant already loads.
Only change the country parameter. For Denmark, always use dk1 or dk2.
Reload or restart Home Assistant.
Check Developer Tools to confirm that the new sensors return values.

Beginner-friendlyThe example deliberately uses simple flat fields instead of complex templates, so it stays copy-paste friendly.

What you need to changeUsually only country. The rest can stay unchanged.

What should appear afterwardsAt least one current-price sensor and one cheapest-window sensor.

REST sensor example

This example polls Germany every 15 minutes. For other markets, only the country parameter changes.

rest:
  - resource: "https://api.energypriceforecast.eu/api/v1/home-assistant/summary?country=de&hours=48&window_hours=4"
    scan_interval: 900
    sensor:
      - name: "EnergyPriceForecast current price"
        value_template: "{{ value_json.flat.current_price }}"
        unit_of_measurement: "EUR/kWh"

      - name: "EnergyPriceForecast current CO2 intensity"
        value_template: "{{ value_json.flat.current_co2_g_kwh }}"
        unit_of_measurement: "gCO2/kWh"

      - name: "EnergyPriceForecast cheapest window start"
        value_template: "{{ value_json.flat.cheapest_window_start }}"

      - name: "EnergyPriceForecast greenest window start"
        value_template: "{{ value_json.flat.greenest_window_start }}"

After adding the block, reload or restart Home Assistant and verify the sensor values in Developer Tools.

Official field reference for `home-assistant/summary`

The summary endpoint is intentionally compact. For many automations, the flat block is already enough. If you want more control or custom dashboards, use the more structured price, co2, combined and source blocks as well.

Field	Meaning	Typical use
`flat.current_price`	Current price in `EUR/kWh`. For the current slot it automatically uses the best available public source.	Simple price sensor for automations.
`flat.current_price_source`	Source label of the current price, for example `day_ahead`.	Check whether the value is already official or still forecast-based.
`flat.current_co2_g_kwh`	Current CO2 intensity in `gCO2/kWh`.	CO2-based shifting of flexible loads.
`flat.cheapest_window_*`	Start, end and average value of the cheapest time window in the requested horizon.	EV charging, boilers, heat pumps.
`flat.greenest_window_*`	Start, end and average value of the lowest-CO2 time window.	Low-CO2 scheduling.
`flat.combined_window_*`	Compromise window between price and CO2.	When both matter and you do not want to define your own weighting.
`price.current`	Object with `start`, `end`, `value`, `unit` and `source` for the current price slot.	Dashboards and more precise state logic.
`price.cheapest_window_next_horizon`	Structured cheapest-window block including duration and source counts.	When you want start, end and context together.
`co2.current`	Object with the current CO2 value and its time window.	CO2 display without parsing `flat`.
`co2.greenest_window_next_horizon`	Structured greenest-window block.	Low-CO2 charging or heating logic.
`combined.best_window_next_horizon`	Combined recommendation path with price, CO2 and score values.	A single "best now" decision without building your own score.
`source.price`	Metadata about the price source, including Firestore document, day-ahead provider and counts of available entries.	Debugging, monitoring and quality checks.
`source.co2`	Metadata about the CO2 source.	Debugging and traceability.

Important about price fieldsThe summary endpoint does not return the full raw series of every price variant. For Home Assistant it mainly returns the current state and already computed windows. For full hourly series, hourly-forecast is the better endpoint.

Current does not mean historical actualflat.current_price is the currently usable public price for the running slot. It can come from the official day-ahead auction or from another released source when the full market result is not available yet.

Retail only for selected marketsThe public retail-forecast endpoint is currently intended only for selected markets. For other markets, the summary deliberately stays on market or base values.

When is `summary` enough, and when do you need `hourly-forecast`?

summary is enough for simple automations

If you only need the current price, the current CO2 intensity or the best 4-hour window, home-assistant/summary is the right endpoint. It keeps the YAML short and avoids unnecessary parsing.

hourly-forecast is better for charts and complex templates

If you want to draw your own charts, compute your own scores or separate day-ahead values from model forecast values, use hourly-forecast. That endpoint exposes the hourly series more explicitly.

Public API support matrix

Not every visible market is publicly enabled for every endpoint yet. This matrix makes the current support level explicit instead of relying on guesswork.

Market	`hourly-forecast`	`home-assistant/summary`	`co2-live`	Retail end-price forecast `retail-forecast`
DE	yes	yes	yes	yes
NL	yes	yes	yes	yes
BE	yes	yes	yes	no
FR	yes	yes	yes	no
CZ	yes	yes	yes	no
AT	yes	yes	yes	yes
PL	yes	yes	yes	no
FI	yes	yes	yes	no
SE1	yes	yes	yes	no
SE2	yes	yes	yes	no
SE3	yes	yes	yes	no
SE4	yes	yes	yes	no
DK1	yes	yes	yes	yes
DK2	yes	yes	yes	yes
NO1	yes	yes	yes	yes
NO2	yes	yes	yes	yes
NO3	yes	yes	yes	yes
NO4	yes	yes	yes	yes
NO5	yes	yes	yes	yes

DenmarkUse dk1 or dk2. A generic dk request resolves to DK1.

Czech RepublicCZ is now public for price and CO2 in the summary and live CO2 path. Retail end-price forecast is not public yet.

Retail end priceretail-forecast means an estimated end-customer electricity price, not just the wholesale or base market price. It is currently public for DE, NL, DK1, DK2, AT, and NO1 to NO5.

Adapt it to your setup with AI

This prompt helps an AI turn the summary endpoint into a Home Assistant automation for your actual load, deadline and safety rules. It supplements the copy-paste setup above rather than replacing it.

Protect your API key

Never give an AI your real API key. Keep YOUR_API_KEY in the generated result and insert the key locally in Home Assistant.

Show the copyable prompt

Help me build a safe Home Assistant automation using the Energy Price Forecast EU API.

Read the API contract first:
https://energypriceforecast.eu/openapi/integration-api.json

Use /api/v1/home-assistant/summary and do not invent fields. The API uses official day-ahead prices wherever available and forecast values only for the remaining open horizon.

Before writing YAML, ask me no more than these questions, one at a time:
1. Country or bidding zone?
2. Which load should be controlled and which Home Assistant entity switches it?
3. Power, required runtime and latest completion time?
4. Optimise for price, CO2 or both?
5. Free without a key and up to 48 hours, or Private Pro with up to 120 hours?
6. Do I use packages or configuration.yaml?

Rules for your result:
- Free: hours=48 and no Authorization header.
- Private Pro: hours=120 and header Authorization: Bearer YOUR_API_KEY.
- Never ask me to paste the real key into the chat.
- Handle HTTP errors and check meta.api_key_state and meta.allowed_horizon_hours.
- Briefly explain every API property you use.
- Produce complete, correctly indented YAML and state exactly where it belongs.
- Start with a safe test mode using a notification or input_boolean. Put real load switching in a separate, clearly marked step.
- Define safe behaviour for stale, missing or implausible data. An API error must never switch the load on unexpectedly.
- Finish with a checklist: HTTP 200, sensors populated, allowed horizon correct and test mode triggered correctly.

Ask when information is missing. Do not silently assume entity names, tariffs or electrical limits.

Machine-readable foundation: OpenAPI contract for the integration endpoints.

Important notes

Is there an official Home Assistant integration?

Yes, a native HACS integration is available (currently as a custom repository, see the comparison above). This page's REST-sensor path remains fully supported too - it's easier to test, easier to reason about and already sufficient for many setups.

Are the API prices my exact household electricity price?

Not automatically. hourly-forecast and the Home Assistant summary start with market/base prices. The exact total price depends on country-specific grid fees, taxes, levies and supplier markup.

What happens for an unsupported country?

The public API now returns an explicit error instead of silently falling back to Germany. That is intentional so automations do not run on wrong data.

What if no values appear after pasting the YAML?

The most common causes are: the YAML was pasted into the wrong place, Home Assistant was not reloaded, the country value is unsupported, or the YAML indentation is broken. Developer Tools and the Home Assistant logs usually show this immediately.