Creating events for Yahoo and Google calendars

«If I could save time in a bottle
The first thing that I'd like to do
Is to save every day
Till Eternity passes away
Just to spend them with you»

--Jim Croce

If you're anything like me, you live and die by your calendar. Over the years, I've moved from simple paper calendars to the Palm Pilot back to paper and finally ending up online with Yahoo and Google. This brief post talks about creating hyperlinks that add an event to the clicker's yahoo or google calendar.

Of course, not everyone uses these online calendars. Some use Outlook or iCal or some other desktop solution. The key to publishing events for these systems is to use the ICalendar format which most desktop apps can import. The MIME type for such an ICalendar file is text/calendar. You might also consider using the XHTML microformat hCalendar, which I mentioned briefly in an earlier post. However, this microformat isn't likely to be understood by most desktop apps.

First, let's suppose that we have an event that we want to publish. I turn 40 next year, so let's create an birthday party event for that. In the iCalendar format, such an event might look like this:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//taskboy calendar app
BEGIN:VEVENT
SUMMARY:Joe turns 40 just this once
ORGANIZER;CN=Joe Johnston:MAILTO:jjohn@taskboy.com
DTSTAMP:20100421T105300
DTSTART:20111212T190000
DTEND:20111212T200000
END:VEVENT
END:VCALENDAR

A great deal of this format is boilerplate stuff. The overall container is VCALENDAR, which has a BEGIN and END. Immediately after that is meta-information (like HTML's HEAD section) containing the format version and the app's product ID (which is arbitrary). After the header, the actual VEVENT section begins. There are many types of objects VCalendar can contain including VREPLY, VJOURNAL and VTODO, but this isn't about those (read the RFC for more info). Let's look at the VEVENT attributes in tabular form:

Attribute	Meaning
SUMMARY	A brief description of the event
ORGANIZER	Who organized this event, in LDAP format
DTSTAMP	When this ICalendar file was created
DTSTART	When this event starts
DTEND	When this event ends

The purpose these elements is relatively self-evident. The datetime format used throughout is the ever-popular ISO8601. The ORGANIZER is given in LDAP format, but the spec does not require it to be so. However, most applications, like Outlook, will attempt to locate ORGANIZER in an LDAP system, so this makes a bit of sense.

Above is a basic, serviceable ICalendar file. You can even check this using the handy ICalendar validator. Enough about the desktop. Let's move on to web-based calendars.

Yahoo Calendar does not, as far as I can see, publish an API. However, people have ferreted out enough information to be useful. By creating a simple HTTP GET request (in the form of a hyperlink), events can be entered into Yahoo Calendar.

The base URL for Yahoo Calendar is: http://calendar.yahoo.com/. The following parameters are required: v=60 and TITLE=event. Next come the metadata for the event itself:

Parameter	Meaning
DESC	A brief description of the event
ST	ISO8601 datetime of when the event begins
DUR	How long the event lasts in HHMM format
URL	A URL to a page describing the event
in_loc	A brief label for the event location
in_st	Street address of the event
in_csz	City/State/Zip of the event

Remember: all parameters must be URLencoded. There is a TYPE parameter that can specify the kind of event. The default is "Appointment" (type 10). See the link to Chris's notes for more options there. The following link will add my Birthday event to your Calendar:

Add to Yahoo

Google Calendar has a similar system, but it is documented. The base URL for adding calendar events is http://www.google.com/calendar/event. There is one required parameter: action=TEMPLATE. Here is a rundown of their parameters:

Parameter	Meaning
text	A label for the event
dates	Of the form: START/END where START and END are in ISO8601 format
name	Description of the event
details	A description of the event
location	Description of the event

These parameters need to be URLencoded too. Google differs slightly from the above formats in that the event can have both a label and a description. The start and end time of the event are given in one parameter, which is unnerving. Here's my example event for Google:

Add to Google

Because these links will not return the user to the site they came from, consider using a popup window for these links.

That's the gist of adding events to calendars. Of course, there are a lot more parameters that can be added to these publications and I haven't touched recurring events at all. Still, this is a good jumping off point for your own exploration of the magic of event scheduling.