Adding Events to Users Calendars – Part 2 – Web Calendars

Part 1 of this project was to get downloads in the iCal format working so that people with desktop calendars can add events to them. Next up we want to be able to import into web calendars.

Since we’re talking about web calendars the sequence of events is a little different to with desktop calendars. Rather than having a link return a server-generated file that’s picked up by the desktop calendar, we simply point a link directly at the web calendar in question, and when the user clicks on it the data held in querystring parameters on that link is transmitted to the calendar. Sadly different calendars implement this differently, so you need to write custom formatting code for each calendar that you want to support. For that reason I’m going to stick to the biggest three, Yahoo, MSN, and Google (a possible motivation for big fish not to implement a standard URL format).

Please note that some of the following information is the product of my tinkering and may become unreliable as the companies that run these calendars make changes (if it isn’t unreliable already).

Google Calendar

Google’s instructions for publishing events are already about as simple as they can get, but I’ll summarise the basics here for the sake of completeness.

The components of my URL are:

http://www.google.com/calendar/event?	- The location of this API
action=TEMPLATE	- Don’t edit this unless you know more than me (not hard). I haven’t found any other interesting values.
text=My Event	Put the title of your event in here
dates=20080101/20080101	The start and end dates for your event (YYYYMMDD). If you want to specify an exact time instead of just the date then use YYYYMMDDTHHmmSS, e.g. 20080101T143000 would be half past two on the 1st Jan 2008. If you specify times don’t forget to convert them to PST (GMT -8 hours).
sprop=website:www.justgiving.com &sprop=name:Justgiving	The documentation says this is to identify the website or event source. It says it’s required, but excluding it seems to make no difference.
details=Don’t forget to donate at http://www.justgiving.com/richtest001	This is the description of your event. Don’t forget to URL Encode. Using Carriage Return and Line Feed characters seems to work fine. These encode to %0D and %0A respectively so %0D%0A will create a new line when decoded at Google’s end.

Insert test event into your Google calendar.

Google Calendar doesn’t return you to the original site when it finishes adding the event, so you may want to think about opening this link in a new window, either with window.open(), or preferably an HTML link using the target attribute.

There doesn’t appear to be any provision for adding reminders or recurring events using this URL format.

Yahoo Calendar

While looking for reference material for Yahoo’s calendar I came across a similar article to my own that covers the same ground. Is it a coincidence that the only similar article I’ve found is from someone else in the UK?

Anyway, the components of the URL for inserting an event into a user’s Yahoo calendar are these:

http://calendar.yahoo.com/?	- The location of this API
v=60	Seems to be required. Other values I’ve tried just failed rather than doing anything interesting
DUR=0100	This is the duration of the event, in HHmm format. If you’re adding an all-day event then don’t bother with this.
TITLE=My Event	Put the title of your event in here
ST=20070201	Start date/time, use either YYYYMMDD or YYYYMMDDTHHmmSS depending on whether it’s an all-day event
in_loc=My House	Location of the event
DESC	Description of the event
URL	Page to link back to from the calendar

Insert test event into your Yahoo calendar.

UPDATE: Ryan McNallie has more information on his blog.

MSN Calendar

This was the most baffling API so far due to a complete absence of documentation, and one that’s not really to my taste since the software choice (ISAPI.dll) is visible in the URL. Not very elegant. On the other hand MSN calendar is the only one I’ve found that implements ID-based de-duplication. Anyway, here’s a working URL structure.

http://calendar.msn.com/calendar/isapi.dll?	- The location of this API
pid=5020	- This value seems to be required. Changing it caused an error for me.
pn=Site Name	- This is the name of your site.
id=Your Event ID	- Required. This is a unique ID to avoid duplication of the same event in the calendar.
n=0	- This doesn’t seem to be required and I haven’t figured out what it is yet. Remove it at your own risk.
rurl=[encoded URL]	- Required. This is the URL to return the user to once you’ve finished adding this event to their calendar. Frustratingly it’s required, so you’ll need to handle MSN users differently to everyone else.
s=Event Subject	- The name of your event
d=20080113T040000Z/PT2H00M	- The date and time details of your event, in the format [start date]T[start time]/[duration]. I’d guess the timezone would be controlled by the Z or PT elements of the format but it seemed to ignore any changes I made so I’m going to leave that for now.
l=[encoded URL]	- The URL of the event on your website.
c=0	- No idea. Not required
r=E15	- Not sure. Not required
m=[Event Description]	- This is the URL Encoded body text for your event

Add test event to MSN calendar

[UPDATE - 5th January 2010 - Windows Live Calendar]

MSN Calendar is long dead but redirects to Windows Live Calendar, so I thought I’d update this post with information on that.

You can find more thorough documentation on this Scribd document by Siva Vasanth, but the URL you want to construct is detailed below.

http://calendar.live.com/calendar/calendar.aspx?	- The location of this API call
rru=addevent	- Don’t edit this unless you know more than me (not hard).
summary=My Event	Put the title of your event in here. Don’t forget to URL Encode.
location=London	Location description. Don’t forget to URL Encode.
dtstart	The start and end dates for your event YYYYMMDDTHHmmSS, e.g. 20080101T143000 would be half past two on the 1st Jan 2008. You may need to convert them to the right time zone for your calendar, I haven’t tested this. You may also be able to specify all-day events using the YYYYMMDD format.
dtend	Specify the end time of the event, format as above.
description=Don’t forget to buy a card	This is the description of your event. Don’t forget to URL Encode.

I haven’t found any mention of specifying reminders, repetition, or anything other than basic event details.

Scrybe

Scrybe is still in closed beta, a year after launch. I can’t really justify spending time on it right now. If I can find the time once they’re live I might update this article.