0.10 Info: U-M Events Calendar Feeds – The James and Anne Duderstadt Center

Text below retrieved on 2021.04.16 from https://events.umich.edu/feeds

Happening @ Michigan Event Feeds

Skip to Content HAPPENING @ MICHIGANTHE UNIVERSITY OF MICHIGAN EVENTS CALENDAR

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

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

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 (< and >) 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 About Help Terms of Use Event Feeds Import Events Contact Us