Wie Sie die Zahlen der API lesen, wie aktuell sie sind und wie oft eine Abfrage sinnvoll ist.
Einheiten
| Größe | Einheit | Typ |
|---|---|---|
| Leistung | W | Ganzzahl |
| Energie | Wh | Ganzzahl, immer ≥ 0 |
| Ladezustand | % | Zahl, 0–100 |
Vorzeichen
Netz- und Batterieleistung haben ein Vorzeichen:
| Feld | Positiv | Negativ |
|---|---|---|
grid_power_w |
Netzbezug | Netzeinspeisung |
battery_power_w |
Batterie lädt | Batterie entlädt |
Energiewerte sind dagegen nie negativ: Die Richtung steckt im Feldnamen (imported / exported, charged / discharged).
Zeitstempel
- Zeitstempel von Telemetrie, Konnektivität und Alarmen sind ISO 8601 in UTC (
2026-10-13T12:21:00Z). - Energiefenster (
period_start,period_end,timestamp_start,timestamp_end) sind ISO 8601 in der Zeitzone der Anlage, mit deren Offset (2026-10-13T00:00:00+02:00). - Der Ladezustand gilt pro Gateway, nie als Anlagenmittelwert.
Wie oft die Daten aktualisiert werden
| Daten | Entstehung | Praktische Folge |
|---|---|---|
| Leistung | ein Messwert pro Gateway alle 60 s | häufigere Abfragen liefern denselben Messwert |
| Online-Status | Daten in den letzten 5 Minuten empfangen | eine Anlage wird 5 Minuten nach dem letzten Messwert offline |
| Energie | 15-Minuten-Zähler | die Tagessummen laufen der Echtzeit um etwa 15 Minuten hinterher |
Die null-Regel bei telemetry/latest
telemetry/latest liefert nur Messwerte der letzten 5 Minuten. Hat die Anlage in dieser Zeit keine Daten gesendet, lautet die Response trotzdem 200, mit "timestamp": null und "measurements": null: Ein alter Wert wird nie geliefert. null bedeutet also „keine aktuellen Daten“, nicht „null Watt“; seit wann die Anlage schweigt, zeigt last_seen_at in der Konnektivität.
Innerhalb von measurements sind pv_power_w und load_power_w bei Anlagen, die diese Größen nicht messen, 0; null sind sie nur in den Messpunkten von telemetry/series. Behandeln Sie null bei Leistung, Ladezustand und Energie immer als möglichen Wert.
Empfohlenes Polling
Schema für eine Flotte bis 100 Anlagen, also eine Bulk-Seite:
| Aufruf | Intervall | Requests pro Tag |
|---|---|---|
GET /v1/telemetry/latest |
60 s | 1 440 |
GET /v1/connectivity |
5 min | 288 |
GET /v1/energy/totals?period=day |
15 min | 96 |
| Summe | ≈ 1 800 |
- Kürzere Intervalle liefern keine aktuelleren Daten, sondern dieselben Messwerte.
- Leistungsreihen, Energiereihen und Alarme rufen Sie pro Anlage nur bei Bedarf ab.
- Jede weitere Bulk-Seite vervielfacht die Requests: Ab mehr als 100 Anlagen überschreitet dieses Schema das Tageslimit (siehe „Limits, Fehler und Support“). Verlängern Sie dann die Intervalle oder fragen Sie nach einer gesonderten Vereinbarung.