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’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.|
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.
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|
UPDATE: Ryan McNallie has more information on his blog.
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|
[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.