Eine API (Application Programming Interface) fungiert als Schnittstelle zwischen Systemen bzw. Anwendungen und vereinfacht Kommunikation und Datenaustausch. Das Funktionsprinzip der API lässt sich mit einem Kellner vergleichen - Sie wählen den benötigten Datensatz aus unserem "Menü" und die API bringt Ihnen die Daten. Um die Bestellung aufzugeben wird eine "Request-URL" benötigt, welche einfach in die Adresszeile eines Browsers kopiert oder in ein Script (e.g. bash, Python, R...) integriert werden kann, um die Daten zu beziehen. Diese URL besteht zumeist aus dem "Endpoint" (siehe Stufe 1) und den "Query-Parametern" (siehe Stufe 2).
Der Endpoint hat grundsätzlich die folgende Struktur: <url>/<version>/<type>/<mode>/<resource_id>
Die Metadaten eines Datensatzes enthalten wesentliche Informationen wie zum Beispiel die im jeweiligen Datensatz verfügbaren Parameter. Um diese herunterzuladen wird lediglich der Endpoint benötigt und um den Parameter <metadata> ergänzt:
https://dataset.api.hub.geosphere.at/v1/station/current/tawes-v1-10min/metadata
<url>: https://dataset.api.hub.geosphere.at<version>: v1<type>: station<mode>: current<resource_id>: tawes-v1-10min
<metadata>: optional - wird ausschließlich für die Ausgabe der Metadaten benötigt und beim Download der Daten nicht angegeben
Abhängig von der Resource gibt es unterschiedliche Optionen für <type> und <mode> - weitere Informationen diesbezüglich finden Sie hier.
Die Metadaten werden grundsätzlich im json-Format ausgegeben. Für Stationsbasierte Datensätze (e.g. tawes-v1-10min) besteht aber auch die Möglichkeit diese im csv-Format zu beziehen. Bitte beachten Sie, dass diesbezüglich aktuell lediglich <mode>: "historical" unterstützt wird, und Stations- sowie Parameter-Metadaten getrennt abgefragt werden müssen:
https://dataset.api.hub.geosphere.at/v1/station/historical/tawes-v1-10min/metadata/stations
https://dataset.api.hub.geosphere.at/v1/station/historical/tawes-v1-10min/metadata/parameters
Die Query-Parameter enthalten spezifische Angaben, die benötigt werden umd die gesuchten Daten abzufragen - e.g. Parameter, Stations-IDs, Koordinaten, Datum- bzw. Zeit-Angaben, etc. Diese werden vom Endpoint durch ein ? getrennt. Einzelne Query-Parameter müssen mit einem & separiert werden. Werden für einen Query-Parameter mehrere Angaben gemacht, e.g. mehrere Stations-IDs, so werden diese durch einen , von einander getrennt.
Die folgenden Query-Parameter werden für die Abfrage verwendet - die Namen der meteorologischen Parameter und Station-IDs können den Metadaten entnommen werden (siehe Stufe 1):
<parameters>: TL, RR, FF<station_ids>: 11035, 11216<output_format>: csv - Datei-FormatIn Kombination mit dem Endpoint aus Stufe 1 ergibt sich die folgende Request-URL:
Im Gegensatz zum Endpoint gibt es keine festgelegte Reihenfolge für die Query-Parameter. Abhängig von der Resource können bzw. müssen weitere Query-Parameter angegeben werden.
Weitere Informationen und Beispiele finden Sie in unseren Dokumentationen.
Derzeit werden keine API-Keys für die Authentifizierung benötigt, bitte beachten Sie jedoch die aktuell gültigen Request-Limits:
Request-Rate Limit:
Request-Size Limit:
Die Request-Size einer Abfrage wird nach der folgenden Formel bestimmt:
<Request-Size> = <Parameter> * <Zeitschritte> * <Standorte/Gitterzellen>
<Parameter> = 3<Zeitschritte> = 1<Standorte> = 2<Request-Size> = 3 * 1 * 2 = 6