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 daneben Endpunkte, die du nicht verwenden kannst, weil sie eine angemeldete Sitzung im Browser verlangen und keinen Schlüssel: /api/v1/schluessel samt Widerruf, /api/v1/nutzung und /api/v1/meine-projekte. Sie stehen deshalb auch nicht in openapi.json.

Schritt 0: Zugang

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

1. Konto anlegen. Der Testzugang für die Schnittstelle liegt unter https://energie.schnee.co.at/api-testzugang. Er schaltet von den Modulen der Anwendung allein die Schnittstelle frei und erlaubt eine Adresse, also ein Projekt. Gezählt wird jedes Projekt des Kontos, auch eines, das der Benutzer in der Anwendung selbst anlegt. Das Konto entsteht sofort, sobald der Benutzer die Bestätigungsmail angeklickt hat, und läuft nach dreißig Tagen ab. Du kannst das nicht für ihn erledigen, sag es ihm. Wer die ganze Anwendung testen will, nimmt auf der Startseite den Knopf Kostenlos testen, dort schaltet der Betreiber von Hand frei.
2. Anmelden unter https://energie.schnee.co.at/login.
3. 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.
4. 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:

1. einen Projektnamen, unter dem das Projekt angelegt wird
2. die Adresse mit Straße, Hausnummer, Postleitzahl und Ort
3. den Jahresverbrauch in Kilowattstunden
4. 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, medien 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.

Bilder und 3D-Modell

Zahlen allein überzeugen niemanden. Zu jedem gerechneten Projekt gibt es Bilder, und der Weg dorthin steht in der Antwort selbst: medien.uebersicht_url sagt, was vorliegt, und je Fläche steht bild_url daneben.

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

• Belegungsbild je Fläche: /api/v1/projekte/42/bilder/flaeche/3. Das Luftbild der Fläche mit dem eingezeichneten Modulraster, dazu Nordpfeil und Maßstab. Gezeichnet ist, was geometrisch daraufpasst, also module_moeglich, nicht die kleinere Auslegung module_empfohlen. Die Nummer ist dieselbe wie das Feld id der Fläche in der Dachanalyse.
• Übersichtsbild: /api/v1/projekte/42/bilder/uebersicht, alle belegten Flächen in einem Bild.
• Beide kommen als SVG. Kann dein Werkzeug kein SVG anzeigen, hänge ?format=png an. Die Bildbreite steuert ?breite= zwischen 200 und 2000 Pixeln.
• Orthofoto: /api/v1/projekte/42/orthofoto, das gespeicherte Luftbild des Anwesens.
• 3D-Modell: /api/v1/projekte/42/modell, eine GLB-Datei zum Herunterladen.

Orthofoto und 3D-Modell entstehen erst, wenn das Projekt in der Anwendung geöffnet und gespeichert wurde. Zu einem Projekt, das nur über die Schnittstelle gerechnet wurde, gibt es keines, und die Abfrage antwortet mit 404 und dem Grund. Erfinde dann keine Erklärung, sondern sag dem Benutzer, dass er das Projekt einmal in der Anwendung öffnen muss.

Belegungsbilder gibt es zu jeder gerechneten Fläche mit Modulen, aber nicht in jeder Lage: Ohne gespeicherte Dachanalyse kommt 404 analyse_fehlt, ohne eine einzige belegte Fläche 404 keine_belegten_flaechen. Beides sagt dir, was zu tun ist. Rechne nicht auf Verdacht neu.

Für Bilder gilt eine eigene Ratengrenze von 120 Abrufen je Stunde und Konto.

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

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.

Ratengrenzen

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

Daneben gilt eine anwendungsweite Grenze je Adresse, nicht je Konto: 500 Aufrufe je Stunde und 5000 je Tag. Wer aus einer einzigen Adresse arbeitet, erreicht die 900 Statusabfragen oben also nicht.

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, office@schnee.co.at