Happening @ Michigan Event Feeds

Basics

We offer 3 types of feeds for public consumption. RSS, iCal, and JSON.

We also offer a spreadsheet download in CSV format.

All listing pages can be consumed as one of these types by simply appending a slash and the type you want to the listing page. For example:
Today's events: http://events.umich.edu/day
As JSON: http://events.umich.edu/day/json?v=2
As RSS: http://events.umich.edu/day/rss

We also offer a feed of specific event occurrences by passing the event ID, occurrence ID and feed/json, feed/ical, or feed/rss to the end of the URL. For example:
Single event JSON feed: http://events.umich.edu/event/17220-1200566/feed/json
The eventID-occurrenceID value is provided in listing feeds and described in more detail in the JSON Object Description below

Filtering Listings

The easiest way to filter listings is to go to a listing page on the site, select the filters you want and then click the appropriate feed link at the bottom of the filters. This will generate a feed URL with your current filters set. However the listings on the site only show locations, tags, etc that have events listed for them. We offer a list of all available types, tags, and locations used on the site here: Event Metadata. Click the link to the right on this list to view a preview of the events you will receive.

If you want to generate a feed manually, append a slash and a feed type as before and then send a ?filter= get parameter. Each filter type is sent with a colon and then a comma separated list of the ids you wish to filter by. For example:
JSON feed of all upcoming events with a type of "Audition": http://events.umich.edu/list/json?filter=types:1&v=2

Available Filter Types

  • sponsors: (Numeric Sponsor ID)
  • tags: (URL-escaped tag name)
  • locations: (Numeric Location ID)
  • types: (Numeric Event Type ID)
  • show: (new or featured)

Hiding Specific Events

Reoccurring event occurrences are shown as separate items in each listing and feed. If you would like you can only show the first occurrence of each reoccurring event and hide all the rest. This is useful for getting a notice of a new exhibition, but not cluttering your data with every single occurrence.

Pass a get filter of show:new to show only the first occurrence. For example:
A JSON feed of all upcoming events, showing only the first occurrence: http://events.umich.edu/list/json?filter=show:new&v=2

You can also choose to show only featured events that have been hand curated by the Happening @ Michigan staff. For example:
An RSS feed of all upcoming featured events: http://events.umich.edu/list/rss?filter=show:feature

Specifying Date Ranges

On the list page you can manually select events within a date range by passing the ?range=STARTtoEND get parameter. For example:
A JSON feed of events from 2014-07-01 to 2014-07-15: http://events.umich.edu/list/json?filter=all&range=2014-07-01to2014-07-15&v=2

Limits on Results

By default any feed will return a maximum of 200 results. If you would like to change the number of results you get pass the ?max-results parameter.
To get the next set of results pass the ?page parameter.

Examples:
The next 100 occurrences: https://events.umich.edu/list/json?v=2&max-results=100
Occurrences 101-200: https://events.umich.edu/list/json?v=2&max-results=100&page=2

Combining Filters

Remember, you can combine all of these filters to create very specific feeds tailored to your needs.

If you combine different filter types you will only get events that contain all of those types. For example:
RSS feed of all upcoming events by group "School of Music, Theater, and Dance" and tagged "dance": http://events.umich.edu/list/rss?filter=tags:dance,sponsors:155

If you combine the same filter type you will get all events that match any filter. For example:
JSON feed of all upcoming events at "Nichols Arboretum" or "North Quad": http://events.umich.edu/list/json?filter=locations:555,553&v=2

Finding Available Filters Programatically

You may want to be able to present a list of currently used keywords, locations, etc for your group on your website. We offer the ability to get a JSON feed of the available filters for any query. To use this simply go to http://events.umich.edu/list/metadata/json?v=2 and you will see all available filters that have active events.

You can filter this list of filters the same way as filtering an event feed. Simply append the same filter string from the listing page to the URL. For example: http://events.umich.edu/list/metadata/json?v=2&filter=sponsors:155 Shows a list of available filters for the School of Music group.

This JSON object contains an array for each type of filter containing all the available items for that filter type. Each of these is an object containing three properties.

  • id: The actual filter value you want to pass to a filter query for listings
  • occurrences: A count of how many occurrences will match the filter query if this filter is added
  • name: A more user-friendly displayable name for this filter

JSON Object Description

JSON feeds are offered in 2 versions. Just appending /json will give you version 1 which organizes the results as child objects of a parent object result. Adding an additional get parameter of ?v=2 will give you version 2 which organizes the results as objects of a parent array result set.

Example of Version 1 JSON feed: https://events.umich.edu/day/json

Example of Version 2 JSON feed: https://events.umich.edu/day/json?v=2

When requesting a JSON feed, you will receive an array as the result. Each element is an object with properties corresponding to event information. The id property is the numeric event ID concatenated with a dash and the numeric occurrence ID. For example:
11111-2222222
Where 11111 is the event ID, and 2222222 is the occurrence ID.

This object then contains the following properties and values:

  • id: The unique ID of the occurrence
  • datetime_modified: YYYYMMDDTHHMMSS, the last time anything on this event was modified
  • datetime_start: YYYYMMDDTHHMMSS, the date and time this occurrence of the event begins
  • datetime_end: YYYYMMDDTHHMMSS, the date and time this occurrence of the event ends
  • has_end_time: 1 or 0, true or false if the event has an end time
  • date_start: YYYY-MM-DD, the date this occurrence of the event begins (mySQL format)
  • date_end: YYYY-MM-DD, the date this occurrence of the event ends (mySQL format)
  • time_start: HH:MM:SS, the time this occurrence of the event begins (24 hour format)
  • time_end: HH:MM:SS, the time this occurrence of the event ends (24 hour format)
  • time_zone: Event's timezone, currently these are always America/New_York
  • event_title: The event's title
  • occurrence_title: This field has been deprecated
  • combined_title: The event's title
  • event_subtitle: The event's subtitle, this is optional and may be blank
  • event_type: The name of the event type for this event
  • event_type_id: The numeric ID of the event type for this event
  • description: The event's description
  • occurrence_notes: Any notes for the occurrence, this is optional and may be blank
  • guid: A guaranteed unique ID for this event's occurrence
  • permalink: A permalink to the event on the Happening @ Michigan website
  • building_id: The numeric building ID for the location of this occurrence
  • building_name: The building name for the location of this occurrence
  • campus_maps_id: The numeric building ID for the location of this occurrence used on the campus maps website
  • campus_maps_link_path: The name of the building used in the URL path on the Student Life Maps website
  • campus_maps_link: A link to the building on the Student Life Maps website
  • room: The room name for the location of this occurrence, this is optional and may be blank
  • location_name: A string version of the location, if this occurrence is assigned to a building it will be the building name, otherwise a custom location will be shown here
  • has_livestream: true / false, this occurrence has livestream information
  • livetream_require_login: true / false, this livestream info is only available at the permalink above after logging in
  • livestream_id: The numeric ID of the livestream (Only present if there is a livestream and it is available without logging in)
  • livestream_password: The password of the livestream (Only present if there is a password, livestream information and it is available without logging in)
  • livestream_link: A link to the livestream (Bluejeans will include the password in the link, Zoom will not and only present if there is livestream information and it is available without logging in)
  • cost: Any costs associated with attending this event, this is optional and may be blank
  • tags: An array of strings, the tags that are attached to this event
  • website: The first website link for this event
  • sponsors: An array of sponsor objects listing the sponsors for this event. Each sponsor object has the properties: group_name, group_id, and website
  • maizepages_import: If this event was imported from Maize Pages, this property will appear and give information about the event on Maize Pages. The object has the properties: maizepages_event_id, maizepages_group_id, and maizepages_group_name
  • image_url: A link to the full size image attached to this event, this is optional and may be blank
  • image_description: The textual description of the image, useful for accessibility, this is optional and may be blank
  • styled_images: If the event has an image, this contains an object with links to each cropped / scaled format of the image we use on the site. Inside this object are keys with the filter name and the value of each key is a link to the image.
  • occurrence_count: A count of how many occurrences the event has
  • first_occurrence: The ID of the event's first occurrence

Field Formatting

We do allow italicized text on three fields: event_title, event_subtitle, and description. Italicized text is stored in the Markdown format of *asterisks* around the text to be italicized. If you wish to allow italicized text like we do for event display you have two options.

The first is you can handle the conversion yourself. Simply replace the asterisks with <em> tags when displaying events on your end.

Here is the Regular Expression we use for the replacement:

/(\*.*\*)/Umg

The other option is you can request your feed to be output as HTML by appending &html_output=true to your feed request URL. For example: https://events.umich.edu/day/json?v=2&html_output=true

Note first that this output will also convert inline (https://events.umich.edu) links to have <a> tags around them as well to make them clickable and convert newlines to <br> tags and second that this mode only works in v2 of the JSON feeds.

Field HTML

If you are using HTML Output by passing &html_output=true any HTML that a user enters into a field will be converted to their entities (&lt; and &gt;) and not be valid HTML in this mode. We then run our specific conversions (italicizing, newlines, clickable links) and those are the only tags (<em>, <br>, <a>) you can expect from the output in this mode.

If you are NOT using HTML output but your display is used in a browser or renders HTML we do not do any conversion or replacement of HTML in description or other fields and you should take precaution on your display of events to ensure that someone cannot inject unintended HTML into your display.

Feed Usage

We encourage anyone to use our event data to list events on their website. A link back to Happening @ Michigan (http://events.umich.edu) is encouraged, but not required.

If you use a textual feed like iCal or RSS, please cache the results on your server and update them periodically using the last modified date.

You may request the JSON feed without caching to drive an event listing on your website on each request, but please be aware that certain listings and filters allow you to return very large event data sets and some feed requests may take several seconds to load. In this case it may be better for you and us to also cache event data on your server and update based on last modified dates.

Sample Code

If you would like to see an example of a JSON feed being loaded in action you can do so here. This page loads the feed for today's events and displays them. View the source code.

Michigan Creative has created a wordpress widget for loading events from the calendar. UMich Events Widget