Logo

Eine Initiative von Tourismus- und Kulturlandesrat Dipl.-Ing. Christian Benger

Kärntner
VERANSTALTUNGSDATENBANK

Entwickler-Dokumentation

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.

Schnittstelle und Token Anforderung

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.

Datenstruktur

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.

Paginierung & Envelope

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.

Beispiel

{
  "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"
  }
}

Event-Objekt

Wie der Name bereits besagt, repräsentiert ein Event-Objekt eine Veranstaltung in der Datenbank.

Beispiel

{
  "@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": "http://veranstaltungen.kaernten.at/events/RXZlbnREYi01NWE2NDQ1NDZkNjU2NDIwMTkxMDAwMDA",
  "categories": [
    {
      "id": "558c13c76d65640b8f1e0000",
      "name": "Wettkämpfe"
    }
  ],
  "image": {
    "@type": "ImageObject",
    "width": 371,
    "height": 270,
    "contentUrl": "http://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",
        "name": "Herzogstuhl",
        "geo": {
          "@type": "GeoCoordinates",
          "latitude": 14.3458308,
          "longitude": 46.6906372
        },
        "address": {
          "@type": "PostalAddress",
          "streetAddress": "L71",
          "postalCode": "9063",
          "addressCountry": "AT",
          "addressLocality": "Maria Saal"
        }
      }
    }
  ],
  "location": {
    "@type": "Place",
    "name": "Herzogstuhl",
    "geo": {
      "@type": "GeoCoordinates",
      "latitude": 14.3458308,
      "longitude": 46.6906372
    },
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "L71",
      "postalCode": "9063",
      "addressCountry": "AT",
      "addressLocality": "Maria Saal"
    }
  }
}

Folgende Erweiterungen wurden zum Standard-Schema von Schema.org/Event ergänzt:

Kategorien

Das Feld categories ist ein Array von Kategorien, denen eine Veranstaltung zugeordnet ist. Folgende Kategorien stehen zur Verfügung:

  • Aktivitäten
    • Adventure
    • Essen & Trinken
    • Fischen
    • Golf
    • Kulturreisen
    • Kunstvermittlung
    • Messen
    • Märkte
    • Rad, Wandern & Laufen
    • Wellness
    • Workshops & Kurse
  • Bühne
    • Kabarett und Comedy
    • Musical & Oper
    • Tanz
    • Theater
  • Festivals, Feste & Bälle
    • Festivals
    • Kunst
    • Maturabälle
    • Tanzveranstaltungen
    • Tradition
  • Galerie & Ausstellung
    • Ausstellungen
    • Führungen
    • Galerie
  • Kinder und Jugendkultur
    • Ausstellung für Kinder & Jugendliche
    • Literatur für Kinder & Jugendliche
    • Musik für Kinder & Jugendliche
    • Theater für Kinder & Jugendliche
  • Literatur und Bildung
    • Dia- und Lichtbildvorträge
    • Lesungen
    • Vorträge
  • Musik
    • Blasmusik
    • Chormusik
    • Elektronische Musik
    • Klassik & alte Musik
    • Pop, Rock, Jazz & Co
    • Volksmusik & Schlager
  • Sport
    • Shows
    • Wettkämpfe

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.

Beispiel
{
  "categories": [
    {
      "id": "558c15096d65640b8f250000",
      "name": "Adventure"
    },
    {
      "id": "558c127c6d65640b8f070000",
      "name": "Aktivitäten"
    },
    {
      "id": "59b24e862158b765db000917",
      "name": "Ausstellung für Kinder & Jugendliche"
    }
  ]
}

Event-Images

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.

Filter

Die Schnittstelle unterstützt das Filtern nach folgenden Kriterien:

Alle Filter-Kritierien werden nach dem folgenden Schema übergeben: http://...json?filter[<filter-typ>]=<Wert>

Mehrere Filter können gleichzeitig genutzt werden und werden logisch mit AND verknüpft.

Beispiele

      curl https://...json?filter[from]=23.10.2017&filter[to]=30.10.2017
      => 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
    

Nutzungsbedingungen

Cc by

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.



Logo

Eine Initiative von Tourismus- und Kulturlandesrat Dipl.-Ing. Christian Benger

Kärntner
VERANSTALTUNGSDATENBANK



Mit Ihrem Besuch auf dieser Website stimmen Sie der Verwendung von Cookies zu. Dies hilft uns den Service für Sie weiter zu verbessern.