Copy page

Sites & Data

Forecasts

The forecast delivers the expected PV power for a site in 15-minute intervals. You query it via the site_id; site, strings and configuration come from the stored site.

Code
GET /v2/forecast/{site_id}

Timestamps are in the site's local timezone by default (see timezone in the response). Pass ?timezone=utc to receive UTC timestamps ending in Z instead.

Parameters

Parameter	Meaning
forecast_days	Forecast horizon in days. Without a value, the plan maximum. Hard limit 7, additionally capped to the plan limit.
past_days	Past days before today (archived forecast). Default 0. Hard limit 30, capped to the plan limit.
include	Which field groups come back (repeatable). Default default.
timezone	Timezone of the timestamps: local (default) or utc. utc returns UTC timestamps ending in Z.

include groups

include is repeatable and selects field groups — not individual columns:

Code
GET /v2/forecast/{site_id}?include=weather&include=irradiance

Group	Fields
default	pv_power (PV power in W).
weather	temp, weather_code, wind_speed, relative_humidity, precipitation_mm, snow_water_equivalent.
irradiance	ghi, dhi, bni (horizontal irradiance).
clearsky	pv_power_clearsky (power under a cloudless sky).
strings	Adds the separate strings block (see below). values stays unchanged.
variability	Adds the min/max band (see below). Paid feature, never part of all.
all	All field groups and the strings block (but not variability).

Response structure

Response (abridged)
{
  "site_id": "site_rv8wm5…",
  "timezone": "Europe/Berlin",
  "computed_at": "2026-06-09T08:00:00",
  "included": [
    "default"
  ],
  "daily": [
    {
      "date": "2026-06-09",
      "pv_energy_kwh": 42.7,
      "temp_min": 11.0,
      "temp_max": 24.3
    }
  ],
  "values": [
    {
      "timestamp": "2026-06-09T12:00:00",
      "pv_power": 8200.0
    }
  ]
}

• daily — daily aggregates (energy in kWh, min/max temperature, dominant weather code).
• values — time series per 15 minutes. pv_power is the sum over all strings.

The strings block

With include=strings (or all) you get a separate top-level array strings in long/tidy format — one row per time step and string:

Code
"strings": [
{"timestamp": "2026-06-09T12:00:00", "string_index": 0, "string_id": "str_9f3a1c08", "pv_power": 5100.0, "gti": 820.0, "gti_shaded": 815.0},
{"timestamp": "2026-06-09T12:00:00", "string_index": 1, "string_id": "str_4b7e2d10", "pv_power": 3100.0, "gti": 760.0, "gti_shaded": 752.0}
]

• string_index refers position-based to site.strings[i] — same order as in GET /v2/sites/{site_id}. Always present.
• string_id is the string's stable id — the join key to its measurements. Present for saved sites; on the inline endpoint it appears only if you supplied an id on the string.
• The tilted irradiance (gti, gti_shaded) lives here, not in values, because it depends on the string's orientation.
• Each string delivers a row in every time step (0.0 at night), so there are no gaps.
• values.pv_power is the sum of the string powers.

In a DataFrame the block can be loaded directly and pivoted on string_index:

Code
import pandas as pd

df = pd.DataFrame(response["strings"])
wide = df.pivot(index="timestamp", columns="string_index", values="pv_power")

Variability band (include=variability)

The band delivers a lower/upper bound of the PV power, if available in your plan. A request with include=variability on a plan without this feature returns 403.

• Fields: pv_power_min / pv_power_max in every values and strings row, plus pv_energy_kwh_min / pv_energy_kwh_max in daily.
• Horizon: covers roughly the next 48 h. Outside that (and for past_days) min == max == pv_power (flat band). Sites not covered also receive a flat band — not an error.
• variability is never included by all, only on explicit request.

Caching & computed_at

Forecasts are not recomputed on every request, but only as often as your plan allows. Repeated requests in the same slot return the same cached result; computed_at shows the computation time.

The cache is automatically invalidated when the site changes (coordinates, strings, config) or the plan changes.

Limits & errors

Limit / error	Behavior
Forecast access	Without forecast access in the plan → 403.
Monthly requests	Monthly request limit (per user & endpoint), reset on the 1st of the month → 429 when exceeded.
forecast_days / past_days	Values are capped to the plan limit.
Site not found	404.