What's New in v3

Version 3 of the API brings several new features as well as changes to the previous APIs. This page highlights some of the new features introduced in v3. The latest notes are first.

Efficient synchronization of resources

With newly introduced sync tokens, the Calendar API now supports incremental sync of all collections. This provides much better performance than prior methods based on retrieval of all resources. Learn more.

Push notification support for all calendar collections

The Calendar API now supports push notifications that inform your application when a resource changes. Learn more.

Custom colors for Calendars

The Calendar API now includes fields for custom colors for calendars. The CalendarList resource now includes backgroundColor and foregroundColor properties that supersede colorId. To use the new custom colors, set colorRgbFormat to True when performing updates.

Google+ Events in Calendar API v3

This version of the API contains some changes for compatibility with Google+ events:

  • Events can have creator, organizer, and/or attendees with an id field and without an email field. The id field will always be the user's Profile ID. This is essentially the number you see in the URL when looking at a Google+ profile page in a browser. Because the email field is no longer required, it is important that you not rely on its presence. This has previously been used for tasks such as finding the calendar user among the attendee entries. This scenario is now handled by the self flag.

For applications that still expect a value for email field in the creator, organizer, or attendees fields, set the alwaysIncludeEmail parameter to True with the list and get operations for events. This will provide a generated (i.e. non-working) email value if no email is set.

  • The self flag is now available for the creator, organizer, and attendees fields to indicate whether the event was found on the calendar corresponding to that role for the event.

  • The locked flag for events indicates that the main event fields ("summary", "description", "location", "start", "end", or "recurrence") cannot be changed. Attempts to do so are rejected with a 403 Forbidden response. This can only be set for attendees' copies of an event, never for the organizer (i.e. the master copy). Other event details, such as extended properties, can still be changed. This is not the same as "guestCanModify: false", which indicated that modifications aren't reflected on copies other than the user's. This field is read-only.

  • The endTimeUnspecified flag for events indicates that a duration or end time for this event has not been specified. For backward-compatibility, the end time is still set with the event. Also for backward-compatibility, not including this flag in an update will not change it.

Send feedback about...

Google Calendar API
Google Calendar API