# Historische Daten

Die historischen Daten liefern vergangene PV-Erträge und Wetterdaten für einen Standort. Wie bei
der Prognose fragen Sie über die `site_id` ab; Standort, Strings und Konfiguration kommen aus dem
gespeicherten Standort.

```bash
GET /v2/historical/{site_id}
```

In der V2 sind die alten V1-Endpunkte `/recent` und `/history` **zu einem Endpunkt
verschmolzen**.

Zeitstempel sind standardmäßig in der **lokalen Zeitzone** des Standorts (siehe `timezone` in der
Antwort). Mit `?timezone=utc` erhalten Sie stattdessen UTC-Zeitstempel mit `Z` am Ende.

:::tip
Die vollständige Parameter- und Feldliste steht in der [API-Referenz](/api). Diese Seite erklärt
die Konzepte.
:::

## Zeitraum wählen

Sie geben den Zeitraum **entweder** als gleitendes Fenster (`period`) **oder** mit festem
Start-/Enddatum an — nicht beides.

### Gleitendes Fenster: `period`

`period` folgt dem Muster `^\d+[dmy]$`:

| Suffix | Bedeutung                      |
|--------|--------------------------------|
| `d`    | Tage (z. B. `7d`)              |
| `m`    | Monate (z. B. `3m` = 3 Monate) |
| `y`    | Jahre (z. B. `1y` = 1 Jahr)    |

```bash
GET /v2/historical/{site_id}?period=30d
```

Reine Zahlen (`30`) werden abgelehnt.

### Festes Fenster: `start_date` / `end_date`

ISO-Datumsangaben (`YYYY-MM-DD`), **beide zusammen** erforderlich:

```bash
GET /v2/historical/{site_id}?start_date=2026-01-01&end_date=2026-01-31
```

`period` mit `start_date`/`end_date` zu mischen ergibt **400**.

## `include`-Gruppen

Wie bei der Prognose, aber **ohne** `clearsky`:

| Gruppe       | Felder                                                           |
|--------------|------------------------------------------------------------------|
| `default`    | `pv_power` (PV-Leistung in W).                                   |
| `weather`    | Temperatur, Wettercode, Wind, Luftfeuchte, Niederschlag, Schnee. |
| `irradiance` | `ghi`, `dhi`, `bni`.                                             |
| `all`        | Alle Gruppen plus den `strings`-Block.                           |

:::note
Historische Antworten enthalten **kein** `daily`-Aggregat und **keine** Clear-Sky-Werte — nur
`values` und (bei `strings`/`all`) den per-String-`strings`-Block. Der `strings`-Block
funktioniert wie bei der [Prognose](/de/v2/api/forecast).
:::

## Validierung & Limits

Der angefragte Zeitraum wird gegen Plan und Plausibilität geprüft:

- `end_date` darf höchstens **gestern** sein.
- `start_date ≤ end_date`.
- Spanne oder Anfangsdatum ≤ Ihr Plan-Limit

Verstöße ergeben **400** mit erklärender Meldung.

| Limit / Fehler               | Verhalten                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| Zugriff zur Historical-API   | Ohne Historical-Zugang im Plan → **403**.                                      |
| Monatilchen Historical Limit | Monatliches Anfragelimit (pro Nutzer & Endpunkt) → **429** bei Überschreitung. |
| `max_period_days`            | Maximale Spanne pro Anfrage.                                                   |
| `earliest_start_date`        | Frühestes abrufbares Datum.                                                    |

Es gibt **kein** Caching; jede erfolgreiche Anfrage zählt auf das Monatslimit.

:::tip
Ihre konkreten Limits finden Sie auf der Seite über [Nutzung & Limits](https://pvnode.com/usage).
:::