# Konfiguration für pvnode

> Umgebungsvariablen des Forecast-Collectors für den Anbieter pvnode, für die Site-basierte API v2 und die ältere API v1.

Diese Seite beschreibt die Umgebungsvariablen für den Anbieter [pvnode](https://pvnode.com). Der Forecast-Collector unterstützt den kostenlosen wie den kostenpflichtigen pvnode-Tarif.

Dazu kommen die [allgemeinen Einstellungen](/docs/referenz/forecast-collector/allgemeine-konfiguration/), allen voran `FORECAST_PROVIDER=pvnode`.

## Zwei API-Varianten

Der Forecast-Collector kann pvnode auf zwei Arten ansprechen:

- **v2 (Site-basiert)**: Standort und PV-Strings liegen als _Site_ in der pvnode-Web-App. Sie wird dort einmalig von Hand angelegt, der Collector kann das nicht übernehmen. In der Konfiguration steht dann nur noch die ID dieser Site als [`PVNODE_SITE_ID`](#pvnode_site_id). Die Variablen für Standort, Dachflächen und `PVNODE_EXTRA_PARAMS` sind damit wirkungslos.
- **v1 (Plane-basiert)**: Standort und Dachflächen stehen vollständig in den Umgebungsvariablen des Collectors. Das ist das bisherige Verhalten.

> **v1 wird abgeschaltet**
>
>
> pvnode stellt die v1-API zum **31.12.2026** ein. Wer pvnode nutzt, sollte bis dahin auf v2 umgestellt haben.
>
> Der Forecast-Collector beherrscht seit [v0.10.0](https://github.com/solectrus/forecast-collector/releases/tag/v0.10.0) beide Varianten. Bestehende Installationen laufen nach einem Update unverändert weiter; die Umstellung erfolgt, sobald eine Site angelegt ist.
>

## Vollständiges Beispiel

```properties title=".env"
# Anbieter
FORECAST_PROVIDER=pvnode

# Zeitzone
TZ=Europe/Berlin

# pvnode-Zugangsdaten
PVNODE_APIKEY=pvn_my-secret-api-key

# Site-ID aktiviert die API v2
PVNODE_SITE_ID=site_xxxxxxxxxxxxxxxxxxxxxx

# Optional: Tarif des kostenpflichtigen pvnode-Kontos
# PVNODE_PAID=true
# oder
# PVNODE_PAID=nowcast

# Optional: Selbst gesetztes Monatslimit für Abfragen
# PVNODE_REQUEST_LIMIT=500

# InfluxDB
INFLUX_HOST=influxdb
INFLUX_SCHEMA=http
INFLUX_PORT=8086
INFLUX_TOKEN=my-super-secret-write-token
INFLUX_ORG=solectrus
INFLUX_BUCKET=solectrus
INFLUX_MEASUREMENT=Forecast
```

Ohne `PVNODE_SITE_ID` läuft der Collector über die API v1. Standort und Dachflächen kommen dann aus den Variablen weiter unten:

```properties title=".env (API v1)"
# Standort
FORECAST_LATITUDE=50.12345
FORECAST_LONGITUDE=6.12345

# Anzahl der Dachflächen
FORECAST_CONFIGURATIONS=2

# Erste Dachfläche (nach Süden)
FORECAST_0_DECLINATION=30
FORECAST_0_AZIMUTH=180
FORECAST_0_KWP=5.5

# Zweite Dachfläche (nach Westen)
FORECAST_1_DECLINATION=30
FORECAST_1_AZIMUTH=270
FORECAST_1_KWP=3.9

# Optional: Zusätzliche API-Parameter
# PVNODE_EXTRA_PARAMS=diffuse_radiation_model=perez

# Optional: Zusätzliche API-Parameter je Dachfläche
# PVNODE_0_EXTRA_PARAMS=snow_slide_coefficient=0.5
# PVNODE_1_EXTRA_PARAMS=snow_slide_coefficient=0.3
```

## Zugangsdaten

### `PVNODE_APIKEY`<span class="badge required"></span>

API-Key des pvnode-Kontos. Er wird zuvor bei pvnode erstellt: \
https://pvnode.com/settings/api-keys

Der Collector schickt ihn bei jeder Abfrage mit, unter beiden API-Varianten. Ohne gültigen Key weist pvnode die Abfrage ab, und im Dashboard bleibt die Prognosekurve leer.

```properties title="Beispiel"
PVNODE_APIKEY=pvn_my-secret-api-key
```

> **HELIOS**
>
>
> HELIOS fragt den API-Key unter _Konfiguration → Datenquellen → Forecast-Collector_ ab.
>

### `PVNODE_SITE_ID`<span class="badge optional"></span>

ID der Site im pvnode-Konto. Ist sie gesetzt, spricht der Collector die API **v2** an. Verfügbar ab Version `0.10.0` des Forecast-Collectors.

Die Site trägt den Standort und alle PV-Strings. Deshalb sind mit einer Site-ID sämtliche Variablen für Standort und Dachflächen wirkungslos, ebenso `PVNODE_EXTRA_PARAMS`. Ohne die Variable bleibt es bei der API v1, die pvnode Ende 2026 abschaltet.

```properties title="Beispiel"
PVNODE_SITE_ID=site_xxxxxxxxxxxxxxxxxxxxxx
```

> **HELIOS**
>
>
> HELIOS fragt die Site-ID unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht und fragt stattdessen nach Standort und Dachflächen.
>

### `PVNODE_PAID`<span class="badge optional"></span>

Tarif des pvnode-Kontos. Erlaubt sind `false` für den Tarif **Free**, `true` für **Light** und `nowcast` für **Plus**. Groß- und Kleinschreibung spielt keine Rolle, jeder andere Wert gilt als `false`. Standardwert ist `false`.

Der Collector erkennt den Tarif nicht selbst, er richtet seinen Abrufplan nach dem eingetragenen. Steht hier ein höherer Tarif als der tatsächlich abonnierte, fragt der Collector häufiger ab, als das Konto erlaubt. Die Folge sind Fehlermeldungen oder ein vorzeitig aufgebrauchtes Monatskontingent.

```properties title="Beispiel"
PVNODE_PAID=nowcast
```

> **HELIOS**
>
>
> HELIOS fragt den Tarif unter _Konfiguration → Datenquellen → Forecast-Collector_ ab, vorbelegt mit Free. Bei Free setzt HELIOS die Variable nicht, denn der Collector nimmt den kostenlosen Tarif ohnehin an.
>

Die Tarife unterscheiden sich in der Reichweite der Prognose:

- **Free (`false`)**: Vorhersage für den morgigen Tag
- **Light (`true`)**: Vorhersage für sieben Tage, stündlich aktualisiert
- **Plus (`nowcast`)**: Vorhersage für sieben Tage, tagsüber alle 10 Minuten aktualisiert, nachts stündlich

Wie viele Anfragen pro Monat ein Tarif umfasst, legt pvnode fest: [Preise und Tarife](https://pvnode.com/de#pricing).

## Abfrageintervall

Ein Abfrageintervall gibt es bei pvnode nicht zu konfigurieren. `FORECAST_INTERVAL` wird ignoriert, und HELIOS setzt die Variable bei pvnode gar nicht erst. Der Collector bestimmt die Abrufzeitpunkte selbst, nach den Update-Zeiten von pvnode und dem monatlichen Kontingent an Abfragen. Das Kontingent kommt aus dem Tarif, sofern nicht [`PVNODE_REQUEST_LIMIT`](#pvnode_request_limit) ein kleineres vorgibt.

Im Tarif Free ist das unter der API v2 ein Abruf pro Tag. Eine einzige Abfrage genügt dort, unabhängig von der Anzahl der PV-Strings.

Unter der API v1 richtet sich der Collector zusätzlich nach der Anzahl der Dachflächen und den zusätzlichen Parametern. Er fasst gleiche Parameter zusammen und deckt, wenn möglich, mit einer Abfrage zwei Dachflächen ab. Das Kontingent teilt sich dabei auf die Abfragen auf: Braucht eine Vorhersage zwei getrennte Abfragen, bleibt im Tarif Free nur jeder zweite Tag übrig.

### `PVNODE_REQUEST_LIMIT`<span class="badge optional"></span>

Selbst gesetztes Monatslimit für die Anzahl der Abfragen, als positive ganze Zahl. Ohne die Variable rechnet der Collector mit dem vollen Kontingent des Tarifs. Die Variable gilt für beide API-Varianten.

Nützlich ist das Limit, wenn dasselbe pvnode-Konto noch andere Anwendungen bedient, etwa evcc oder Home Assistant. Der Collector bestimmt seine Abrufzeitpunkte weiterhin selbst, legt dabei aber das kleinere Kontingent zugrunde und fragt entsprechend seltener ab. Ein Wert oberhalb des Tarifkontingents bleibt wirkungslos. Der Collector meldet ihn beim Start als Warnung im Log.

```properties title="Beispiel"
PVNODE_REQUEST_LIMIT=500
```

> **HELIOS**
>
>
> HELIOS fragt das Anfragelimit unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht.
>

## Nur bei API v1

Alles Weitere auf dieser Seite gilt nur ohne [`PVNODE_SITE_ID`](#pvnode_site_id), also für die klassische API v1. Mit einer Site liegen Standort und Dachflächen bei pvnode, der Collector holt sie dort ab.

> **v1 wird abgeschaltet**
>
>
> Neue Installationen starten gleich mit einer Site, denn pvnode schaltet die v1-API ab (siehe [Zwei API-Varianten](#zwei-api-varianten)).
>

## Standort

pvnode arbeitet mit einem monatlichen **Standort-Limit** (Site-Limit), das vom Tarif abhängt. Einen Standort speichert pvnode automatisch, sobald eine Abfrage mit Koordinaten eintrifft.

> **Vorsicht bei der Angabe der Koordinaten**
>
>
> pvnode speichert Standorte auf 5 Nachkommastellen genau. Bei jeder weiteren Abfrage müssen **exakt dieselben Koordinaten** kommen, damit pvnode sie dem bekannten Standort zuordnet.
>
> Geänderte Koordinaten, etwa wegen eines Tippfehlers, legen bei pvnode einen neuen Standort an. Im kostenlosen Tarif meldet pvnode dann `Site limit has been exceeded`.
>
> Die bereits verwendeten Standorte zeigt das [pvnode Studio](https://www.pvnode.com/studio) an (Klick auf die Karte oder _Standort auswählen_ → _Bereits verwendeten Standort auswählen_). Sie werden monatlich zurückgesetzt.
>

### `FORECAST_LATITUDE`<span class="badge optional"></span>

Breitengrad des Standorts der PV-Anlage, `-90` (Süd) bis `90` (Nord). Dezimaltrennzeichen ist der Punkt. Pflicht, solange keine [`PVNODE_SITE_ID`](#pvnode_site_id) gesetzt ist.

```properties title="Beispiel"
FORECAST_LATITUDE=50.12345
```

> **HELIOS**
>
>
> HELIOS fragt den Breitengrad unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Mit einer Site-ID entfällt die Frage, HELIOS setzt die Variable dann nicht.
>

### `FORECAST_LONGITUDE`<span class="badge optional"></span>

Längengrad des Standorts der PV-Anlage, `-180` (West) bis `180` (Ost). Dezimaltrennzeichen ist der Punkt. Pflicht, solange keine [`PVNODE_SITE_ID`](#pvnode_site_id) gesetzt ist.

```properties title="Beispiel"
FORECAST_LONGITUDE=6.12345
```

> **HELIOS**
>
>
> HELIOS fragt den Längengrad unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Mit einer Site-ID entfällt die Frage, HELIOS setzt die Variable dann nicht.
>

## Dachflächen

Neigung, Ausrichtung und Leistung gibt es zweimal: ohne Index als globalen Wert und mit Index je Dachfläche. Der indizierte Wert gewinnt, der globale springt für jede Dachfläche ein, die keinen eigenen hat. Bei einer einzelnen Dachfläche genügen deshalb die globalen Variablen.

### `FORECAST_CONFIGURATIONS`<span class="badge optional"></span>

Anzahl der Dachflächen. Standardwert ist `1`. Steht hier eine zu kleine Zahl, bleiben die Angaben der übrigen Dachflächen unbeachtet — `FORECAST_1_KWP` etwa wirkt erst ab `FORECAST_CONFIGURATIONS=2`.

pvnode nimmt bis zu zwei Dachflächen pro Abfrage entgegen. Der Collector fasst sie zusammen, sofern ihre zusätzlichen Parameter übereinstimmen. Sonst kostet jede Dachfläche eine eigene Abfrage aus dem Monatskontingent.

```properties title="Beispiel"
FORECAST_CONFIGURATIONS=2
```

> **HELIOS**
>
>
> HELIOS fragt die Anzahl der Dachflächen unter _Konfiguration → Datenquellen → Forecast-Collector_ ab, höchstens vier. Bei einer einzelnen Dachfläche lässt HELIOS die Variable weg. Der Collector selbst kennt keine Obergrenze.
>

### `FORECAST_DECLINATION`<span class="badge optional"></span>

Neigung des Dachs in Grad, `0` (waagerecht) bis `90` (senkrecht). Der Wert gilt für jede Dachfläche, die keine eigene [`FORECAST_X_DECLINATION`](#forecast_x_declination) hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

```properties title="Beispiel"
FORECAST_DECLINATION=30
```

> **HELIOS**
>
>
> HELIOS fragt die Neigung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bei mehreren Dachflächen setzt HELIOS stattdessen die indizierten Varianten.
>

### `FORECAST_AZIMUTH`<span class="badge optional"></span>

Ausrichtung des Dachs in Grad, von Norden gezählt: `0` ist Nord, `90` Ost, `180` Süd, `270` West. Der Wert gilt für jede Dachfläche, die keine eigene [`FORECAST_X_AZIMUTH`](#forecast_x_azimuth) hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

Forecast.Solar zählt anders, nämlich von Süden (`-180` bis `180`). Wer von dort kommt, muss die Ausrichtung umrechnen: Aus `0` (Süd) wird `180`. Bei Solcast wiederum spielt die Ausrichtung im Collector keine Rolle, sie steht in der Anlagenkonfiguration im Solcast-Portal.

```properties title="Beispiel"
FORECAST_AZIMUTH=207
```

> **HELIOS**
>
>
> HELIOS fragt die Ausrichtung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab, in der Zählweise von pvnode. Den Wert für Forecast.Solar hält HELIOS getrennt davon, ein Anbieterwechsel rechnet also nicht um.
>

### `FORECAST_KWP`<span class="badge optional"></span>

Installierte Modulleistung in Kilowatt-Peak (kWp). Der Wert gilt für jede Dachfläche, die keine eigene [`FORECAST_X_KWP`](#forecast_x_kwp) hat. Bei einer einzelnen Dachfläche ist er damit Pflicht.

```properties title="Beispiel"
FORECAST_KWP=9.24
```

> **HELIOS**
>
>
> HELIOS fragt die Leistung unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bei mehreren Dachflächen setzt HELIOS stattdessen die indizierten Varianten.
>

### `FORECAST_X_DECLINATION`<span class="badge optional"></span>

Neigung der Dachfläche `X`, gezählt ab `0`. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert aus [`FORECAST_DECLINATION`](#forecast_declination).

```properties title="Beispiel"
FORECAST_0_DECLINATION=27
FORECAST_1_DECLINATION=30
```

> **HELIOS**
>
>
> HELIOS setzt die indizierten Variablen, sobald mehr als eine Dachfläche eingetragen ist.
>

### `FORECAST_X_AZIMUTH`<span class="badge optional"></span>

Ausrichtung der Dachfläche `X`, gezählt ab `0`. Wertebereich wie bei [`FORECAST_AZIMUTH`](#forecast_azimuth), also von Norden gezählt. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert.

```properties title="Beispiel"
FORECAST_0_AZIMUTH=180
FORECAST_1_AZIMUTH=270
```

> **HELIOS**
>
>
> HELIOS setzt die indizierten Variablen, sobald mehr als eine Dachfläche eingetragen ist.
>

### `FORECAST_X_KWP`<span class="badge optional"></span>

Modulleistung der Dachfläche `X` in kWp, gezählt ab `0`. Pflicht, sobald mehr als eine Dachfläche konfiguriert ist. Fehlt sie, greift der globale Wert aus [`FORECAST_KWP`](#forecast_kwp) — beide Dachflächen bekämen dann dieselbe Leistung.

```properties title="Beispiel"
FORECAST_0_KWP=5.5
FORECAST_1_KWP=3.9
```

> **HELIOS**
>
>
> HELIOS setzt die indizierten Variablen, sobald mehr als eine Dachfläche eingetragen ist.
>

### `PVNODE_EXTRA_PARAMS`<span class="badge optional"></span>

Zusätzliche Query-Parameter für die pvnode-API, im Format `key1=value1&key2=value2`, ohne führendes `?` oder `&`. Der Collector hängt sie an jede Abfrage an. Welche Parameter es gibt, steht in der [pvnode-Dokumentation](https://www.pvnode.com/docs/de/forecast#optional-parameters).

Die Parameter gelten für die gesamte Abfrage, nicht für eine einzelne Dachfläche. Deshalb landen zwei Dachflächen nur dann in einer gemeinsamen Abfrage, wenn ihre Parameter übereinstimmen.

```properties title="Beispiel"
PVNODE_EXTRA_PARAMS=diffuse_radiation_model=perez&snow_slide_coefficient=0.5
```

> **HELIOS**
>
>
> HELIOS fragt die Parameter unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt das Feld leer, setzt HELIOS die Variable nicht. Mit einer Site-ID entfällt die Frage.
>

### `PVNODE_X_EXTRA_PARAMS`<span class="badge optional"></span>

Zusätzliche Query-Parameter für die Dachfläche `X`, gezählt ab `0`. Sie ersetzen [`PVNODE_EXTRA_PARAMS`](#pvnode_extra_params) für diese Dachfläche, sie ergänzen es nicht.

Nötig ist das nur, wenn sich die Dachflächen in den Parametern unterscheiden — was sie zugleich daran hindert, sich eine Abfrage zu teilen.

```properties title="Beispiel"
PVNODE_0_EXTRA_PARAMS=diffuse_radiation_model=perez
PVNODE_1_EXTRA_PARAMS=snow_slide_coefficient=0.3
```

> **HELIOS**
>
>
> HELIOS fragt die Parameter je Dachfläche unter _Konfiguration → Datenquellen → Forecast-Collector_ ab. Bleibt ein Feld leer, setzt HELIOS die Variable nicht.
>