Events-Ressource-Referenz

Auf die Events-Ressource können Sie über die URL https://HOST/webservice/CALENDAR/events zugreifen, wobei HOST und CALENDAR jeweils durch passende Werte ersetzt werden müssen. Um die Liste der zurückgegebenen Events einzuschränken, können diverse Suchparameter verwendet werden.

Events-Suchparameter

api_key

Typ: String. Gibt den API-Key an. Es gibt keinen Default-Wert. Bei jedem Zugriff muss ein gültiger API-Key angegeben werden. Beispiel:

../events?api_key=abcdef

id

Typ: Integer. Gibt den eindeutigen Schlüssel eines Events an. Es gibt keinen Default-Wert. Wird dieser Suchparameter angegeben, dann werden alle anderen Suchparameter (außer api_key) ignoriert. Es wird nur noch der Event mit dem angegebenen eindeutigen Schlüssel gefunden, falls er existiert und zur Veröffentlichung freigegeben ist. Beispiel:

../events?id=53124

from

Typ: Datetime. Gibt den Zeitpunkt an, ab dem die Events gesucht werden sollen. Er bezieht sich auf das Start-Datum des Events (Attribut dtstart). Dieser Parameter ermöglicht es in Verbindung mit dem Parameter to, nach Events zu suchen, die innerhalb der angegebenen Zeitspanne (einschließlich der angegebenen Zeitpunkte) beginnen. Der Default-Wert ist der Zeitpunkt des Zugriffs auf den Web-Service. Beispiel:

../events?from=2007-10-28T13:35:00

to

Typ: Datetime. Gibt den Zeitpunkt an, bis zu dem (einschließlich) die Events gesucht werden sollen. Er bezieht sich auf das Start-Datum des Events (Attribut dtstart). Der Default-Wert ist leer. Wenn der Parameter nicht angegeben wird, werden Events ohne Zeitbegrenzung gesucht. Beispiel:

../events?to=2007-10-28T14:00:00

what

Typ: String. Sucht im Text des Events (Attribute summary und description). Es werden nur Events ausgegeben, in deren Text der Wert des Parameters vorkommt. Der Default-Wert ist leer. Wenn der Parameter nicht angegeben wird, werden alle Events ohne Einschränkung gesucht. Beispiel:

../events?what=Konzert

where

Typ: String. Sucht im Text des Veranstaltungsortes (Attribut location). Es werden nur Events ausgegeben, in deren Veranstaltungsort der Wert des Parameters vorkommt. Der Default-Wert ist leer. Wenn der Parameter nicht angegeben wird, werden alle Events ohne Einschränkung des Veranstaltungsortes gesucht. Beispiel:

../events?where=Konzerthalle

category

Typ: String. Sucht im Default-Namen der Kategorie des Events (Attribut category). Wenn der vollständige Name der Kategorie angegeben wird, werden nur Events ausgegeben, die in der Kategorie mit dem Namen des Parameter-Wertes enthalten sind. Der Default-Wert ist leer. Wenn der Parameter nicht angegeben wird, werden alle Events in allen Kategorien gesucht. Wenn das letzte Zeichen das %-Zeichen ist, werden alle Kategorien durchsucht, die mit der angegebenen Zeichenfolge beginnen. Beispiele:

../events?category=Sport:Basketball

findet alle Events in der Kategorie "Sport:Basketball".

../events?category=Sport%

findet alle Events in allen Kategorien, die mit "Sport" beginnen.

limit

Typ: Integer(1..50). Der Parameter gibt an, wieviele Events maximal zurückgegeben werden sollen. Werden mehr Events gefunden, werden nur die ersten limit Events, sortiert nach dem Start-Datum, zurückgegeben. Der Default-Wert ist 10. Es sind nur Werte zwischen 1 und 300 erlaubt. Siehe auch die Anmerkungen zu den Parametern offset und limit am Ende dieses Abschnitts. Beispiel:

../events?limit=20

offset

Typ: Integer. Der Parameter gibt an, wieviele Events bei der Ausgabe übersprungen werden sollen. Bei der Ausgabe werden die ersten offset Events, sortiert nach dem Start-Datum, übersprungen. Werden weniger als offset Events gefunden, wird kein Event zurückgegeben. Es sind nur positive Werte erlaubt. Der Default-Wert ist 0, d.h. die Ausgabe beginnt beim ersten gefundenen Event. Zusammen mit dem Parameter limit kann eine seitenweise Ausgabe realisiert werden. Siehe auch die Anmerkungen zu den Parametern offset und limit am Ende dieses Abschnitts. Beispiel:

../events?offset=100

Anmerkungen zu den Parametern offset und limit

Bei jeder Suchanfrage werden maximal 300 Ergebnisse gefunden. Demzufolge werden bei einem Offset größer als 300 keine Ergebnisse zurückgegeben. Wenn offset+limit größer als 300 ist, werden nur 300−offset Ergebnisse zurückgegeben.

Events-Ergebnis

Die fehlerfreie Verarbeitung der Anfrage wird durch den HTTP-Status-Code 200 angezeigt. In diesem Fall wird als Rückgabe ein XML-Dokument geliefert, das die folgende Struktur hat:

XML-Format des Events-Ergebnis-Dokuments

<element name="events" xmlns="https://relaxng.org/ns/structure/1.0">
  <zeroOrMore>
    <element name="event">
      <interleave>
        <element name="id"><data type="int"/></element>
        <element name="dtstart"><data type="dateTime"/></element>
        <element name="dtend"><data type="dateTime"/></element>
        <optional>
          <element name="is_all_day"><empty/></element>
        </optional>
        <optional>
          <element name="is_permanent"><empty/></element>
        </optional>
        <optional>
          <element name="event_set"><text/></element>
        </optional>
        <optional>
          <element name="event_set_de"><text/></element>
        </optional>
        <optional>
          <element name="event_set_en"><text/></element>
        </optional>
        <optional>
          <element name="event_set_fr"><text/></element>
        </optional>
        <optional>
          <element name="type_of_event"><text/></element>
        </optional>
        <element name="summary"><text/></element>
        <optional>
          <element name="summary_de"><text/></element>
        </optional>
        <optional>
          <element name="summary_en"><text/></element>
        </optional>
        <optional>
          <element name="summary_fr"><text/></element>
        </optional>
        <optional>
          <element name="description"><text/></element>
        </optional>
        <optional>
          <element name="description_de"><text/></element>
        </optional>
        <optional>
          <element name="description_en"><text/></element>
        </optional>
        <optional>
          <element name="description_fr"><text/></element>
        </optional>
        <optional>
          <element name="related_link"><text/></element>
        </optional>
        <optional>
          <element name="related_link_1_url"><text/></element>
        </optional>
        <optional>
          <element name="related_link_1_title"><text/></element>
        </optional>
        <optional>
          <element name="related_link_2_url"><text/></element>
        </optional>
        <optional>
          <element name="related_link_2_title"><text/></element>
        </optional>
        <optional>
          <element name="related_link_3_url"><text/></element>
        </optional>
        <optional>
          <element name="related_link_3_title"><text/></element>
        </optional>
        <optional>
          <element name="location_address0"><text/></element>
        </optional>
        <optional>
          <element name="location_address1"><text/></element>
        </optional>
        <optional>
          <element name="location_address2"><text/></element>
        </optional>
        <optional>
          <element name="location_city"><text/></element>
        </optional>
        <optional>
          <element name="location_country"><text/></element>
        </optional>
        <optional>
          <element name="location_postal_code"><text/></element>
        </optional>
        <optional>
          <element name="location_latitude"><data type="decimal"/></element>
        </optional>
        <optional>
          <element name="location_longitude"><data type="decimal"/></element>
        </optional>
        <optional>
          <element name="contact_title"><text/></element>
        </optional>
        <optional>
          <element name="contact_first_name"><text/></element>
        </optional>
        <optional>
          <element name="contact_last_name"><text/></element>
        </optional>
        <optional>
          <element name="contact_phone"><text/></element>
        </optional>
        <optional>
          <element name="contact_fax"><text/></element>
        </optional>
        <optional>
          <element name="contact_email"><text/></element>
        </optional>
        <zeroOrMore>
          <group>
            <interleave>
              <element name="category"><text/></element>
              <element name="category_de"><text/></element>
              <element name="category_en"><text/></element>
              <element name="category_fr"><text/></element>
            </interleave>
          </group>
        </zeroOrMore>
      </interleave>
    </element>
  </zeroOrMore>
</element>

Beschreibung der Datenfelder eines Events

Der Name und die Bedeutung der einzelnen Datenfelder sind dem Datenformat für den Mime-Type text/calendar entlehnt (siehe https://en.wikipedia.org/wiki/ICalendar). Ein Event entspricht einer VEVENT-Komponente im text/calendar-Format. Eine Ausnahme bilden die beiden Datenfelder contact und location. Diese werden – anders als bei einer VEVENT-Komponente – nicht als ein Feld ausgegeben, sondern als entsprechende Detail-Felder.

  • id: Eindeutiger Schlüssel des Events
  • dtstart: Zeitpunkt des Beginns des Events
  • dtend: Zeitpunkt des Endes des Events
  • is_all_day: ganztägiger Event
  • is_permanent: das Event ist permanent
  • event_set: Name der Veranstaltungsreihe (Default-Wert für alle nicht explizit angegeben Sprachen)
  • event_set_de: Name der Veranstaltungsreihe in deutscher Sprache
  • event_set_en: Name der Veranstaltungsreihe in englischer Sprache
  • event_set_fr: Name der Veranstaltungsreihe in französischer Sprache
  • type_of_event: Typ der Veranstaltung
  • summary: Titel bzw. Zusammenfassung des Events (Default-Wert für alle nicht explizit angegeben Sprachen)
  • summary_de: Titel bzw. Zusammenfassung des Events in deutscher Sprache
  • summary_en: Titel bzw. Zusammenfassung des Events in englischer Sprache
  • summary_fr: Titel bzw. Zusammenfassung des Events in französischer Sprache
  • description: Beschreibung des Events (Default-Wert für alle nicht explizit angegeben Sprachen)
  • description_de: Beschreibung des Events in deutscher Sprache
  • description_en: Beschreibung des Events in englischer Sprache
  • description_fr: Beschreibung des Events in französischer Sprache
  • related_link: URL des ersten Links zu weiterführenden Informationen
  • related_link_1_url: URL des ersten Links zu weiterführenden Informationen
  • related_link_1_title: Titel des ersten Links zu weiterführenden Informationen
  • related_link_2_url: URL des zweiten Links zu weiterführenden Informationen
  • related_link_2_title: Titel des zweiten Links zu weiterführenden Informationen
  • related_link_3_url: URL des dritten Links zu weiterführenden Informationen
  • related_link_3_title: Titel des dritten Links zu weiterführenden Informationen
  • location_address0: Bezeichnung des Veranstaltungsortes
  • location_address1: Adresse des Veranstaltungsortes
  • location_address2: Adresszusatz des Veranstaltungsortes
  • location_city: Stadt des Veranstaltungsortes
  • location_country: Land des Veranstaltungsortes
  • location_postal_code: Postleitzahl des Veranstaltungsortes
  • location_latitude: Geo-Koordinaten des Veranstaltungsortes
  • location_longitude: Geo-Koordinaten des Veranstaltungsortes
  • contact_title: Titel des Ansprechpartners
  • contact_first_name: Vorname des Ansprechpartners
  • contact_last_name: Nachname des Ansprechpartners
  • contact_phone: Telefonnummer des Ansprechpartners
  • contact_fax: Faxnummer des Ansprechpartners
  • contact_email: E-Mail-Adresse des Ansprechpartners
  • category: Name der Kategorie des Events (Default-Wert für alle nicht explizit angegeben Sprachen)
  • category_de: Name der Kategorie des Events in deutscher Sprache
  • category_en: Name der Kategorie des Events in englischer Sprache
  • category_fr: Name der Kategorie des Events in französischer Sprache

Beispiel eines Events-Ergebnis-Dokuments einer Suchanfrage ohne Angabe eines eindeutigen Schlüssels

Der Web-Service-Aufruf

curl https://agendatest.infopark.de/webservice/cal/events?api_key=webservicetestapikey\&from=2007-11-01

erzeugt das folgende Ergebnis:

<events>
  <event>
    <id>2929</id>
    <dtstart>2007-11-07T16:00:00+01:00</dtstart>
    <dtend>2007-11-07T18:00:00+01:00</dtend>
    <event_set>international championship</event_set>
    <event_set_de>Internationale Meisterschaft</event_set_de>
    <event_set_en>international championship</event_set_en>
    <event_set_fr>championnat internationale</event_set_fr>
    <summary>England vs. Zimbabwe</summary>
    <summary_de>England gegen Zimbabwe</summary_de>
    <location_city>London</location_city>
    <category>Sports:Cricket</category>
    <category_de>Sport:Cricket</category_de>
    <category_en>Sports:Cricket</category_en>
    <category_fr>Sport:Cricket</category_fr>
  </event>
  <event>
    <id>2930</id>
    <dtstart>2007-11-08T19:00:00+01:00</dtstart>
    <dtend>2007-11-08T21:00:00+01:00</dtend>
    <summary>Liverpool 2-1 Arsenal</summary>
    <description>LIVERPOOL: Alonso 41, Mellor 90
ARSENAL 1: Vieira 57

FA Barclays Premiership</description>
    <category>Sports:Football</category>
    <category_de>Sport:Fussball</category_de>
    <category_en>Sports:Football</category_en>
    <category_fr>Sport:Football</category_fr>
  </event>
</events>

Beispiel eines Events-Ergebnis-Dokuments einer Suchanfrage mit Angabe eines eindeutigen Schlüssels

Der Web-Service-Aufruf

curl https://agendatest.infopark.de/webservice/cal/events?api_key=webservicetestapikey\&id=2930

erzeugt das folgende Ergebnis:

<events>
  <event>
    <id>2930</id>
    <dtstart>2007-11-08T19:00:00+01:00</dtstart>
    <dtend>2007-11-08T21:00:00+01:00</dtend>
    <summary>Liverpool 2-1 Arsenal</summary>
    <description>LIVERPOOL: Alonso 41, Mellor 90
ARSENAL 1: Vieira 57

FA Barclays Premiership</description>
    <category>Sports:Football</category>
    <category_de>Sport:Fussball</category_de>
    <category_en>Sports:Football</category_en>
    <category_fr>Sport:Football</category_fr>
  </event>
</events>