API Method /calendars/events/list

This function returns a list of events associated with a calendar.

Arguments

authentication: This method controls access via optional user authentication.
id string: The calendar ID.
count_only boolean: If count_only is set, an abbreviated version of the output will be returned. Only total_items and search_time elements are included in the result. (optional)
modified_since string: Searches for events that were modified after modified_since time. In the form of yyyy-MM-ddTHH-mm-ss. (E.g. "2005-11-15T18:00:00".)
sort_order string: One of 'date', 'title', 'venue_name'. Default is 'date'. (optional)
sort_direction string: One of 'ascending' or 'descending'. Default is 'ascending'. (optional)
page_size integer: The desired number of results per page. (optional)
page_number integer: The desired page number. (optional)

Example Request

Here's an example search URL:

http://api.evdb.com/rest/calendars/events/list?...&id=C0-001-000002448-9&modified_since=2005-11-15T18:00:00

Output Parameters

Output from this function is an XML calendar block with the following constructs:

id string

The calendar ID.

name string

The calendar name.

owner string

The username of the calendar's owner.

description string

The calendar description.

keywords string

The keywords associated with the calendar.

smart boolean

Indicates whether the calendar is smart: "1" for true and "0" for false.

privacy integer

The calendar's privacy level: public ("1"), private ("2"), or sharable ("3").

notify_schedule string

Choice to notify owner on updates to calendar either "immediately", "daily", or "weekly".

what_query string

The keyword half of the query driving a smart calendar.

where_query string

The location half of the query driving a smart calendar.

total_items integer

The total number of items in the result set.

page_size integer

The number of events per "page" returned.

page_count integer

The number of "pages" of output.

page_number integer

The current "page" number.

page_items integer

The number of events returned in this block. This is not necessarly the same as page_size. The last page, for instance, will probably not be a full page.

first_item integer

The item number of the first element on this page.

last_item integer

The item number of the last element on this page.

search_time float

The fractional number of seconds it took to satisfy this query.

events array

An array of page_items events. Each event entry has the following structure:

id string

The unique ID for this event. Presented as an event object attribute. See the example below.

title string

The event title.

description string

The event description.

start_time string

The event start time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").

stop_time string

The event stop time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").

venue_id integer

The venue ID.

venue_name string

The venue name.

venue_display boolean

Whether or not the venue name should be displayed in certain cirumstances. Eventful's notion of a venue is a bit broader than you might think. For example, events for which only the postal code is known have a venue named "Postal code 46311, US", for instance. In these cases, a traditional address block looks a bit unusual, and Eventful chooses not to display the venue name in these cases. You may wish to do the same, and the venue_display parameter allows you to do that.

venue_address string

The venue address.

city_name string

The venue city_name.

region_name string

The venue state/province/other name.

region_abbr string

The venue state/province/other abbreviation.

postal_code string

The venue postal code.

country_name string

The venue country name.

all_day boolean

If true, this event lasts all day.

search_rank float

The relevance rank of this result, relative to other events in the search results.

latitude signed float

The venue latitude.

longitude signed float

The venue longitude.

geocode_type string

The method used to geocode the venue latitude and longitude.

trackback_count integer

The number of trackback entries associated with this event.

calendar_count integer

The number of calendars to which this event has been added.

comment_count integer

The number of comments associated with this event.

link_count integer

The number of URLs associated with this event.

created string

The event creation time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").

images array

Array of images associated with the event, each image is an image block contianing:

url string: The source URL of an image.
width integer: Image width, in pixels.
height integer: Image height, in pixels.
caption string: The image caption.

deleted string

The event deletion time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").

timezone string

The timezone the event occurs in.

modified string

The event last modified time, in ISO 8601 format (e.g. "2005-03-01 19:00:00").

groups array

An array of groups associated with this calendar.

id string: The unique ID for the group.
group_name string: The group name.
group_desc string: The group description.
creator_id string: The group's creator.

feeds array

An array of feeds associated with the calendar.

id string: The unique ID for this feed.
name string: The feed name.
description string: The feed description.
url string: The URL associated with the feed.
image_url string: The URL of the image associated with the feed.

tags array

An array of tags associated with the calendar.

owner string: The username of the tag's creator.
title string: The tag string.

Example XML Response

 <?xml version="1.0" encoding="UTF-8"?>
<calendar id="C0-001-000002282-5">
  <name>inging in San Diego</name>
  <owner>dano</owner>
  <description>...</description>
  <keywords>biking cycling diego frisbee golf...</keywords>
  <smart>0</smart>
  <privacy>2</privacy>
  <notify_schedule></notify_schedule>
  <what_query>golf || golfing || cycling || tennis || walk || run || row ...</what_query>
  <where_query>san diego</where_query>
  <total_items>21</total_items>
  <page_size>10</page_size>
  <page_count>3</page_count>
  <page_number>1</page_number>
  <page_items>10</page_items>
  <first_item>1</first_item>
  <last_item>10</last_item>
  <events>
    <event id="E0-001-000500913-9">
      <title>Rock Climbing at Vertical Hold</title>
      <description>...</description>
      <start_time>2005-11-30 19:00:00</start_time>
      <stop_time></stop_time>
      <venue_id>V0-001-000150929-7</venue_id>
      <venue_name>Vertical Hold</venue_name>
      <venue_display>1</venue_display>
      <venue_address>9580 Distributuon Ave
San Diego, CA 92121</venue_address>
      <city_name>La Jolla</city_name>
      <region_name>California</region_name>
      <region_abbr>California</region_abbr>
      <postal_code></postal_code>
      <country_name>United States</country_name>
      <all_day>0</all_day>
      <search_rank></search_rank>
      <latitude></latitude>
      <longitude></longitude>
      <geocode_type></geocode_type>
      <trackback_count>0</trackback_count>
      <calendar_count>2</calendar_count>
      <comment_count>0</comment_count>
      <link_count>1</link_count>
      <created>2005-11-16 10:04:46</created>
      <image>
        <url>http://images.evdb.com/images/medium/E0-001/000/500/913-9.jpg</url>
        <width>47</width>
        <height>48</height>
        <caption></caption>
      </image>
      <deleted>0</deleted>
      <timezone></timezone>
      <modified>2005-11-16 10:06:01</modified>
      <privacy>1</privacy>
      <feeds></feeds>
      <calendars>
        <calendar id="C0-001-000002628-3"></calendar>
        <calendar id="C0-001-000002341-7"></calendar>
      </calendars>
    </event>
  </events>
  <groups></groups>
  <feeds></feeds>
  <tags>
    <tag id="biking">
      <title>biking</title>
      <owner>dano</owner>
    </tag>
    <tag id="cycling">
      <title>cycling</title>
      <owner>dano</owner>
    </tag>
  </tags>
</calendar>

Error Codes

This method may return these errors in an error document:

Authentication error: The specified user was not found or provided invalid credentials.
Missing parameter: The 'id' parameter is mandatory.
Not found: There is no calendar with that identifier.
Access denied: User 'username' does not have permission to view calendar 'id'

Eventful

Overview

Tools