Happening @ Michigan Event Feeds

Basics

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

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
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

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

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

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

Finding Available Filters Programatically

You may want to be able to present a list of currently used tags, 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
  • 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
  • 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
  • image_url: A link to the full size image attached to this event, 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

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