Eine Initiative der Kärntner Landesregierung
Im Sinne des Open-Data-Prinzips wurde die Kärntner Veranstaltungsdatenbank von Anfang an mit einer offenen Schnittstelle konzipiert, die es Entwicklern ermöglicht, Daten abzurufen und in eigene Applikationen/Webseiten zu integrieren.
Die Schnittstelle liefert die Event-Daten als JSON aus, welches als JSON-Linked-Data (JSON-LD) formatiert wird. Das Event-Schema folgt hierbei (mit hier dokumentierten Änderungen) den Vorgaben von Schema.org/Event.
Voraussetzung für die Nutzung der Schnittstelle der Kärntner Veranstaltungsdatenbank ist ein autorisierter API-Endpunkt. Ein öffentlicher Endpunkt, der alle Events beinhaltet, wird unter angeboten. Man kann sich jedoch als Entwickler registrieren und einen personalisierten Endpunkt einrichten, der spezielle Filter- und Sortierkriterien bereit stellt, um die Entwicklung zu erleichtern.
Die Schnittstelle liefert, wie bereits erwähnt, JSON-LD Daten welchen das Schema.org/Event Schema zugrunde liegt. Die Events werden als JSON-Liste angezeigt, im Feld events während das Feld links Informationen zur Paginierung der API beinhaltet.
Die Event-Liste befindet sich immer in der Eigenschaft events und ist in jedem Fall ein JSON-Array ([]). Falls keine Events gefunden werden, wird ein leeres Array zurückgegeben.
Die links Sektion bietet URLs zur nächsten (next), vorherigen (prev), ersten (first) und letzten (last) Seite. Befindet man sich auf der ersten oder letzten Seite so werden die Eigenschaften next bzw prev entsprechend nicht ausgegeben.
Über den zusätzlichen, optionalen Parameter pagesize lässt sich die Anzahl der pro Seite gelieferten Veranstaltungen an die spezifischen Bedürfnisse der jeweiligen Applikation bzw. Website anpassen.
{ "events": [ .... ], "links": { "first": "http://veranstaltungen.kaernten.at/api/v2/endpoints/557ea81f6d6564769e010000?page=1&pagesize=20", "next": "http://veranstaltungen.kaernten.at/api/v2/endpoints/557ea81f6d6564769e010000?page=2&pagesize=20", "last": "http://veranstaltungen.kaernten.at/api/v2/endpoints/557ea81f6d6564769e010000?page=23&pagesize=20" } }
Wie der Name bereits besagt, repräsentiert ein Event-Objekt eine Veranstaltung in der Datenbank.
{ "@context": "http://schema.org/", "@type": "Event", "name": "Zollfeld Challenge Einzelzeitfahren", "description": "<p>Als großes Highlight der Rennradsaison wird der Sportverein \n„trispoat“ heuer erstmalig ein Einzelzeitfahren für Radsportler und \nTriathleten veranstalten. Das Zeitfahren soll zu einem Fixpunkt der \nWettkampfsaison in der Alpen-Adria-Region werden und über die Grenzen \nder Region Bekanntheit erlangen. Die „Zollfeld Challenge“ ist offen für \nalle Amateur- und Profiradsportler. Mit der offiziellen Anmeldung zu \ndieser Veranstaltung erkennt jeder Teilnehmer das Reglement der \nVeranstaltung an. </p><br>", "startDate": "2015-07-25T15:00:00+00:00", "endDate": "2015-07-25T17:00:00+00:00", "url": "https://veranstaltungen.kaernten.at/events/RXZlbnREYi01NWE2NDQ1NDZkNjU2NDIwMTkxMDAwMDA", "categories": [ { "id": "558c13c76d65640b8f1e0000", "name": "Wettkämpfe" } ], "image": { "@type": "ImageObject", "id": "55a643d96d656420190e0000", "width": 371, "height": 270, "contentUrl": "https://veranstaltungen.kaernten.at/api/assets/55a643d96d656420190e0000.png" }, "subEvents": [ { "type": "Event", "start_date": "2015-07-25T15:00:00+02:00", "end_date": "2015-07-25T17:00:00+02:00", "location": { "@type": "Place", "id": "5c19ce0c2158b73ae8000000", "name": "Herzogstuhl", "geo": { "@type": "GeoCoordinates", "latitude": 46.6933336, "longitude": 14.3489333 }, "address": { "@type": "PostalAddress", "streetAddress": "L71", "postalCode": "9063", "addressCountry": "AT", "addressLocality": "Maria Saal" } } } ], "location": { "@type": "Place", "id": "5c19ce0c2158b73ae8000000", "name": "Herzogstuhl", "geo": { "@type": "GeoCoordinates", "latitude": 46.6933336, "longitude": 14.3489333 }, "address": { "@type": "PostalAddress", "streetAddress": "L71", "postalCode": "9063", "addressCountry": "AT", "addressLocality": "Maria Saal" } } }
Folgende Erweiterungen wurden zum Standard-Schema von Schema.org/Event ergänzt:
Das Feld categories ist ein Array von Kategorien, denen eine Veranstaltung zugeordnet ist. Folgende Kategorien stehen zur Verfügung:
Sämtliche Kategorien können über die Schnittstelle http://veranstaltungen.kaernten.at/api/v2/categories abgerufen werden. Die Rückgabe erfolgt als JSON-Liste im categories Feld.
{ "categories": [ { "id": "558c15096d65640b8f250000", "name": "Adventure" }, { "id": "558c127c6d65640b8f070000", "name": "Aktivitäten" }, { "id": "59b24e862158b765db000917", "name": "Ausstellung für Kinder & Jugendliche" } ] }
Viele Events beinhalten neben den textuellen Infos zusätzlich noch ein Foto oder eine Grafik. Das Foto bzw. die Grafik kann über die im Feld image.contentUrl angeführte URL heruntergeladen werden. Um Bandbreite bei der Datenübertragung einzusparen, bietet die API die Möglichkeit, die Größe der Bilddatei zu begrenzen. Dazu können der URL zusätzliche Parameter zum Begrenzen der Bilddimensionen hinzugefügt werden (z.B.: http://.../image.png?width=300&height=200). Wird dabei nur einer der beiden Parameter übergeben, wird das Bild entsprechend seines Seitenverhältnisses skaliert. Sind beide Parameter gesetzt wird die so definierte Fläche ausgefüllt und überstehende Bildteile abgeschnitten.
Die Schnittstelle unterstützt das Filtern nach folgenden Kriterien:
category)from, to)lat, lng, distance)http://...json?filter[<filter-typ>]=<Wert>
Mehrere Filter können gleichzeitig genutzt werden und werden logisch mit AND verknüpft.
curl https://...json?filter[from]=19.12.2018&filter[to]=26.12.2018
=> Liefert alle Events der nächsten Woche
curl https://....json?filter[lat]=46.6223464&filter[lng]=14.3084264&filter[distance]=20
=> Liefert alle Events in einem Umkreis von 20 Kilometern um die Koordinaten von Klagenfurt (46.6223464, 14.3084264)
curl https://....json?filter[category]=558c15096d65640b8f250000
=>Liefert alle Events der Kategorie Adventure
veranstaltungen.kaernten.at ist gemäß der Open Government Data Österreich Lizenz CC-BY 3.0 AT sowohl für private als auch kommerzielle Zwecke frei sowie entgeltfrei nutzbar.
Die Namensnennung hat in folgender Weise zu erfolgen: „Datenquelle: veranstaltungen.kaernten.at“, wobei „veranstaltungen.kaernten.at“ als Link auf veranstaltungen.kaernten.at auszuführen ist.