Events Resource Reference

You can access the events resource by means of the URL http://HOST/webservice/CALENDAR/events in which HOST and CALENDAR need to be replaced with suitable values. To restrict the list of the events returned, several search parameters can be specified.

Search parameters for events

api_key

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

id

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

from

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

to

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

what

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

where

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

category

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".

limit

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 below. Example:

../events?limit=20

offset

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

Notes on the Parameters 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.

Events result

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:

XML format of the events result document

<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="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>

Event data fields

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 event
  • dtstart: Point in time the event begins
  • dtend: Point in time the event ends
  • is_all_day: all-day event
  • is_permanent: This is a permanent event
  • event_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 language
  • event_set_en: Name of the series of events in English language
  • event_set_fr: Name of the series of events in French language
  • type_of_event: The event type
  • summary: Title / summary of the event (default value for all languages not explicitly specified)
  • summary_de: Title / summary of the event in German language
  • summary_en: Title / summary of the event in English language
  • summary_fr: Title / summary of the event in French language
  • description: Description of the event (default value for all languages not explicitly specified)
  • description_de: Description of the event in German language
  • description_en: Description of the event in English language
  • description_fr: Description of the event in French language
  • related_link: URL of the first link pointing to additional information
  • related_link_1_url: URL of the first link pointing to additional information
  • related_link_1_title: Title of the first link pointing to additional information
  • related_link_2_url: URL of the second link pointing to additional information
  • related_link_2_title: Title of the second link pointing to additional information
  • related_link_3_url: URL of the third link pointing to additional information
  • related_link_3_title: Title of the third link pointing to additional information
  • location_address0: Event location name
  • location_address1: Event location address
  • location_address2: Additional event loacation address information
  • location_city: Event location city
  • location_country: Event location country
  • location_postal_code: Event location postal code
  • location_latitude: Geological coordinates of the event location
  • location_longitude: Geological coordinates of the event location
  • contact_title: The contact person's title
  • contact_first_name: The contact person's first name
  • contact_last_name: The contact person's last name
  • contact_phone: The contact person's phone number
  • contact_fax: The contact person's fax number
  • contact_email: The contact person's e-mail address
  • category: Name of the event category (default value for all languages not explicitly specified)
  • category_de: Name of the event category in German language
  • category_en: Name of the event category in English language
  • category_fr: Name of the event category in French language

Sample events result document for a search request without a unique key

The web service call

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

produces the following result:

<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>

Sample events result document for a search request with a unique key

The web service call

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

produces the following result:

<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>