Adding Events to Users Calendars – Part 2 – Web Calendars

Monday 7th January, 2008

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.


Adding Events to Users Calendars – Part 1 – iCal/vCal

Tuesday 18th December, 2007

I’ve just been figuring out how to use iCal/vCal to add events to users calendars and the resources I found were a little dry so here’s a quick and dirty HOWTO.

Set up some code on your server to return the text below, and set the “Content-Type” header of the HTTP Response to text/calendar

Getting something working

First up I tried getting a basic event into Outlook (the calendar I have to hand). I found that without the DTSTAMP field Outlook threw a non-specific wobbly. When this field is included Outlook treats it as the creation time of the event. More info on the quirks of specific implementations can be found on the relevant Wikipedia article.

My first working file looked something like this:

BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
UID:SOMETHING
DTSTAMP:20071216T000000Z
DTSTART:20071216T000000Z
DTEND:20071216T235959Z
SUMMARY:Test event
DESCRIPTION:Nothing much
END:VEVENT
END:VCALENDAR

Note the VEVENT element nested inside the VCALENDAR element like in XML.

All-day events

This seems to work, although seems to be putting the dates into Outlook an hour later than I would’ve expected (and we’re in GMT not BST so it’s not that). In any case, I want to return these as all-day events since we don’t store the specific time of the event. The format for that seems to be DTSTART;VALUE=DATE:20070930, which makes sense. The VALUE=DATE seems to be a way of specifying the data type for a field, in this case DATE rather than DATE-TIME.

Setting reminders

Next I want to add a reminder to my calendar item. One week should do the trick. Looking at the code below you can see that I’ve nested a VALARM element within the VEVENT element. Using a TRIGGER value of “-PT7D“, I should now get a notification from my calendar a week before the event. You can also use other units, “-PT3H” would be three hours, “-PT5M” would be five minutes, you get the picture.

Alternatively you could input a specific time for the reminder to go off by overriding the TRIGGER field, like this: TRIGGER;VALUE=DATE-TIME:20080117T133000Z.

Final output

This is my final static version with an all-day event and a reminder.

BEGIN:VCALENDAR
VERSION:2.0
METHOD:PUBLISH
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
UID:SOMETHING
DTSTAMP;VALUE=DATE:20071201
DTSTART;VALUE=DATE:20071220
DTEND;VALUE=DATE:20071220
SUMMARY:Test event
DESCRIPTION:Nothing much
BEGIN:VALARM
TRIGGER:-PT7D
ACTION:DISPLAY
DESCRIPTION:Reminder to do something
END:VALARM
END:VEVENT
END:VCALENDAR

Done

That’s about as far as I need to go with this, now I just need to hook it into the database and link to it correctly. Let me know if you find this useful, or find mistakes, either way someone’s learning something.

Tip: If you’re trying to debug your iCal response, try using the Firebug plug-in for Firefox. The “Net” tab will show you the response your server is returning.