|
|
The eo2 APIs will accept requests over HTTP and return vanilla HTML, XML, JSON, RSS or iCal output. The Content type is set in the header based on the request.
In the following examples, please replace [text] with the correct information for your calendar. If you do not specify a range, the API will return all results for your query.
Format of the queries start with http://web-app.usc.edu/ws/eo2/[format]/ where format is either calendar (i.e. for HTML pages), xml, json, rss, or ics (i.e. for iCal output). In the examples below we used the base URL of http://web-app.usc.edu/ws/eo2/xml
Past events will not display unless you specify a date range beginning before today. Events not listed as published will never be returned (recorded flagged as published in the current calendar implementation). Events flagged as private will not be shown.
All list queries to the Calendar API are structured in a similar fashion. If you would like include past events in a list query, simply append a date range formatted as /[date]--[date] where [date] is understood by PHP’s strtotime function. If you specify a single date, the API will return events for a single day.
/[calendar id]/today |
Events for today |
/[calendar id]/10%2F23%2F2006 |
Events for 10/23/2006 |
/[calendar id]/20061023 |
Events for 10/23/2006 |
/[calendar id]/10%2F23%2F2006-12%2F31%2F2006 |
Events for 10/23/2006 – 12/31/2006 |
/[calendar id]/20061023--20061231 |
Events for 10/23/2006 – 12/31/2006 |
/[calendar id]/today--90+day |
Events from today for the next 90 days |
/[calendar id]/-90+day--today |
Events from today for the previous 90 days |
For more fine-grained queries you can request a number of different list types.
/[calendar id]/list/categories will generate an alphabetized list of all categories used in the calendar with a count of events in each one. The output will look like this:
<event-categories>
<event-category>
<category_name>...</category_name>
<category_count>...</category_count>
</event-category>
<event-category>
...
</event-category>
<event-category>
...
</event-category>
</event-categories>
/[calendar id]/list/[range as 1-10] (Q: How do we distinguish between page or date range?)
Will return a list of events from all categories sorted chronologically.
<events>
<event>
<event-id>...</event-id>
<event-name>...</event-name>
<event-image-small>...</event-image-small>
<event-date>...</event-date>
<event-time>...</event-time>
<event-location>...</event-location>
<event-description-short>...</event-description-short>
</event>
<event>
...
</event>
</events>
/[calendar id]/list/category/[category name]
Will return a list of events in a category sorted chronologically. If you wish to limit the number of items returned you can do so with /limit/[range]
/[calendar_id]/list/category/[category name]/limit/1-3
Will return the firsts through third items (in programmer speak 0-2).
Here’s and example of the format returned.
<events>
<category>[Category]</category>
<event>
<event-id>...</event-id>
<event-name>...</event-name>
<event-image-small>...</event-image-small>
<event-date>...</event-date>
<event-time>...</event-time>
<event-location>...</event-location>
<event-description-short>...</event-description-short>
</event>
<event>
...
</event>
</events>
/[calendar id]/list/search/[query]/limit/[range as 1-10 or all]
Will return a list of results for a search query.
<events>
<search>[Search Text]</search>
<event>
<event-id>...</event-id>
<event-name>...</event-name>
<event-image-small>...</event-image-small>
<event-date>...</event-date>
<event-time>...</event-time>
<event-location>...</event-location>
<event-description-short>...</event-description-short>
</event>
<event>
...
</event>
</events>
/[calendar id]/event/[id]
Will return the full details for a specified event.
<event>
<event-id>...</event-id>
<event-name>...</event-name>
...
</event>