Events Resource Reference

You can access the events resource by means of the URL https://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

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

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 https://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 https://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