|
|
eo2 provides a number of services for interacting with public, published calendar data. The most important service is the XML API. It is what forms the back bone all the other services. Additionally there is a general RSS service and a USC Today service. The later provides an RSS feed of feature candidate events and can be used to select feature candidate events from University Park Campus or Health Sciences Campus. There is also a generic and themed calendar display support for all public calendars (see http://web-app.usc.edu/ws/eo2/calendars).
The web server provides its own on-line help at http://web-app.usc.edu/ws/eo2/help. Help includes an explanation of the eo2 services available.
eo2 provides a generic calendar view. You can see a list of calendars available and from their see a generic view individual calendars. The calendar list page includes links to the iCal version of the calendar as well as the RSS feed version.
If a theme has been implemented in APP_PATH/themes/CALENDAR_ID for the calendar then that would be used in lieu of the generic calendar view. A good starting point is to look at /info/www/ws/eo2/themes/32/*.php on web-app.usc.edu (i.e. http://web-app.usc.edu/ws/eo2/calendar/32) which is the first theme implemented in the new system. /info/www/ws/eo2/themes/32/page.php will select based on the restful URI requested an approach file to include (e.g. list.php, event.php, sports.php). Each included file in turn then traverses $_VIEW for the information it needs to render the content properly.
The eo2 XML API seeks to provide a flexible service for retrieving calendar meta data, event lists and event data. It is a RESTS driven service returning XML content. To use the server you would retrieve the XML content via http with a URL like http://web-app/ws/eo2/xml/32/list. This API only provides access to public, published events from publicly visible calendars. Many examples in the xml api can be rendered as HTML via themed interfaces.
You need to know the numeric calendar id of the calendar you wish to access. E.g. 32 is the USC Public Events Calendar.
| Task | iCal | Calendar view | Notes |
|---|---|---|---|
| Retrieving a list of categories available for the USC Public Events Calendar | http://web-app.usc.edu/ws/eo2/xml/32/categories | ||
| Retrieving a list of events available from the USC Public Events Calendar | http://web-app.usc.edu/ws/eo2/xml/32/list | http://web-app.usc.edu/ws/eo2/calendar/32/list | |
| Retrieving a specific event (e.g. Event ID: 861856) | http://web-app.usc.edu/ws/eo2/xml/32/event/861856 | http://web-app.usc.edu/ws/eo2/calendar/32/event/861856 | |
| Retrieving events for first quarter 2008 | http://web-app.usc.edu/ws/eo2/xml/32/list/20080101—20080331 | http://web-app.usc.edu/ws/eo2/calendar/32/list/20080101—20080331 | The date range is separated by a ‘—’ and the date format needs to be urlencoded. The way of specifying a date is based on what is support by PHP’s strtotime function. |
| Retrieving events for the coming week | http://web-app.usc.edu/ws/eo2/xml/32/list/today—1+week | http://web-app.usc.edu/ws/eo2/calendar/32/list/today—1+week | |
| Retrieving a list of events with the search term “Music” | http://web-app.usc.edu/ws/eo2/xml/32/search/Music | http://web-app.usc.edu/ws/eo2/calendar/32/search/Music | |
| Retrieving a list of events at Bovard | http://web-app.usc.edu/ws/eo2/xml/32/location/Bovard | http://web-app.usc.edu/ws/eo2/calendar/32/location/Bovard | |
| Retrieving a list of featured events from the USC Public Events Calendar | http://web-app.usc.edu/ws/eo2/xml/32/feature/2819 | http://web-app.usc.edu/ws/eo2/calendar/32/feature/2819 |
The RSS API is very similar to the xml api except that results are formatted as an RSS feed and it only supports event list retrieval. The links back to the vent detail points at the generic calendar interface.
You need to know the numeric calendar id of the calendar you wish to access. E.g. 32 is the USC Public Events Calendar.
eo2 provides JSON content via the json.php interface. It works much the same way as the XML API but returns JSON formmated content instead of XML.
eo2 provides iCal content via the ics interface. It works much the same way as the XML API but returns iCal formatted content instead of XML. Currently iCal support only supports lists of events. iCal support for individual events will be added in the future.
| Task | iCal | Calendar view | Notes |
|---|---|---|---|
| Retrieving a list of events available from the USC Public Events Calendar | http://web-app.usc.edu/ws/eo2/ics/32/list | http://web-app.usc.edu/ws/eo2/calendar/32/list | |
| Retrieving a specific event (e.g. Event ID: 861856) | http://web-app.usc.edu/ws/eo2/ics/32/event/861856 | http://web-app.usc.edu/ws/eo2/calendar/32/event/861856 | |
| Retrieving events for first quarter 2008 | http://web-app.usc.edu/ws/eo2/ics/32/list/20080101—20080331 | http://web-app.usc.edu/ws/eo2/calendar/32/list/20080101—20080331 | The date range is separated by a ‘—’ and the date format needs to be urlencoded. The way of specifying a date is based on what is support by PHP’s strtotime function. |
| Retrieving events for the coming week | http://web-app.usc.edu/ws/eo2/ics/32/list/today—1+week | http://web-app.usc.edu/ws/eo2/calendar/32/list/today—1+week | |
| Retrieving a list of events with the search term “Music” | http://web-app.usc.edu/ws/eo2/ics/32/search/Music | http://web-app.usc.edu/ws/eo2/calendar/32/search/Music | |
| Retrieving a list of events at Bovard | http://web-app.usc.edu/ws/eo2/ics/32/location/Bovard | http://web-app.usc.edu/ws/eo2/calendar/32/location/Bovard | |
| Retrieving a list of featured events from the USC Public Events Calendar | http://web-app.usc.edu/ws/eo2/ics/32/feature/2819 | http://web-app.usc.edu/ws/eo2/calendar/32/feature/2819 |
The USC Today RSS feed provides a subset of events by calendar. It only shows events which have the feature candidate field set to true. You can optionally add an additional restriction for the list to be specific to the UPC and HSC campus.
You need to know the numeric calendar id of the calendar you wish to access. E.g. 32 is the USC Public Events Calendar.
If you have many events being returned with one query it may fail. This is the case of more then three months of events at a time with the USC Public Events Calendar. The historical events are available but you will need to request in smaller sets. This primarily effected the Archive link on the generic view of the calendars and was the reason that link was removed. If you wish to use a date range that could return a large number of events then you should test it first before you include that as a feature in your design.