Calendar API v3

  We recently launched a new version of the Google Calendar API. In addition to the advantages it gains from Google's new infrastructure for APIs, Google Calendar API v3 has a number of improvements that are specific to Google Calendar. In this blog post we’ll highlight a topic that often causes confusion for developers using the Google Calendar API: recurring events. A recurring event is a 'template' for a series of events that usually happen with some regularity, for example daily or bi-weekly. To create a recurring event, the client specifies the first instance of the event and includes one or more rules that describe when future events should occur. Google Calendar will then 'expand' the event into the specified occurrences. Individual events in a series may be changed, or even deleted. Such events become exceptions: they are still part of the series, but changes are preserved even if the recurring event itself is updated. Let's create a daily recurring event that will occur every weekday of the current week (as specified by the recurrence rule on the last line):

POST https://www.googleapis.com/calendar/v3/calendars/primary/events

{
  "summary": "Daily project sync",
  "start": {
    "dateTime": "2011-12-12T10:00:00",
    "timeZone": "Europe/Zurich"
  },
  "end": {
    "dateTime": "2011-12-12T10:15:00",
    "timeZone": "Europe/Zurich"
  },
  "recurrence": [
    "RRULE:FREQ=DAILY;COUNT=5"
  ]
}

When added to a calendar, this will turn into five different events. The recurrence rule is specified according to the iCalendar format (see RFC 5545). Note, however, that, in contrast to the previous versions of the Google Calendar API, the start and end times are specified the same way as for single instance events, and not with iCalendar syntax. Further, note that a timezone identifier for both the start and end time is always required for recurring events, so that expansion happens correctly if part of a series occurs during daylight savings time. By default, when listing events on a calendar, recurring events and all exceptions (including canceled events) are returned. To avoid having to expand recurring events, a client can set the singleEvents query parameter to true, like in the previous versions of the API. Doing so excludes the recurring events, but includes all expanded instances. Another way to get instances of a recurring event is to use the 'instances' collection, which is a new feature of this API version. To list all instances of the daily event that we just created, we can use a query like this:

GET https://www.googleapis.com/calendar/v3/calendars/primary/events/7n6f7a9g8a483r95t8en23rfs4/instances

which returns something like this:

{
  ...
  "items": [
  {
    "kind": "calendar#event",
    "id": "7n6f7a9g8a483r95t8en23rfs4_20111212T090000Z",
    "summary": "Daily project sync",
    "start": {
      "dateTime": "2011-12-12T10:00:00+01:00"
    },
    "end": {
      "dateTime": "2011-12-12T10:15:00+01:00"
    },
    "recurringEventId": "7n6f7a9g8a483r95t8en23rfs4",
    "originalStartTime": {
      "dateTime": "2011-12-12T10:00:00+01:00",
      "timeZone": "Europe/Zurich"
    },
    ...
  },
  … (4 more instances) ...

Now, we could turn one instance into an exception by updating that event on the server. For example, we could move one meeting in the series to one hour later as usual and change the title. The original start date in the event is kept, and serves as an identifier of the instance within the series. If you have a client that does its own recurrence rule expansion and knows the original start date of an instance that you want to change, the best way to get the instance is to use the originalStart parameter like so:

GET https://www.googleapis.com/calendar/v3/calendars/primary/events/7n6f7a9g8a483r95t8en23rfs4/instances?originalStart=2011-12-16T10:00:00%2B01:00

This would return a collection with either zero or one item, depending on whether the instance with the exact original start date exists. If it does, just update or delete the event as above. Lastly, in Google Calendar API v3, we have added the ability to revert the changes made to an individual instance, so it is no longer an exception. One way of doing something similar with the previous versions of the API would be to just copy all fields from the underlying recurring event into the instance and perform an update. That is an incomplete solution, however, because fields that were once updated in the exception would not be updated when the recurring event changes. The proper way to do this now is to use the reset method on the event. To undo the changes we did to our Friday meeting, we would issue a request like this:

POST https://www.googleapis.com/calendar/v3/calendars/primary/events/7n6f7a9g8a483r95t8en23rfs4_20111216T090000Z/reset

We hope you’ll find value in these changes to recurring events. Keep in mind, too, that these are not the only improvements in Google Calendar API v3. Look for an upcoming post describing best practices for another key area of improvement: reminders.