The HarvardEvents API allows you to request data programmatically HarvardEvents in CSV, iCalendar, JSON, JSONP, serialized PHP, RSS, or XML format. The API provides a RESTful interface, which means that you can query it using simple HTTP GET requests.

HarvardEvents knows about events from 2009-05-27 onward. New events (or changes to old events) may take up to 24 hours to appear in HarvardEvents’s database.

Author

To report bugs or request features, contact:

License

Use of this API is governed by a Creative Commons Attribution-Noncommerical 3.0 Unported license, which means that you may use its data for non-commercial purposes so long as you attribute your data to this API, as by including a link to HarvardEvents in your own work. For approval of commercial purposes, contact the author.

Methods

All methods support CORS.

calendars

To query the HarvardEvents API for calendars, contact the server via URLs in this format:

http://events.cs50.net/api/1.0/calendars?param1=value1&param2=value2&...

Supported parameters include:

parameter description

id

Optional. Comma-separated list of calendar IDs. Only calendars with these IDs will be returned.

campus

Optional. Comma-separated list of campus IDs. Only calendars for these campuses will be returned.

output

Required. Format for output. Must be csv, json, jsonp, php, or xml.

If any parameters are malformed or any required parameters are omitted, an empty response will be returned along with, possibly, HTTP status code 400 Bad Request.

In a future version of this API, campuses' IDs may be returned in a different manner.

CSV

If you request data in CSV format (e.g., http://events.cs50.net/api/1.0/calendars?id=128&output=csv), the response will be a series of comma-delimited rows, per the below:

id,calname,campus
128,"CS50 Events","COL,DCE,GSAS,GSE,HBS,HDS,HLS,HMS,HSDM,HSPH,SEAS"

Note that the response’s first row defines the CSV file’s fields. Fields' order may change over time, so do not hardcode indices into your own code. Use that first row to determine fields' indices dynamically, per this article on parsing CSV.

JSON

If you request data in JSON format (e.g., http://events.cs50.net/api/1.0/calendars?id=128&output=json), the response will be an array of objects, per the below:

[
   {
      "id":"128",
      "calname":"CS50 Events",
      "campus":"COL,DCE,GSAS,GSE,HBS,HDS,HLS,HMS,HSDM,HSPH,SEAS"
   }
]

JSONP

If you request data in JSONP format (e.g., http://events.cs50.net/api/1.0/calendars?id=128&output=jsonp&callback=parseResponse), the response will be a padded array of objects, per the below:

parseResponse([{"id":"128","calname":"CS50 Events","campus":"COL,DCE,GSAS,GSE,HBS,HDS,HLS,HMS,HSDM,HSPH,SEAS"}])

PHP

If you request data in (serialized) PHP format (e.g., http://events.cs50.net/api/1.0/calendars?id=128&output=php), the response will be a serialized array of associative arrays, per the below:

a:1:{i:0;a:3:{s:2:"id";s:3:"128";s:7:"calname";s:11:"CS50 Events";s:6:"campus";s:47:"COL,DCE,GSAS,GSE,HBS,HDS,HLS,HMS,HSDM,HSPH,SEAS";}}

Once you unserialize that response, you’ll have the below in memory:

Array
(
    [0] => Array
        (
            [id] => 128
            [calname] => CS50 Events
            [campus] => COL,DCE,GSAS,GSE,HBS,HDS,HLS,HMS,HSDM,HSPH,SEAS
        )

)

XML

If you request data in XML format (e.g., http://events.cs50.net/api/1.0/calendars?id=128&output=xml), the response will be an XML document whose root element is calendars, each of whose children is an calendar, per the below:

<?xml version="1.0" encoding="UTF-8"?>
<calendars>
  <calendar>
    <id>128</id>
    <calname>CS50 Events</calname>
    <campus>COL,DCE,GSAS,GSE,HBS,HDS,HLS,HMS,HSDM,HSPH,SEAS</campus>
  </calendar>
</calendars>

campuses

To query the HarvardEvents API for campuses, contact the server via URLs in this format:

http://events.cs50.net/api/1.0/campuses?param1=value1&param2=value2&...

Supported parameters include:

parameter description

output

Required. Format for output. Must be csv, json, jsonp, php, or xml.

If any parameters are malformed or any required parameters are omitted, an empty response will be returned along with, possibly, HTTP status code 400 Bad Request.

CSV

If you request data in CSV format (e.g., http://events.cs50.net/api/1.0/campuses?output=csv), the response will be a series of comma-delimited rows, per the below:

id
COL
DCE
GSAS
GSD
GSE
HBS
HDS
HKS
HLS
HMS
HSDM
HSPH
SEAS

Note that the response’s first row defines the CSV file’s fields. Fields' order may change over time, so do not hardcode indices into your own code. Use that first row to determine fields' indices dynamically, per this article on parsing CSV.

JSON

If you request data in JSON format (e.g., http://events.cs50.net/api/1.0/campuses?output=json), the response will be an array of objects, per the below:

[
   {
      "id":"COL"
   },
   {
      "id":"DCE"
   },
   {
      "id":"GSAS"
   },
   {
      "id":"GSD"
   },
   {
      "id":"GSE"
   },
   {
      "id":"HBS"
   },
   {
      "id":"HDS"
   },
   {
      "id":"HKS"
   },
   {
      "id":"HLS"
   },
   {
      "id":"HMS"
   },
   {
      "id":"HSDM"
   },
   {
      "id":"HSPH"
   },
   {
      "id":"SEAS"
   }
]

JSONP

If you request data in JSONP format (e.g., http://events.cs50.net/api/1.0/campuses?output=jsonp&callback=parseResponse), the response will be a padded array of objects, per the below:

parseResponse([{"id":"COL"},{"id":"DCE"},{"id":"GSAS"},{"id":"GSD"},{"id":"GSE"},{"id":"HBS"},{"id":"HDS"},{"id":"HKS"},{"id":"HLS"},{"id":"HMS"},{"id":"HSDM"},{"id":"HSPH"},{"id":"SEAS"}])

PHP

If you request data in (serialized) PHP format (e.g., http://events.cs50.net/api/1.0/campuses?output=php), the response will be a serialized array of associative arrays, per the below:

a:13:{i:0;a:1:{s:2:"id";s:3:"COL";}i:1;a:1:{s:2:"id";s:3:"DCE";}i:2;a:1:{s:2:"id";s:4:"GSAS";}i:3;a:1:{s:2:"id";s:3:"GSD";}i:4;a:1:{s:2:"id";s:3:"GSE";}i:5;a:1:{s:2:"id";s:3:"HBS";}i:6;a:1:{s:2:"id";s:3:"HDS";}i:7;a:1:{s:2:"id";s:3:"HKS";}i:8;a:1:{s:2:"id";s:3:"HLS";}i:9;a:1:{s:2:"id";s:3:"HMS";}i:10;a:1:{s:2:"id";s:4:"HSDM";}i:11;a:1:{s:2:"id";s:4:"HSPH";}i:12;a:1:{s:2:"id";s:4:"SEAS";}}

Once you unserialize that response, you’ll have the below in memory:

Array
(
    [0] => Array
        (
            [id] => COL
        )

    [1] => Array
        (
            [id] => DCE
        )

    [2] => Array
        (
            [id] => GSAS
        )

    [3] => Array
        (
            [id] => GSD
        )

    [4] => Array
        (
            [id] => GSE
        )

    [5] => Array
        (
            [id] => HBS
        )

    [6] => Array
        (
            [id] => HDS
        )

    [7] => Array
        (
            [id] => HKS
        )

    [8] => Array
        (
            [id] => HLS
        )

    [9] => Array
        (
            [id] => HMS
        )

    [10] => Array
        (
            [id] => HSDM
        )

    [11] => Array
        (
            [id] => HSPH
        )

    [12] => Array
        (
            [id] => SEAS
        )

)

XML

If you request data in XML format (e.g., http://events.cs50.net/api/1.0/campuses?output=xml), the response will be an XML document whose root element is campuses, each of whose children is a campus, per the below:

<?xml version="1.0" encoding="UTF-8"?>
<campuses>
  <campus>
    <id>COL</id>
  </campus>
  <campus>
    <id>DCE</id>
  </campus>
  <campus>
    <id>GSAS</id>
  </campus>
  <campus>
    <id>GSD</id>
  </campus>
  <campus>
    <id>GSE</id>
  </campus>
  <campus>
    <id>HBS</id>
  </campus>
  <campus>
    <id>HDS</id>
  </campus>
  <campus>
    <id>HKS</id>
  </campus>
  <campus>
    <id>HLS</id>
  </campus>
  <campus>
    <id>HMS</id>
  </campus>
  <campus>
    <id>HSDM</id>
  </campus>
  <campus>
    <id>HSPH</id>
  </campus>
  <campus>
    <id>SEAS</id>
  </campus>
</campuses>

events

To query the HarvardEvents API for events, contact the server via URLs in this format:

http://events.cs50.net/api/1.0/events?param1=value1&param2=value2&...

Supported parameters include:

parameter description

calendar

Optional. Comma-separated list of calendars' IDs. Only events from these calendars will be returned.

callback

Required iff output is `jsonp`. Callback function with which response will be padded.

campus

campuses' IDs]]. Valid values include COL, DCE, GSAS, GSD, GSE, HBS, HDS, HKS, HLS, HMS, HSDM, HSPH, and SEAS.

dtend

Optional. An end date/time in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format, where HH is in 24-hour time. (Don’t overlook the T between YYYY-MM-DD and HH:MM:SS in the latter.) Events happening before or on this date/time will be returned. If omitted, YYYY-MM-DDT00:00:00 will be assumed, where YYYY-MM-DD is tomorrow.

dstart

Optional. A start date/time in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format, where HH is in 24-hour time. (Don’t overlook the T between YYYY-MM-DD and HH:MM:SS in the latter.) Events happening on or after this date/time will be returned. If omitted, YYYY-MM-DDT00:00:00 will be assumed, where YYYY-MM-DD is today.

output

Required. Format for output. Must be csv, json, jsonp, php, rss, or xml.

q

Optional. Query string. Only events whose summary, description, or calendar’s name contain the string will be returned. Be sure to URL-encode this parameter’s value (as with PHP’s urlencode).

tag

Optional. Comma-separated list of tags. Only events with at least one of these tags will be returned.

If any parameters are malformed or any required parameters are omitted, an empty response will be returned along with, possibly, HTTP status code 400 Bad Request.

CSV

If you request events in CSV format (e.g., http://events.cs50.net/api/1.0/events?calendar=128&dtstart=2010-12-10&output=csv), the response will be a series of comma-delimited rows, whereby Description, if double-quoted, may very well contain \n (i.e., ASCII code 0x0a), per the below:

Subject,"Start Date","Start Time","End Date","End Time","All day event",Description,Location
"CS50 Fair",12/10/2010,11:00,12/10/2010,16:30,False,"The CS50 Fair is a campus-wide exhibition of 300+ students' final projects. On display will be Android Apps, BlackBerry Apps, Facebook Apps, Firefox Add-Ons, Games, iPhone Apps, Tools, Websites, and more, all made by students.

Come see friends' final projects.

Come chat with recruiters.

Win amazing prizes.

Squeeze a CS50 Stress Ball.

Eat popcorn and candy.

Come to the CS50 Fair. Come experience CS50.

All of Harvard welcome.

This is CS50.
http://www.cs50.net/","Northwest Science Labs"

Note that the response’s first row defines the CSV file’s fields. Fields' order may change over time, so do not hardcode indices into your own code. Use that first row to determine fields' indices dynamically, per this article on parsing CSV.

Because Description contain \n, be sure to parse the CSV properly, as with PHP’s fgetcsv.

iCalendar

If you request tweeters in iCalendar format (e.g., http://events.cs50.net/api/1.0/events?calendar=128&dtstart=2010-12-10&output=ics), the response wil be an iCalendar feed, per the below:

BEGIN:VCALENDAR
METHOD:PUBLISH
PRODID:-//216.38.51.62//NONSGML iCalcreator 2.6//
VERSION:2.0
X-WR-CALNAME:HarvardEvents
X-WR-TIMEZONE:America/New_York
BEGIN:VEVENT
UID:4078
DTSTAMP:20101124T035445Z
DESCRIPTION:The CS50 Fair is a campus-wide exhibition of 300+ students' fin
 al projects. On display will be Android Apps\, BlackBerry Apps\, Facebook
 Apps\, Firefox Add-Ons\, Games\, iPhone Apps\, Tools\, Websites\, and more
 \, all made by students.\n\nCome see friends' final projects.\n\nCome chat
  with recruiters.\n\nWin amazing prizes.\n\nSqueeze a CS50 Stress Ball.\n
 \nEat popcorn and candy.\n\nCome to the CS50 Fair. Come experience CS50.\n
 \nAll of Harvard welcome.\n\nThis is CS50.\nhttp://www.cs50.net/
DTSTART:20101210T110000
DTEND:20101210T163000
LOCATION:Northwest Science Labs
SUMMARY:CS50 Fair
END:VEVENT
END:VCALENDAR

JSON

If you request data in JSON format (e.g., http://events.cs50.net/api/1.0/events?calendar=128&dtstart=2010-12-10&output=json), the response will be an array of objects, per the below:

[
   {
      "summary":"CS50 Fair",
      "dtstart":"2010-12-10T11:00:00",
      "dtend":"2010-12-10T16:30:00",
      "location":"Northwest Science Labs",
      "description":"The CS50 Fair is a campus-wide exhibition of 300+ students' final projects. On display will be Android Apps, BlackBerry Apps, Facebook Apps, Firefox Add-Ons, Games, iPhone Apps, Tools, Websites, and more, all made by students.\n\nCome see friends' final projects.\n\nCome chat with recruiters.\n\nWin amazing prizes.\n\nSqueeze a CS50 Stress Ball.\n\nEat popcorn and candy.\n\nCome to the CS50 Fair. Come experience CS50.\n\nAll of Harvard welcome.\n\nThis is CS50.\nhttp:\/\/www.cs50.net\/",
      "calname":"CS50 Events",
      "calendar":{
         "id":"128",
         "calname":"CS50 Events"
      }
   }
]

JSONP

If you request data in JSONP format (e.g., http://events.cs50.net/api/1.0/events?calendar=128&dtstart=2010-12-10&output=jsonp&callback=parseResponse), the response will be a padded array of objects, per the below:

parseResponse([{"summary":"CS50 Fair","dtstart":"2010-12-10T11:00:00","dtend":"2010-12-10T16:30:00","location":"Northwest Science Labs","description":"The CS50 Fair is a campus-wide exhibition of 300+ students' final projects. On display will be Android Apps, BlackBerry Apps, Facebook Apps, Firefox Add-Ons, Games, iPhone Apps, Tools, Websites, and more, all made by students.\n\nCome see friends' final projects.\n\nCome chat with recruiters.\n\nWin amazing prizes.\n\nSqueeze a CS50 Stress Ball.\n\nEat popcorn and candy.\n\nCome to the CS50 Fair. Come experience CS50.\n\nAll of Harvard welcome.\n\nThis is CS50.\nhttp:\/\/www.cs50.net\/","calname":"CS50 Events","calendar":{"id":"128","calname":"CS50 Events"}}])

RSS

If you request events in RSS format (e.g., http://events.cs50.net/api/1.0/events?calendar=128&dtstart=2010-12-10&output=rss), the response will be an RSS feed, whereby description will contain CDATA (which, in turn, can contain XHTML), per the below:

<?xml version="1.0" encoding="utf-8" ?>
<rss version='2.0'>
  <channel>
    <title>HarvardEvents</title>
    <description></description>
    <link>
    http://events.cs50.net/api/1.0/new?calendar=128&amp;dtstart=2010-12-10&amp;output=rss</link>
    <item>
      <guid>http://events.cs50.net/4078</guid>
      <title>CS50 Fair</title>
      <link>http://events.cs50.net/4078</link>
      <description>
        <![CDATA[<p><b>Where:</b> Northwest Science Labs</p><p><b>What:</b> The CS50 Fair is a campus-wide exhibition of 300+ students' final projects. On display will be Android Apps, BlackBerry Apps, Facebook Apps, Firefox Add-Ons, Games, iPhone Apps, Tools, Websites, and more, all made by students.<br />

<br />
Come see friends' final projects.<br />
<br />
Come chat with recruiters.<br />
<br />
Win amazing prizes.<br />
<br />
Squeeze a CS50 Stress Ball.<br />
<br />
Eat popcorn and candy.<br />
<br />
Come to the CS50 Fair. Come experience CS50.<br />
<br />
All of Harvard welcome.<br />
<br />
This is CS50.<br />
<a href="http://www.cs50.net/" target="_blank" >http://www.cs50.net/</a></p>]]>
</description>
      <category>events</category>
      <pubDate>Fri, 10 Dec 2010 11:00:00 -0500</pubDate>
    </item>
  </channel>
</rss>

XML

If you request data in XML format (e.g., http://events.cs50.net/api/1.0/events?calendar=128&dtstart=2010-12-10&output=xml), the response will be an XML document whose root element is events, each of whose children is an event, per the below:

<?xml version="1.0" encoding="utf-8"?>
<events>
  <event>
    <summary>CS50 Fair</summary>
    <dtstart>2010-12-10T11:00:00</dtstart>
    <dtend>2010-12-10T16:30:00</dtend>
    <location>Northwest Science Labs</location>
    <description>The CS50 Fair is a campus-wide exhibition of 300+
    students' final projects. On display will be Android Apps,
    BlackBerry Apps, Facebook Apps, Firefox Add-Ons, Games, iPhone
    Apps, Tools, Websites, and more, all made by students. Come see
    friends' final projects. Come chat with recruiters. Win amazing
    prizes. Squeeze a CS50 Stress Ball. Eat popcorn and candy. Come
    to the CS50 Fair. Come experience CS50. All of Harvard welcome.
    This is CS50. http://www.cs50.net/</description>
    <calname>CS50 Events</calname>
    <calendar>
      <id>128</id>
      <calname>CS50 Events</calname>
    </calendar>
  </event>
</events>

Examples

Changelog

  • 0.9

  • 0.91

    • Added calendar IDs and CALNAMEs to CSV output of events method.

  • 1.0

    • Complete overhaul. Added support for multiple output formats.