You can access the events resource by means of the URL
http://HOST/webservice/INSTANCE/CALENDAR/events
in which
HOST
, INSTANCE
, and CALENDAR
need to
be replaced with suitable values. To restrict the list of the events
returned, several search parameters can be specified.
Type: String. Specifies the API key. No default value exists.
A valid API key must be specified for each query. Example:
../events?api_key=abcdef
Type: Integer. Specifies the unique key of an event. No default value
exists. If this search parameter is specified, all other search parameters
except api_key
are ignored. Only the event with the specified
unique key will be found if it exists and has been released for publication.
Example:
../events?id=53124
Type: Datetime. Specifies the minimum start date (attribute
dtstart
) an event must have to be potentially returned in the
search result. This parameter, in conjunction with the to
parameter,
makes it possible to search only for events whose start date and time
lies within the specified limits, including these limits. The default value is
the date and time the service is accessed. Example:
../events?from=2007-10-28T13:35:00
Type: Datetime. Specifies the maximum start date (attribute
dtstart
) an event must have to be potentially returned in the
search result. The default value is empty. If this parameter has not been
specified, the search is performed without an upper limit to the start date.
Example:
../events?to=2007-10-28T14:00:00
Type: String. Searches the summaries and descriptions of the
events, i.e. their summary
and description
attributes.
An event is potentially added to the results list only if the parameter value
is contained in at least one of these event attributes. The default value is
empty. If the parameter has not been specified, the search is not restricted
with respect to the summary or description.
Example:
../events?what=Concert
Type: String. Searches the locations of the events, i.e. the
location
attribute.
An event is potentially added to the results list only if the parameter value
is contained in this event attribute. The default value is
empty. If the parameter has not been specified, the search is not restricted
with respect to the event location.
Example:
../events?where=Concert hall
Type: String. Searches the default name of the event category, i.e.
the category
attribute. If the full name of the category has
been specified, only events are returned whose category matches the
parameter value. The default value is empty. If the parameter has not
been specified, the search is not restricted with respect to the event
category. If the last character of this parameter is the %
character, all categories whose name starts with the specified string are
searched. Examples:
../events?category=Sport:Basketball
finds all events in the Sport:Basketball
category.
../events?category=Sport%
finds all events in categories starting with "Sport".
Type: Integer(1..50). This parameter determines the maximum number
of events to be returned. If the results list contains more events, only the first
limit
events, sorted by their start date, are returned.
The default value is 10. If specified, the parameter value must be in
the range from 1 to 50. See also the
Notes on the Parameters offset
and limit
.
Example:
../events?limit=20
Type: Integer. This parameter specifies the number of events to be omitted when the search results are returned.
The first offset
events, sorted by their start date, are omitted from the search results.
If less than offset
events are found, no event is returned. Only positive values may be specified.
The default value is 0, meaning that the first event returned is the first that was found. In conjunction with
the limit
parameter, the results can be output page by page. See also the
Notes on the Parameters offset
and limit
below.
Example:
../events?offset=100
offset
and limit
The maximum number of hits a search query returns is 300. Thus, no
hits are returned if an offset is used that is greater than 300. If
offset+limit
is greater than 300, only
300−offset
hits are returned.
The fact that a request that was processed without any errors is indicated by the HTTP status code 200. In this case, an XML document is returned that has the following structure:
<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>
The name and the meaning of the individual data fields are borrowed from
the data format of the text/calendar
MIME type (see
http://en.wikipedia.org/wiki/ICalendar).
An event corresponds to a VEVENT
component in the
text/calendar
format. Exceptions to this are the data fields contact
and location
. In contrast to a VEVENT
component, these fields are not output as one field but as the corresponding details fields.
id
: Unique key of the eventdtstart
: Point in time the event beginsdtend
: Point in time the event endsis_all_day
: all-day eventevent_set
: Name of the series of events (default value for all languages not explicitly specified)event_set_de
: Name of the series of events in German languageevent_set_en
: Name of the series of events in English languageevent_set_fr
: Name of the series of events in French languagesummary
: Title / summary of the event (default value for all languages not explicitly specified)summary_de
: Title / summary of the event in German languagesummary_en
: Title / summary of the event in English languagesummary_fr
: Title / summary of the event in French languagedescription
: Description of the event (default value for all languages not explicitly specified)description_de
: Description of the event in German languagedescription_en
: Description of the event in English languagedescription_fr
: Description of the event in French languagerelated_link
: URL pointing to additional informationlocation_address0
: Event location namelocation_address1
: Event location addresslocation_address2
: Additional event loacation address informationlocation_city
: Event location citylocation_country
: Event location countrylocation_postal_code
: Event location postal codecontact_title
: The contact person's titlecontact_first_name
: The contact person's first namecontact_last_name
: The contact person's last namecontact_phone
: The contact person's phone numbercontact_fax
: The contact person's fax numbercontact_email
: The contact person's e-mail addresscategory
: Name of the event category (default value for all languages not explicitly specified)category_de
: Name of the event category in German languagecategory_en
: Name of the event category in English languagecategory_fr
: Name of the event category in French languageThe web service call
curl http://agenda.infopark.de/webservice/wstest/cal/events?api_key=webservicetestapikey\&from=2007-11-01
produces the following result:
<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>
The web service call
curl http://agenda.infopark.de/webservice/wstest/cal/events?api_key=webservicetestapikey\&id=53125
produces the following result:
<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>