Documentation

Energy Forecast

Copy page

TL;DR

• GET /v1/users/{userId}/home/energy-forecast — a forward-looking, quarter-hourly energy forecast: price, PV production, household consumption, battery state of charge and grid flows
• The series is quarter-hourly (15-minute slots) and forward-looking — it starts at the current slot and runs to the end of tomorrow; there is no elapsed-today or measured data
• Energy values are kWh per slot, prices are ct/kWh; all timestamps are UTC (...Z)
• Shares its prerequisites and enable/disable toggle with the Solar Forecast endpoints: a home location and at least one producing device are required, and the forecast must be enabled
• Missing prerequisites return distinct, actionable errors (409/404) instead of an empty body

The Energy Forecast endpoint exposes clever-PV's quarter-hourly look-ahead for a user's home: expected price, PV production, household consumption, battery state of charge and grid import/feed-in for the rest of today and tomorrow. It is intended for partner integrations that want to anticipate price windows, grid flows and battery behaviour, or align loads with expected solar surplus.

This endpoint is read-only. The home location and the enable/disable toggle it depends on are managed via the Solar Forecast endpoints (PUT …/home/location, PUT …/home/solar-forecast).

---

Solar Forecast vs. Energy Forecast

Both forecasts read from the same home (location, producing device, enabled flag), but return different data at different resolutions:

	Solar Forecast	Energy Forecast (this page)
Endpoint	GET …/home/solar-forecast	GET …/home/energy-forecast
Granularity	Hourly	Quarter-hourly (15-minute slots)
Coverage	Measured production so far today + forecast for today/tomorrow	Forward-looking only — current slot through tomorrow; no elapsed-today or measured data
Data returned	PV production (measured + forecast) and the weather behind it (clouds, rain, snow, icon)	Price, PV production, household consumption, battery state of charge, grid import/feed-in
Typical use	Display a production curve, compare forecast vs. actual, show weather context	Anticipate price windows, plan around battery/grid behaviour, align loads with solar surplus
Manages location/toggle	Yes — PUT …/home/location, PUT …/home/solar-forecast	No — reuses Solar Forecast's location and enabled flag

If you need weather or a production-vs-actual comparison, use Solar Forecast. If you need price, consumption, battery or grid figures, use Energy Forecast. Both can be called independently once the shared prerequisites are met.

---

Prerequisites

A forecast can only be produced once both of the following are true:

1. The home has a location. Set it with PUT …/home/location (see Solar Forecast).
2. The home has at least one producing device — a solar inverter or an electric meter — onboarded.

The forecast must also be enabled (PUT …/home/solar-forecast with { "enabled": true }) — there is no separate enable flag for the energy forecast.

After the location is set, generation runs in the background. The forecast is not available instantly: GET returns 404 solarForecastNotAvailable until the first forecast has been produced, then 200.

---

Get the forecast

GET /v1/users/{userId}/home/energy-forecast

Code
GET /v1/users/3f9b1c7a-.../home/energy-forecast
Authorization: Bearer eyJhbGciOi...

200 OK

Code
{
  "createdAtUtc": "2026-06-30T11:52:02Z",
  "entries": [
    {
      "time": "2026-06-30T11:45:00Z",
      "price": 20.23046,
      "stockPrice": 3.61046,
      "houseConsumptionKwh": 0.1,
      "solarProductionKwh": 0.2037,
      "soc": 90,
      "gridConsumptionKwh": 0,
      "gridFeedInKwh": 0
    }
  ]
}

Top-level fields

Field	Type	Description
createdAtUtc	string	When the forecast was computed, UTC ISO-8601 (...Z).
entries	array	The quarter-hourly forecast slots, ordered by time ascending.

Forecast entry

Each entry is one 15-minute slot.

Field	Type	Description
time	string	Start of the 15-minute slot, UTC ISO-8601 (...Z).
price	number?	End-customer buy price for the slot, in ct/kWh. null when no price is available.
stockPrice	number?	Raw exchange (spot) price for the slot, in ct/kWh. null when unavailable.
houseConsumptionKwh	number	Forecasted household consumption for the slot, in kWh.
solarProductionKwh	number	Forecasted PV production for the slot, in kWh.
soc	int?	Forecasted battery state of charge at the slot, in percent (0–100). null when the home has no battery.
gridConsumptionKwh	number	Forecasted grid import for the slot, in kWh.
gridFeedInKwh	number	Forecasted grid feed-in for the slot, in kWh.

The series is forward-looking: it starts at the current 15-minute slot and runs to the end of tomorrow (up to the forecast horizon). It does not include elapsed-today slots or measured values. Every timestamp is UTC (...Z).

---

Error responses

All errors follow RFC 7807 (application/problem+json) using the partner-friendly ConnectApiProblemDetails shape (type + errorCode + traceId + optional detail).

Status	errorCode	Meaning
401	—	Missing or invalid bearer token.
403	—	Token lacks the connect_api scope.
404	missingHome	The authenticated user has no home.
404	solarForecastNotAvailable	The forecast is enabled and prerequisites are met, but it has not been generated yet. Retry shortly.
409	homeLocationRequired	No home location is set. Call PUT …/home/location first.
409	solarProducerRequired	The home has no producing device (inverter/meter); a forecast cannot be generated.
409	solarForecastDisabled	The forecast is disabled. Enable it via PUT …/home/solar-forecast to regenerate.
429	—	Global IP rate limit (100 requests / 10 seconds).
500	internalError	Unhandled server error.

These are the same prerequisite and error codes used by Solar Forecast — the two endpoints share the same underlying location, producer and enabled-flag gates.

---

Important notes

• Units: energy fields (houseConsumptionKwh, solarProductionKwh, gridConsumptionKwh, gridFeedInKwh) are in kWh per 15-minute slot; price/stockPrice are in ct/kWh; soc is a percentage.
• Resolution & horizon: the series is quarter-hourly and forward-looking — from the current slot to the end of tomorrow. There is no elapsed-today data; to compare forecast against actuals, use the Historical Energy Data endpoints.
• UTC only: All timestamps are UTC (...Z).
• null is valid: null price/stockPrice means no price is available for the slot; null soc means the home has no battery. Neither is an error.
• Shared toggle: there is no dedicated enable/disable for the energy forecast — it follows the same Home.SolarForecastEnabled flag as the Solar Forecast endpoints.