Energie Schnee - Anleitung für Agenten und Chatbots

Diese Seite rechnet Photovoltaikanlagen. Über die Schnittstelle bekommst du zu einer Adresse alle Dachflächen des Anwesens mit Modulmenge, Leistung, Ausrichtung, Neigung und Verschattung.

Basisadresse: https://energie.schnee.co.at/api/v1
Ausführliche Doku: https://energie.schnee.co.at/api/v1/doku
Maschinenlesbar: https://energie.schnee.co.at/api/v1/openapi.json
Format: JSON, UTF-8
Abgedeckt: Österreich, Deutschland, Schweiz.

Die Schnittstelle rechnet nicht nur, sie legt ein Projekt an. Je Adresse und Konto gibt es genau eines. Ein zweites wird mit 409 abgewiesen, und das ist kein Fehler, sondern die Regel.

This file is German. The API returns German texts but stable English-style error codes in snake_case. Field names are ASCII without umlauts.

Rate nichts, ruf es ab

Alles hier ist ohne Zugang abrufbar. Wenn du unsicher bist, hol dir die Wahrheit, statt sie zu erfinden:

curl -s https://energie.schnee.co.at/AGENT.md            # diese Anleitung
curl -s https://energie.schnee.co.at/api/v1/lastprofile  # gültige Lastprofile
curl -s https://energie.schnee.co.at/api/v1/openapi.json # alle Endpunkte samt Feldnamen

Wenn dein Werkzeug an einer dieser Adressen scheitert, etwa mit 403 aus deiner eigenen Umgebung, nimm das andere Werkzeug. Dieselbe Anleitung steht als gewöhnliche Webseite unter https://energie.schnee.co.at/api/v1/anleitung, und die kommt auch durch, wenn eine Sandbox keine Dateien laden darf. Gib nicht auf, bevor du beide Wege probiert hast.

Erfinde keine Feldnamen, keine Parameter und keine Adressen. Was du brauchst, steht in diesen drei Abrufen. Es gibt neben den hier genannten nur noch zwei Endpunkte, /api/v1/schluessel und /api/v1/nutzung, und die brauchen eine angemeldete Sitzung im Browser, keinen Schlüssel.

Schritt 0: Zugang

Ohne Schlüssel geht nur Lesen. So kommt dein Benutzer an einen:

Konto anlegen. Der kostenlose Testzugang liegt unter https://energie.schnee.co.at/testpool/join/7-U0t3gScWuIxuGgveL9WA. Auf der Startseite heißt der Knopf Kostenlos testen. Der Betreiber schaltet frei. Du kannst das nicht für den Benutzer erledigen, sag es ihm.
Anmelden unter https://energie.schnee.co.at/login.
Modul Schnittstelle öffnen: https://energie.schnee.co.at/module/api. Dort auf Schlüssel anlegen, einen Namen vergeben. Der Schlüssel erscheint genau einmal und beginnt mit es_. Er lässt sich danach nicht wieder anzeigen, nur widerrufen.
Der Benutzer gibt dir diesen Schlüssel. Sag ihm dazu, dass er ihn nach dem Gespräch im selben Modul widerrufen soll, wenn der Chatverlauf irgendwo gespeichert wird.

Erst wenn du einen Schlüssel hast, geht es weiter. Behaupte nie, du hättest etwas gerechnet, wenn kein Schlüssel vorlag.

Was du vom Benutzer brauchst

Vier Angaben:

einen Projektnamen, unter dem das Projekt angelegt wird
die Adresse mit Straße, Hausnummer, Postleitzahl und Ort
den Jahresverbrauch in Kilowattstunden
das Standardlastprofil aus der Tabelle unten, im Zweifel H0

Frage nach dem, was fehlt. Rate nichts, besonders keinen Verbrauch.

Der kurze Weg, wenn du nur Adressen abrufen kannst

Viele Chatbots können ausschließlich eine Adresse aufrufen: kein POST, keine eigene Kopfzeile. Dafür gibt es einen einzigen Aufruf, der alles erledigt.

https://energie.schnee.co.at/api/v1/analyse?schluessel=es_...&name=Testprojekt&adresse=Mösl%205,%204841%20Ungenach&jahresverbrauch_kwh=6000&lastprofil=H0

Beim ersten Aufruf legt er das Projekt an und startet die Analyse, Antwort 202 mit zustand: läuft. Ruf dieselbe Adresse nach der Zahl von Sekunden aus dem Feld erneut_in_s noch einmal auf, dann steht das Ergebnis darin, mit zustand: fertig. Es wird kein zweites Projekt angelegt, egal wie oft du aufrufst.

Auf diesem Weg zählt jede Abfrage gegen die Ratengrenze von 40 Aufrufen je Stunde, auch das Nachfragen. Frage deshalb nicht schneller als alle zehn Sekunden.

Dieser Weg ist die Notlösung für Werkzeuge, die nicht anders können. Der Schlüssel steht dabei in der Adresse und damit im Zugriffsprotokoll jedes Rechners dazwischen. Prüfe zuerst, ob du eine Kopfzeile setzen kannst, viele Werkzeuge können mehr als sie zunächst annehmen. Wenn ja, nimm den regulären Weg darunter.

Der reguläre Weg

Der Lauf dauert zehn bis neunzig Sekunden, deshalb zwei Schritte.

Schritt 1: anlegen

curl -X POST https://energie.schnee.co.at/api/v1/projekte \
  -H "X-API-Key: es_..." -H "Content-Type: application/json" \
  -d '{"name":"Haus Muster","adresse":"Musterweg 1, 4840 Vöcklabruck",
       "jahresverbrauch_kwh":4500,"lastprofil":"H0"}'

Antwort 202 mit projekt_id und analyse_url. Die Kopfzeile Content-Type: application/json ist Pflicht, sonst kommt 415.

Schritt 2: abholen

GET auf die analyse_url aus Schritt 1, bis zustand auf fertig steht. Solange kommt 202 mit schritt, fertig, gesamt und wartet.

curl -s https://energie.schnee.co.at/api/v1/projekte/42/dachanalyse \
  -H "X-API-Key: es_..."

Wie lange du zwischen zwei Abfragen wartest, steht in der Antwort, im Feld erneut_in_s und in der Kopfzeile Retry-After. Halte dich daran.

wartet: true heißt: die Rechnung hat noch gar nicht begonnen. Es rechnen gerade zwei andere Analysen, deine ist vorgemerkt. Jede Abfrage ist zugleich der Versuch, den frei gewordenen Platz zu bekommen. Diese Wartezeit zählt nicht gegen die Frist im nächsten Absatz.

Höre 150 Sekunden nach dem Beginn der Rechnung auf zu fragen, also ab dem ersten Mal, dass wartet auf false steht. Ein normaler Lauf braucht zehn bis neunzig Sekunden. Dauert es länger, hängt er. Dann stößt du ihn genau einmal neu an und wartest wieder bis 150 Sekunden. Kommt danach immer noch nichts, sag dem Benutzer, dass die Analyse nicht durchläuft, und nenne ihm die Projektkennung. Frage nicht endlos weiter.

Sag dem Benutzer beim Warten einmal, dass es bis zu anderthalb Minuten dauert. Er hält das für einen Hänger, wenn du schweigst.

Die fertige Antwort enthält flaechen[], zusammenfassung, wirtschaftlichkeit und quellen.

Wenn der Lauf scheitert: Ein zweites Projekt an derselben Adresse geht nicht, das Projekt steht ja schon. Stoße den Lauf stattdessen erneut an, mit POST auf dieselbe analyse_url, die du zum Abholen verwendest:

curl -X POST https://energie.schnee.co.at/api/v1/projekte/42/dachanalyse \
  -H "X-API-Key: es_..."

Alle eigenen Projekte liefert GET /api/v1/projekte, jeweils mit analyse_url und dem Link in die Wirtschaftlichkeitsrechnung. Die Liste ist seitenweise, die nächste Seite steht im Feld weiter oder ist null.

Was du dem Benutzer sagst

Die empfohlene Anlage steht in zusammenfassung.auslegung_kwp und zusammenfassung.auslegung_module. Sie folgt dem gesendeten Jahresverbrauch.
Das Dachpotenzial insgesamt steht in zusammenfassung.leistung_moeglich_kwp. Das ist, was geometrisch daraufpasst, nicht was sinnvoll ist. Dasselbe Feld gibt es auch je Fläche, achte auf den Pfad.
Welche Flächen sinnvoll sind, erkennst du an flaechen[].empfohlen.
Gib immer den Link aus wirtschaftlichkeit.url. Dort rechnet der Benutzer seine Wirtschaftlichkeit fertig, mit Speicher, Auto und Tarifen. Der Link verlangt die Anmeldung des Mandanten, dem der Schlüssel gehört.
Verschattung: flaechen[].verschattung.verlust_mittel_pct ist der mittlere Verlust über fünf Messpunkte, Einzelwerte stehen in flaechen[].verschattung.messpunkte. Das ganze Feld verschattung kann null sein, wenn keine Messpunkte vorliegen. Erfinde dann keine Zahl, sag, dass keine Verschattungsdaten vorliegen.
Ziehe die Verschattung nicht noch einmal ab. ertrag_kwh_pro_kwp enthält sie bereits, das Feld ertrag_enthaelt_verschattung sagt es dir.
Zwei Flächenangaben, nicht verwechseln: grundflaeche_m2 ist die Fläche in der Draufsicht, dachflaeche_m2 die geneigte, also die echte Dachfläche.

Standardlastprofile

Kennung	Bezeichnung
`H0`	Haushalt (Vorgabe)
`L0`	Landwirtschaft allgemein
`L1`	Landwirtschaft mit Milchwirtschaft
`L2`	Sonstige Landwirtschaft
`G0`	Gewerbe allgemein
`G1`	Werktags 8-18 Uhr
`G2`	Abends mit Ladenbeleuchtung
`G3`	Durchlaufend
`G4`	Laden/Friseur
`G5`	Bäckerei mit Backstube
`G6`	Wochenendbetrieb

Immer aktuell unter https://energie.schnee.co.at/api/v1/lastprofile.

Das Profil wird geprüft und zum Projekt gespeichert. Gerechnet wird damit heute in der Anwendung. Für die Flächenauswahl der Schnittstelle zählt vorerst allein der Jahresverbrauch.

Fehler

Jeder Fehler trägt fehler.code zum Verzweigen, fehler.meldung für den Menschen und fehler.tu mit dem nächsten Schritt. Das gilt auch für 404, 405, 415, 429 und 500.

Status	Code	Was du tust
401	`schluessel_fehlt`, `schluessel_ungueltig`	Den Benutzer bitten, unter https://energie.schnee.co.at/module/api einen Schlüssel anzulegen.
400	`lastprofil_unbekannt`	Eine Kennung aus `fehler.erlaubt` verwenden.
400	`verbrauch_fehlt`	Nach dem Jahresverbrauch fragen. Zahl größer null, höchstens hundert Millionen.
400	`adresse_zu_lang`	Nur Straße, Hausnummer, Postleitzahl und Ort senden, höchstens 200 Zeichen.
404	`adresse_nicht_gefunden`	Nach vollständiger Adresse fragen. Nur AT, DE, CH.
404	`adresse_nicht_eindeutig`	Es wurde nichts gefunden, das zu Ort und Postleitzahl passt. Die Fundstellen stehen in `fehler.gefunden`. Nimm keine davon auf gut Glück, frage den Benutzer, welche gemeint ist, und sende deren Schreibweise erneut.
404	`analyse_fehlt`	Das Ergebnis ist verfallen, Ergebnisse werden einen Tag vorgehalten. Lege kein neues Projekt an, das scheitert an der Dublettenregel. Stoße stattdessen `POST` auf die `analyse_url` aus `fehler.analyse_url` an.
409	`projekt_besteht_bereits`	Kein zweites Projekt anlegen. An einer Adresse ist je Konto nur ein Projekt möglich. Nimm `bestehendes_projekt.analyse_url` für die Zahlen und gib `bestehendes_projekt.url` als Link aus.
415	`inhaltstyp_falsch`	Kopfzeile `Content-Type: application/json` setzen.
429	`ratengrenze`	Warten, die Dauer steht in `fehler.tu` und in der Kopfzeile `Retry-After`. Grenzen siehe unten.
503	`dienst_ueberlastet`, `dienst_nicht_erreichbar`	Der Geodienst antwortet gerade nicht. Die Wartezeit steht in `Retry-After`, danach `POST` auf die `analyse_url`.
503	`analyse_abgebrochen`	Der Lauf wurde unterbrochen, etwa durch einen Neustart. Einmal neu anstoßen mit `POST` auf die `analyse_url`.
422	`kein_dach`	An dieser Stelle gibt es kein auswertbares Dach. Adresse prüfen.
500	`analyse_fehlgeschlagen`, `interner_fehler`	Erneut anstoßen mit `POST` auf die `analyse_url`. Bleibt es dabei, dem Benutzer die Projektkennung nennen.

Ratengrenzen

Gezählt wird je Konto, nicht je Schlüssel. Mehrere Schlüssel bringen also nichts.

Was	Grenze je Stunde
Projekte anlegen und Analysen neu anstoßen	20
Stand abfragen, Projekte auflisten	900
Der kurze Weg `/api/v1/analyse`, Anlegen und Abfragen zusammen	40

Grenzen

Ergebnisse sind eine Vorplanung aus Fernerkundungsdaten, keine Ausführungsplanung. Sag das dem Benutzer.
Die Zahlen gelten für den gerechneten Standort und sind nicht übertragbar.
Ergebnisse werden einen Tag lang vorgehalten. Danach liefert die Abfrage 404 analyse_fehlt, und der Weg zurück ist ein neuer Anstoß per POST, nicht ein neues Projekt.
Es rechnen höchstens zwei Analysen gleichzeitig, für alle Nutzer zusammen. Deshalb gibt es den Wartezustand.
Bei Weitergabe der Daten ist die Namensnennung mitzuführen, sie steht in jeder Antwort im Feld quellen.
Die Adresse wird zur Geokodierung an Nominatim des OpenStreetMap-Vereins gesendet und im angelegten Projekt gespeichert.
Die vollständige Wirtschaftlichkeitsrechnung über die Schnittstelle ist vorbereitet, aber noch nicht verfügbar. wirtschaftlichkeit.verfuegbar zeigt an, ob es sie gibt.

Betreiber: Ing. Martin Schneeweiss B.Eng., Mösl 5, 4841 Ungenach, martin@schnee.co.at