Why use widgets rather than XML?
Most people need basically the same types of widgets. So rather than everyone building their own, Web Services does it for them. We have direct access to query the database for events that have changed. In addition, widgets are static content and do not pull data every time a person accesses a web page.
Why limit XML data requests?
XML is generic data that is dynamically pulled; it is not static. There are server costs for us when users pull data, therefore we limit the number of simultaneous web requests. If the limit is reached an HTTP 503 error code is sent along with a message.
Do we provide a way for importing events?
No. The Calendar is intended to be used as a marketing tool, and it is often used by stakeholders who have no marketing background. As such, robust calendar management--choosing appropriate and consistent tags, event types, location and sponsor information, etc.--is essential to the success of events. In other words, we don't want people just dumping their events into the calendar system.
How can we avoid entering events more than once?
We recommend having individuals enter events into our calendar system. Then, pull the events out using the XML web data feeds so that you can integrate them back into your calendar system. Since we ask users for more information than most calendar systems, you have more control over how events appear within your current calendars.
The current Calendar XML schema can be found here:
https://xml.calendars.illinois.edu/calendarws16.xsd
The deprecated Calendar XML schemas can be found here:
https://xml.calendars.illinois.edu/calendarws15.xsd (this is not supported after 8/1/2022)
How long will unsupported schemas and URLs be supported?
Unsupported versions of the schema and URLs will continue to work until the next newer version of the schema is released. We never maintain more than one past version of the schema and URLs. We also only answer questions related to the newest version of the schema or URLs.
How to receive notifications of service changes?
We notify the CCSP listserv when changes are made to the Calendar XML. When changes are made we will push out a new schema and new URLs. These will have a new version number so that users can continue to use the prior version prior to upgrading. We try to provide a six-week window from when we push out new changes until we turn off old URLs.
In the Calendar XML data we provide two important parameters, /responseWS/deprecated and /responseWS/endOfServiceDate . If the value of deprecated is true then this should alert the developers that a newer version of the schema needs to be used. If the endOfServiceDate contains a date then this will tell you when this query will return a 404 HTML error.
How to access the XML?
In order to access the XML URLs, you have to register your IP address with Web Services. To do this fill out the Contact Us form found at the bottom of the Webtools portal. Please send us a production, test, and development IP addresses. If you don't have a minimum of a test and production server then you will not be given access to the XML data.
How do you do specific searching?
Using the "search" tab from the public calendar web interface you will notice that there are many web parameters used when searching. None of these parameters are required.
search
EventType
KEYWORDS
startDate (this value defaults to the current time)
endDate
Any of these parameters can be added to the web query "/calendar/eventXML#/#.xml" in order to filter the results. The web parameter "searchEventType" can be used more than once. Below are examples of searching. You will notice that the slash that separates the elements of a date are HTML escaped with %2F. You will also notice that the month and day are always two numbers.
Schema 16 - example web queries
https://xml.calendars.illinois.edu/eventXML16/7.xml
https://xml.calendars.illinois.edu/eventXML16/7.xml?pageNumber=0
https://xml.calendars.illinois.edu/eventXML16/7.xml?startDate=07%2F01%2F2020&pageNumber=0
https://xml.calendars.illinois.edu/eventXML16/7.xml?startDate=07%2F01%2F2020&endDate=07%2F23%2F2020&pageNumber=0
Schema 15 (this is not supported after 8/1/2022)
https://xml.calendars.illinois.edu/eventXML15/7.xml?startDate=07%2F01%2F2020&endDate=07%2F23%2F2020
How do you page through the results of a web query?
Generating events, like all data processing, has CPU, memory and other types of costs associated with it. In order to provide a reasonable service, we only return a limited list of events per web query. To page through the results, add a pageNumber web parameter starting with 0 for the first page. If pageNumber is left off it will default to page 0. When you receive the results look at the element in the XML "/responseWS/maxPageSize". This will tell you the max events that can be returned with a web query. If the events returned is less than maxPageSize then don't send additional web requests. If the number of events is equal to this value then increment the pageNumber and requery for additional events.
