Geo-Service

AnmeldungJede Anfrage braucht einen Schlüssel

Alle Endpunkte verlangen einen API-Schlüssel. Er wird als Kopfzeile X-API-Key mitgeschickt, nicht als Abfrageparameter, damit er nicht in Protokolldateien und Verlaufslisten landet. Einen Schlüssel bekommt man vom Betreiber. Er beginnt mit gs_ und ist danach unveränderlich.

Es gibt zwei Rechtestufen. lesen erlaubt alle abfragenden Endpunkte. verwalten erlaubt zusätzlich die steuernden Endpunkte, die den Zwischenspeicher des Dienstes anfassen. Welche Stufe ein Endpunkt verlangt, steht in jeder Tabelle rechts.

Erster AufrufHöhe eines Punktes

Der kürzeste sinnvolle Aufruf fragt die Geländehöhe und die Oberflächenhöhe an einem Punkt ab. Alle Beispiele auf dieser Seite laufen so, wie sie hier stehen, sobald der eigene Schlüssel eingesetzt ist.

curl -H "X-API-Key: gs_ihrschluessel" \
  "https://geoservice.schnee.co.at/height?lat=48.0&lon=13.8"

{
  "dgm_height": 426.01,
  "dom_height": 426.02,
  "coordinate_reprojected": { "x": 4604584.3, "y": 2772450.4 },
  "quelle": {
    "namensnennung": "Datenquelle: BEV, data.bev.gv.at, CC BY 4.0",
    "quellen": [ { "herausgeber": "BEV", "lizenz": "CC-BY-4.0", "erfassungsjahr": 2022 } ]
  }
}

dgm_height ist die Geländehöhe in Metern über dem Meer, dom_height die Höhe der Oberfläche einschließlich Bewuchs und Bebauung. Liegt der Punkt außerhalb des Bestands, stehen beide Werte auf null. Das Feld quelle enthält die Namensnennung, die bei einer Weitergabe der Werte mitgeführt werden muss.

Höhen und ProfilePunktwerte, Schnitte, Umgebungsgitter

curl -X POST -H "X-API-Key: gs_ihrschluessel" -H "Content-Type: application/json" \
  -d '{"start": {"lat": 48.00, "lon": 13.80}, "end": {"lat": 48.01, "lon": 13.81}}' \
  "https://geoservice.schnee.co.at/profile?resolution_m=1"

HorizontVerschattung rundum

/horizon liefert für 360 Richtungen den Höhenwinkel des Horizonts, getrennt für Gelände und Oberfläche, jeweils mit der Entfernung des Hindernisses. Damit lässt sich die Verschattung eines Standorts über den Tages- und Jahresverlauf rechnen.

Gebäude und GrundstückeUmrisse aus eigenem Bestand

Die Umrisse kommen aus dem eigenen Bestand des Dienstes und nicht aus einer fremden Live-Abfrage. Der Ausschnitt wird als bbox in der Reihenfolge minLon, minLat, maxLon, maxLat übergeben.

curl -H "X-API-Key: gs_ihrschluessel" \
  "https://geoservice.schnee.co.at/api/osm/gebaeude?bbox=13.79,47.99,13.81,48.01"

WindWindklima je Richtung

Das Windklima stammt aus dem Global Wind Atlas 4.0 und liegt für Deutschland, Österreich und die Schweiz auf einem Gitter von 0,025 Grad vor. Geliefert wird der nächste Gitterpunkt. Die Werte gelten für ebenes Gelände einheitlicher Rauigkeit und sind noch nicht der Wind am Standort.

curl -H "X-API-Key: gs_ihrschluessel" \
  "https://geoservice.schnee.co.at/api/wind/klima?lat=48.06&lon=13.60"

WetterNiederschlag und Temperatur über einer Fläche

Die Werte stammen aus den Rastern der Wetterdienste mit 1 km Zellweite: GeoSphere Austria (INCA stündlich, SPARTACUS täglich), Deutscher Wetterdienst (RADOLAN und HOSTRADA stündlich, HYRAS täglich) und MeteoSchweiz (täglich). Geliefert wird das flächengewichtete Mittel über alle Rasterzellen unter dem Vieleck. Zellen ohne Wert fallen aus dem Mittel, ein Zeitschritt ohne jeden Wert steht als null. Alle Zeiten in UTC.

curl -X POST -H "X-API-Key: gs_ihrschluessel" -H "Content-Type: application/json" \
  -d '{"flaeche": {"type": "Polygon", "coordinates": [[[13.59,48.05],[13.61,48.05],[13.61,48.07],[13.59,48.07],[13.59,48.05]]]},
       "groesse": "niederschlag", "takt": "monat", "von": "2024-01-01", "bis": "2024-12-31"}' \
  "https://geoservice.schnee.co.at/api/wetter/reihe"

BewuchsLaub- oder Nadelwald

Der Laubtyp des Baumbestands stammt aus dem Copernicus Land Monitoring Service (Dominant Leaf Type 2018) und liegt für Deutschland, Österreich und die Schweiz als Raster von 10 m vor. Je Gitterpunkt wird der Wert der Rasterzelle geliefert, in der er liegt.

curl -H "X-API-Key: gs_ihrschluessel" \
  "https://geoservice.schnee.co.at/api/bewuchs/waldart?xmin=13.599&ymin=48.058&xmax=13.607&ymax=48.063&punkte_x=61&punkte_y=61"

AdressenAnschrift zu Koordinate und zurück

Eine Suche für Österreich, Deutschland und die Schweiz. Zuerst wird im amtlichen Register gesucht (Österreich, Schweiz, Nordrhein-Westfalen, Berlin, Hamburg, Thüringen), Schreibfehler werden dort unscharf erkannt. Was das Register nicht kennt, kommt aus OpenStreetMap über den eigenen Photon-Dienst des Geoservice, notfalls über Nominatim. Jeder Treffer trägt im Feld quelle seine Herkunft: amtlich oder osm.

curl -H "X-API-Key: gs_ihrschluessel" \
  "https://geoservice.schnee.co.at/api/adresse/suche?q=Mösl%205,%204841%20Ungenach&limit=5"

Treffer aus OpenStreetMap stehen unter der Open Database License. Wer sie anzeigt, nennt „© OpenStreetMap-Mitwirkende“.

OrthofotoLuftbilder

Bestand und DatenstandWas liegt vor und wie alt ist es

Vor einer Berechnung lohnt die Frage, ob für den Ort überhaupt Daten vorliegen und aus welchem Jahr sie stammen. Maßgeblich ist das Erfassungsjahr, nicht der Zeitpunkt des Imports.

Die Endpunkte zu Lizenzen und Regionen mit den Verben POST, PUT und DELETE dienen der Pflege des Bestands und verlangen die Stufe verwalten. Sie sind für fremde Anbindungen ohne Belang.

ZwischenspeicherNur mit der Stufe verwalten

Der Dienst hält Höhendaten im Arbeitsspeicher. Diese Endpunkte greifen dort ein. Ein falscher Aufruf verlangsamt den Dienst für alle Nutzer, deshalb verlangen sie einen Schlüssel der Stufe verwalten.

FehlercodesWas die Antwort bedeutet

Fehlerantworten sind immer JSON und tragen das Feld detail mit einem Text in deutscher Sprache.

Grenzen und PflichtenVor der ersten Anbindung lesen

• Räumliche Abdeckung. Deutschland und Österreich, je nach Datentyp unterschiedlich vollständig. Außerhalb liefert der Dienst null statt eines geschätzten Werts.
• Bezugssysteme. Ein- und Ausgabe erfolgen in WGS84. Die einzige Ausnahme sind die Endpunkte des Zwischenspeichers mit ihren Feldern bbox_min_x bis bbox_max_y, die in EPSG:3035 rechnen. Umrechnen lässt sich beides mit /transform.
• Antwortgrößen. Höhengitter und Umrisslisten werden gepackt übertragen. Ein Ausschnitt in feinster Auflösung erreicht ungepackt zweistellige Megabyte, der eigene Zugriff sollte also gzip annehmen.
• Zeitgrenzen. Punktabfragen antworten in Millisekunden. Der erste Horizont oder das erste Gitter eines Gebiets braucht Sekunden bis Minuten. Eine Zeitgrenze unter 120 Sekunden ist zu knapp.
• Gleichzeitige Aufrufe. Ein einzelner Schlüssel sollte nicht mehr als fünf Anfragen gleichzeitig stellen. Der Dienst zählt Aufrufe je Schlüssel mit.
• Namensnennung. Die Daten stammen von amtlichen Stellen mit Nennungspflicht. Jede datenliefernde Antwort trägt die Namensnennung im Feld quelle oder in der Kopfzeile X-Quellenangabe. Sie muss in jeder Veröffentlichung mitgeführt werden, die auf diesen Werten beruht.
• Ablauf und Sperre. Ein Schlüssel kann ein Ablaufdatum tragen und jederzeit gesperrt werden. Beides zeigt sich als 401. Eine Sperre wirkt innerhalb einer halben Minute.
• Keine Gewähr. Die Höhen stammen aus Laserscandaten mit einer Erfassung, die je Gebiet Jahre auseinanderliegt. Für eine Planung ist das Erfassungsjahr über /tile_info zu prüfen.