Auf die Events-Ressource können Sie über die URL
http://HOST/webservice/INSTANCE/CALENDAR/events
zugreifen,
wobei HOST
, INSTANCE
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.
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
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
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
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
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
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
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.
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
.
Beispiel:
../events?limit=20
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
.
Beispiel:
../events?offset=100
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.
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:
<element name="events" xmlns="http://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="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> <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="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="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>
Der Name und die Bedeutung der einzelnen Datenfelder sind dem
Datenformat für den Mime-Type text/calendar
entlehnt (siehe
http://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 Eventsdtstart
: Zeitpunkt des Beginns des Eventsdtend
: Zeitpunkt des Endes des Eventsis_all_day
: ganztägiger Eventevent_set
: Name der Veranstaltungsreihe (Default-Wert für alle
nicht explizit angegeben Sprachen)event_set_de
: Name der Veranstaltungsreihe in deutscher Spracheevent_set_en
: Name der Veranstaltungsreihe in englischer Spracheevent_set_fr
: Name der Veranstaltungsreihe in französischer
Sprachesummary
: Titel bzw. Zusammenfassung des Events (Default-Wert für
alle nicht explizit angegeben Sprachen)summary_de
: Titel bzw. Zusammenfassung des Events in deutscher
Sprachesummary_en
: Titel bzw. Zusammenfassung des Events in englischer
Sprachesummary_fr
: Titel bzw. Zusammenfassung des Events in französischer
Sprachedescription
: Beschreibung des Events (Default-Wert für alle nicht
explizit angegeben Sprachen)description_de
: Beschreibung des Events in deutscher Sprachedescription_en
: Beschreibung des Events in englischer Sprachedescription_fr
: Beschreibung des Events in französischer Spracherelated_link
: URL mit Link zu weiterführenden Informationenlocation_address0
: Bezeichnung des Veranstaltungsorteslocation_address1
: Adresse des Veranstaltungsorteslocation_address2
: Adresszusatz des Veranstaltungsorteslocation_city
: Stadt des Veranstaltungsorteslocation_country
: Land des Veranstaltungsorteslocation_postal_code
: Postleitzahl des Veranstaltungsortescontact_title
: Titel des Ansprechpartnerscontact_first_name
: Vorname des Ansprechpartnerscontact_last_name
: Nachname des Ansprechpartnerscontact_phone
: Telefonnummer des Ansprechpartnerscontact_fax
: Faxnummer des Ansprechpartnerscontact_email
: E-Mail-Adresse des Ansprechpartnerscategory
: Name der Kategorie des Events (Default-Wert für alle
nicht explizit angegeben Sprachen)category_de
: Name der Kategorie des Events in deutscher Sprachecategory_en
: Name der Kategorie des Events in englischer Sprachecategory_fr
: Name der Kategorie des Events in französischer
SpracheDer Web-Service-Aufruf
curl http://agenda.infopark.de/webservice/wstest/cal/events?api_key=webservicetestapikey\&from=2007-11-01
erzeugt das folgende Ergebnis:
<events> <event> <id>53124</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>53125</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>
Der Web-Service-Aufruf
curl http://agenda.infopark.de/webservice/wstest/cal/events?api_key=webservicetestapikey\&id=53125
erzeugt das folgende Ergebnis:
<events> <event> <id>53125</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>