Dachflächen und Potenzial über eine Schnittstelle

Steckbrief

Der kurze Weg für Chatbots

Viele Chatbots können ausschließlich eine Adresse aufrufen, also weder POST senden noch eine eigene Kopfzeile setzen. Für sie erledigt ein einziger Aufruf alles:

https://energie.schnee.co.at/api/v1/analyse
    ?schluessel=es_...
    &name=Testprojekt
    &adresse=Musterweg 1, 4840 Musterort
    &jahresverbrauch_kwh=6000
    &lastprofil=H0

Der erste Aufruf legt das Projekt an und startet die Analyse, Antwort 202 mit zustand: läuft. Derselbe Aufruf nach der Zahl von Sekunden aus dem Feld erneut_in_s liefert das Ergebnis mit zustand: fertig. Auf diesem Weg zählt jede Abfrage gegen die Grenze von 40 Aufrufen je Stunde. Es wird kein zweites Projekt angelegt, egal wie oft aufgerufen wird. Der Schlüssel steht dabei in der Adresse und damit im Zugriffs­protokoll jedes Rechners dazwischen. Wer Kopfzeilen setzen kann, nimmt den Weg darunter.

Der reguläre Ablauf in zwei Schritten

Zuerst wird ein Projekt angelegt. Das startet die Analyse und antwortet sofort. Danach wird der Stand abgefragt, bis er auf fertig steht. Wie lange zwischen zwei Abfragen zu warten ist, steht in der Antwort selbst, im Feld erneut_in_s und in der Kopfzeile Retry-After.

1. Projekt anlegen

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

Antwort 202:

{
  "projekt_id": 42,
  "name": "Beispielhof",
  "zustand": "läuft",
  "analyse_url": "https://energie.schnee.co.at/api/v1/projekte/42/dachanalyse",
  "hinweis": "Die Dachanalyse läuft. Frage \"analyse_url\" ab, bis \"zustand\" auf \"fertig\" steht."
}

2. Ergebnis abholen

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

Solange gerechnet wird, kommt 202 mit Fortschritt. Am Ende 200 mit allen Flächen:

Scheitert der Lauf, weil der Geodienst nicht antwortet, wird er mit POST auf dieselbe Adresse erneut angestoßen. Ein zweites Projekt an derselben Adresse ist ja nicht möglich, das bestehende bleibt.

{
  "projekt_id": 42,
  "jahresverbrauch_kwh": 4500,
  "lastprofil": "H0",
  "flaechen": [
    {
      "id": 1,
      "name": "Dachfläche 1",
      "gebaeude": 0,
      "grundflaeche_m2": 73.3,
      "dachflaeche_m2": 89.5,
      "neigung_grad": 35.0,
      "azimut_grad": -38.5,
      "firsthoehe_m": 7.63,
      "module_moeglich": 18,
      "leistung_moeglich_kwp": 7.2,
      "module_empfohlen": 12,
      "leistung_empfohlen_kwp": 4.8,
      "ertrag_kwh_pro_kwp": 1142,
      "ertrag_enthaelt_verschattung": true,
      "empfohlen": true,
      "bild_url": "https://energie.schnee.co.at/api/v1/projekte/42/bilder/flaeche/3",
      "verschattung": {
        "verfahren": "5-Punkt",
        "verlust_mittel_pct": 3.4,
        "messpunkte": [
          {"punkt": "center", "lat": 48.05986, "lon": 13.60314, "verlust_pct": 2.9}
        ]
      },
      "umriss": {"type": "Polygon", "coordinates": [[[13.6031, 48.0598]]]}
    }
  ],
  "zusammenfassung": {
    "flaechen_anzahl": 20,
    "grundflaeche_m2": 1491,
    "dachflaeche_m2": 1830.4,
    "module_moeglich": 333,
    "leistung_moeglich_kwp": 133.2,
    "empfehlung_kwp": 10.3,
    "auslegung_kwp": 10.4,
    "spez_ertrag_kwh_kwp": 1084
  },
  "wirtschaftlichkeit": {
    "verfuegbar": false,
    "url": "https://energie.schnee.co.at/module/photovoltaik?project_id=42",
    "anmeldung_noetig": true
  },
  "medien": {
    "uebersicht_url": "https://energie.schnee.co.at/api/v1/projekte/42/medien",
    "bild_uebersicht_url": "https://energie.schnee.co.at/api/v1/projekte/42/bilder/uebersicht"
  }
}

Die Felder einer Dachfläche

Bilder und 3D-Modell

Zu jedem gerechneten Projekt zeichnet der Server das Luftbild der Dachflächen mit den eingezeichneten Modulraster, samt Nordpfeil und Maßstab. Gezeichnet ist, was geometrisch daraufpasst (module_moeglich), nicht die kleinere Auslegung nach Jahresverbrauch. Was zu einem Projekt vorliegt, sagt GET /api/v1/projekte/<id>/medien; in der Antwort der Dachanalyse steht derselbe Weg unter medien.uebersicht_url.

Bilder kommen als SVG, mit ?format=png als PNG. Die Bildbreite steuert ?breite= zwischen 200 und 2000 Pixeln. Für Medien gilt eine eigene Ratengrenze von 120 Abrufen je Stunde und Konto.

Orthofoto und 3D-Modell entstehen beim Speichern in der Anwendung. Zu einem Projekt, das nur über die Schnittstelle gerechnet wurde, gibt es keines, und die Abfrage antwortet mit 404 samt Begründung. Die Belegungsbilder gibt es immer.

Standardlastprofile

Das Lastprofil wird geprüft und zum Projekt gespeichert. Gerechnet wird damit heute in der Anwendung, nicht in der Schnittstelle. Für die Flächenauswahl zählt vorerst allein der Jahresverbrauch. Abrufbar auch unter /api/v1/lastprofile.

Fehler und was zu tun ist

Jede Fehlerantwort trägt einen unveränderlichen code zum Verzweigen, eine meldung für den Menschen davor und unter tu den nächsten Schritt.

Grenzen und Pflichten

• Ein Projekt je Adresse und Mandant. Legt ein anderer Mandant an derselben Adresse an, ist das zulässig.
• Die Wirtschaftlichkeitsrechnung läuft vorerst in der Anwendung. Die Antwort trägt den Link dorthin unter wirtschaftlichkeit.url, er verlangt eine Anmeldung des Mandanten. Ein späterer Endpunkt für die vollständige Rechnung ist vorgesehen, das Feld wirtschaftlichkeit.verfuegbar zeigt an, ob es ihn schon gibt.
• Ergebnisse werden einen Tag lang vorgehalten. Danach ist das Projekt weiter da, die Analyse muss mit POST auf die analyse_url neu angestoßen werden. Ein zweites Projekt anzulegen scheitert an der Dublettenregel.
• Es rechnen höchstens zwei Analysen gleichzeitig, für alle Nutzer zusammen. Wer wartet, erkennt das an wartet: true.
• Die Adresse wird zur Geokodierung an Nominatim des OpenStreetMap-Vereins gesendet und im angelegten Projekt gespeichert.
• Die Schnittstelle ist für Server und Agenten gedacht, nicht für Klienten im Browser. Es werden bewusst keine CORS-Kopfzeilen gesendet, ein Schlüssel gehört nicht in eine Webseite.
• Die Daten stammen aus amtlichen Quellen. Bei Weitergabe ist die Namensnennung mitzuführen, sie steht in jeder Antwort im Feld quellen.
• Ergebnisse sind eine Vorplanung aus Fernerkundungsdaten, keine Ausführungsplanung. Vor dem Bau gehört jedes Dach besichtigt.

Schlüssel bekommen

Nach der Anmeldung im Modul Schnittstelle unter https://energie.schnee.co.at/module/api lässt sich ein Schlüssel anlegen. Er wird genau einmal angezeigt und danach nur noch als Abdruck gespeichert. Ein verlorener Schlüssel lässt sich nicht wiederherstellen, wohl aber widerrufen und neu anlegen. Gezählt wird je Konto, mehrere Schlüssel erhöhen die Grenzen also nicht.

Ein Konto allein für die Schnittstelle gibt es unter https://energie.schnee.co.at/api-testzugang. Von den Modulen der Anwendung schaltet es allein die Schnittstelle frei, erlaubt eine Adresse, also ein Projekt, und läuft nach dreißig Tagen ab. Gezählt wird jedes Projekt des Kontos, auch ein in der Anwendung selbst angelegtes. Ist die Adresse verbraucht, antwortet das Anlegen mit 403 und testkontingent_erschoepft. Wer die ganze Anwendung testen will, nimmt den Testzugang auf der Startseite, dort schaltet der Betreiber von Hand frei.