# 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: - Maschinenlesbar: - 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: ```bash 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 , 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: 1. **Konto anlegen.** Der kostenlose Testzugang liegt unter . 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. 2. **Anmelden** unter . 3. **Modul Schnittstelle öffnen**: . 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** ```bash 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`. ```bash 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: ```bash 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 . 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 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