«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»
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
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:firstname.lastname@example.org 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:
|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:
TITLE=event. Next come the
metadata for the event itself:
|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:
Google Calendar has a similar system, but it is
The base URL for adding calendar events is
There is one required parameter:
action=TEMPLATE. Here is a rundown of their
|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:
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.