Language
DE EN NL

Homey · price and CO2

Use electricity price and CO2 in Homey without building a full Homey app

For Homey, the sensible first step is not a full App Store integration but a compact summary endpoint plus simple HomeyScript cards in Advanced Flow. That is faster to test and much easier to understand.

Open Homey JSON Open HomeyScript

Core logic explained early

The price logic is not “forecast only”. It deliberately works in two stages so real market data always wins as soon as it exists.

Step 1As soon as official day-ahead exists for a slot, that value is preferred.
Step 2Forecast is used only for future slots not yet covered by official day-ahead data.
Why it mattersThe summary therefore combines real day-ahead prices with forecast values only for the still-open part of the horizon.
Why this path makes sense for Homey

Homey itself strongly centers around flows and HomeyScript. For a first rollout, that is much more pragmatic than immediately building and publishing a full Homey app.

Important for beginners

This page intentionally uses small HomeyScript cards in Advanced Flow. That makes testing easier because each card returns exactly one value.

Recommended entry point: summary

Homey gets its own summary path. Technically it stays close to the other automation endpoints, but its structure and naming are tuned for HomeyScript and Advanced Flow.

https://api.energypriceforecast.eu/api/v1/homey/summary?country=de&hours=48&window_hours=4
Current priceflat.current_price for charging or switching decisions.
CO2 liveflat.current_co2_g_kwh for greener automations.
Window logicflat.is_cheapest_window_now and price.next_full_window.start for direct flow logic.

What the API actually returns

The Homey endpoint returns a compact automation view. That matters because in Homey you usually do not want to start with a full raw time series but with a few clear values for flows.

Part Content Why it matters
flatCurrent price, current CO2, active best windows and remaining minutes.Ideal for simple HomeyScript return values.
priceCurrent price slot plus best_window and next_full_window.For planning and future-oriented logic.
co2Current CO2 slot plus CO2 windows.For greener instead of cheaper automations.
sourceMetadata about day-ahead and forecast.Important for interpretation and debugging.
metaAPI key state, allowed horizon and daily counters.Useful for limits and troubleshooting.

Time horizon and resolution

The examples use hours=48 and window_hours=4. That is a sensible starting point, but not the full product limit.

Time horizonUse hours to define the requested horizon. Publicly, we currently communicate up to 120 hours for the price forecast.
Actually allowedWithout an API key, 48 hours are currently free. A key may allow more. The authoritative field is always meta.allowed_horizon_hours.
ResolutionDay-ahead may arrive in quarter-hour slots, while forecast and CO2 are usually hourly. The summary compresses that into automation-friendly fields.

How to use it in Advanced Flow

  1. Install HomeyScript.
  2. In Advanced Flow, add a time trigger, for example every 15 minutes.
  3. Then add a HomeyScript card with return type Number, Yes/No or Text.
  4. Paste one of the copy-paste blocks below.
  5. Use the result tag in the next flow step.

Homey explicitly describes HomeyScript as a way to access website APIs. The examples below use exactly that with the Homey summary endpoint.

Example 1: return the current price as Number

Use this if you want to build threshold-based or comparison logic.

const API_KEY = '';
const url = 'https://api.energypriceforecast.eu/api/v1/homey/summary?country=de&hours=48&window_hours=4';

const response = await fetch(url, {
  headers: API_KEY.trim()
    ? { Authorization: `Bearer ${API_KEY.trim()}` }
    : {},
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const data = await response.json();
return Number(data.flat?.current_price ?? 0);

Example 2: is the best price window active right now?

For real automations this is often more useful than only knowing the next start time.

const API_KEY = '';
const url = 'https://api.energypriceforecast.eu/api/v1/homey/summary?country=de&hours=48&window_hours=4';

const response = await fetch(url, {
  headers: API_KEY.trim()
    ? { Authorization: `Bearer ${API_KEY.trim()}` }
    : {},
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const data = await response.json();
return data.flat?.is_cheapest_window_now === true;

Example 3: return the next full start as Text

Useful for planning, dashboards or notifications.

const API_KEY = '';
const url = 'https://api.energypriceforecast.eu/api/v1/homey/summary?country=de&hours=48&window_hours=4';

const response = await fetch(url, {
  headers: API_KEY.trim()
    ? { Authorization: `Bearer ${API_KEY.trim()}` }
    : {},
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const data = await response.json();
return String(data.price?.next_full_window?.start || '');

Optional with API key

If you want to test more than the free horizon, place the key directly in the script. The API currently expects a Bearer header.

const API_KEY = 'YOUR_API_KEY';
const url = 'https://api.energypriceforecast.eu/api/v1/homey/summary?country=de&hours=120&window_hours=4';

In the end, the authoritative value is not just what you ask for in the URL, but what the server actually allows in meta.allowed_horizon_hours.

Typical Homey use cases

EV chargingOnly charge when is_cheapest_window_now is true or the current price is below a threshold.
Heat pump or boilerUse cheap windows for pre-heating or buffering instead of hardcoded times only.
NotificationsReturn the next good start as text and use it in push or voice notifications.

Important meta fields for debugging

Field Meaning Why relevant
meta.api_key_statemissing, valid, inactive or another error state.Check whether your Bearer token is really applied.
meta.allowed_horizon_hoursServer-side allowed maximum horizon.Important for 48h vs. 120h.
meta.used_horizon_hoursActually used horizon.Shows whether a request was shortened.
meta.used_calls_todayAPI calls used today.Useful for observing real usage in tests.

Current product stage

For Homey we are deliberately starting with the light path via HomeyScript and Advanced Flow. A real Homey app would be possible, but it is much heavier to test, review and maintain as a first step.