Google Apps Platform

Google Calendar API v2 Atom Reference

This API is a subject to the Deprecation Policy and will be deprecated on November 17, 2014. Please use APIv3 instead.

Audience

This document is intended for programmers who want to write client applications that can interact with Google Calendar.

It's a reference document; it assumes that you understand the concepts presented in the developer's guide, and the general ideas behind the Google Data APIs protocol.

Calendar feed types

Google Calendar provides a variety of representations of calendar data. There are two independent axes for specifying a representation: visibility and projection.

Visibility values indicate whether the representation is publicly visible or not. For example, a visibility value of public indicates that the representation is publicly visible. For a list of values, see Visibility values, below.

Projection values indicate how much and what kind of information is included in the representation. For example, a projection value of basic indicates that the representation is a basic Atom feed without any extension elements. For a list of values, see Projection values, below.

Calendar feeds

There are three feeds that return a collection of calendar entries: the metafeed, the allcalendars feed, and the owncalendars feed.

The metafeed is a private, read-only feed that contains an entry for each calendar that a user has access to. The URL for the metafeed is:

https://www.google.com/calendar/feeds/default

The allcalendars feed is a private read/write feed that is used for managing subscriptions and personalization settings of a user's calendars. Unlike the metafeed, the allcalendars feed is writable, so calendar entries can be inserted and deleted, which is equivalent to subscribing and unsubscribing to existing calendars. Calendar entries in the allcalendars feed can also be updated, but since a user may not own all the calendars in this feed, only personalization settings can be updated with this feed. You can update the following personalization settings of a calendar using the allcalendars feed:

Property Description
color Specifies the color of the calendar in the UI.
hidden Indicates whether or not the calendar is shown in the UI.
selected Indicates whether or not the calendar is selected in the UI.

For more information about interacting with the allcalendars feed, see the Managing Subscriptions section of the Developer's Guide. The URL for the allcalendars feeds is:

https://www.google.com/calendar/feeds/default/allcalendars/full

The owncalendars feeds is a private read/write feed that can be used to manage calendars that a user owns. A user is an owner of a calendar if they either created the calendar or if they were granted ownership by an existing owner of the calendar. For the allcalendars feed, inserting and deleting calendar entries is equivalent to creating and deleting secondary calendars. Since a user owns all the calendars in the ownclendars feed, properties such as the title and summary can be updated using this feed. For more information about interacting with the owncalendars feed, see the Managing Calendars section of the Developer's Guide. The URL for the owncalendars feed is:

https://www.google.com/calendar/feeds/default/owncalendars/full

Since all the calendar feeds are private, you can only access it using an authenticated request. That is, the request must contain an authentication token for the user whose calendars you want to retrieve. The Calendar Data API Developer's Guide contains more information about authentication.

Event feeds

To request a particular representation of an event feed, you specify both a visibility value and a projection value in the URI that you send to Calendar.

The URI of a representation of an event feed takes the following form:

https://www.google.com/calendar/feeds/userID/visibility/projection

For example, the following URI is for a feed of calendar events with private visibility and full projection:

https://www.google.com/calendar/feeds/jo@gmail.com/private/full

As a developer, you may want to use any of the projections, but you'll normally use only two of the visibility levels: public or private.

For a private feed, instead of specifying an ID for userID, you can specify the special value default, which tells Calendar to use the default calendar for the username and password that you provided during authentication. For an example of using a default feed, see the Creating single-occurrence events example.

If you know an event's ID, you can request a specific event rather than a full feed. The URI of a representation of a specific Calendar entry (with a given event ID) takes the following form:

https://www.google.com/calendar/feeds/userID/visibility/projection/eventID

Some feed types are read/write (that is, you can post new events to them, and edit or delete existing events), while others are read-only. Read-only feeds don't include a <link rel="http://schemas.google.com/g/2005#post"> element (to tell you where to post new events), and events in read-only feeds don't include <link rel="edit"> elements.

Comment feeds

An event can have a subfeed of comments attached to it. In a full projection event feed, the event feed doesn't include the comments feed inline; instead, the event feed provides a link to the comments feed, with a URL of the following form:

https://www.google.com/calendar/feeds/userID/visibility/full/eventID/comments/subfeedEntryID

The subfeed entry ID at the end is optional; if you include it, then Calendar returns the specified comment entry instead of a feed.

In a composite projection, the event feed does include the comments feed inline. For more information, see Projection values, below.

Personal Settings feed

The settings feed is a private, read-only feed that contains user preferences for Calendar. It is a representation of Calendar General Settings page in Calendar UI.

The URI for settings feed has the following form:

https://www.google.com/calendar/feeds/userID/settings

You can only fetch settings feed for the userID corresponding to the currently authenticated user (or use default as userID). Each user preference is represented as a name/value pair. A given user preference entry with known name can be retrieved with the following URI:

https://www.google.com/calendar/feeds/userID/settings/preferenceName

Each settings feed entry has an gCal:settingsProperty element which has the name and value of particular user preference.

Visibility values

The following table describes the supported visibility values:

Visibility Description Updatability Security Notes
public Shows only public events. Always read-only. Does not require authentication. Inaccessible if the user turns off sharing.
private Shows both public and private events. Potentially read/write. Requires authentication. Updatable only by authorized users.
private-magicCookie Shows both public and private events. Always read-only. Does not require authentication. Instead, authentication information is embedded within the feed URI in the magicCookie string. The magic cookie is a random, high-entropy string combined with authentication information.

Projection values

Although the examples in this document use only the full projection, there are a variety of other useful projections. You may want to start by using full, and then try other projections as you need them and as you get more comfortable with interacting with Calendar.

The following table describes the supported projection values:

Projection Name Description Updatability
full Full-fidelity feed; contains all event properties, but comments aren't included inline; instead, they're specified (in the <gd:feedLink> element) as a link to a separate comment feed. Potentially read/write.
full-noattendees Same as full, but without any <gd:who> elements. Potentially read/write.
composite Same as full, but additionally contains inlined comments, in an <atom:feed> element inside the <gd:feedLink> element. The composite feed also contains <gd:recurrenceException> elements inline in recurring events, and each of those exception elements contains a <gd:originalEvent> element pointing to the original recurring event. Note that the composite feed is often significantly longer than the full feed. Always read-only.
attendees-only Attendees-only feed. Contains minimal event information, but includes <gd:who>. Always read-only.
free-busy Free/busy feed. Contains minimal event information, but includes <gd:when>. Always read-only.
basic Basic Atom feed without any extension elements. Its <atom:summary> and <atom:content> properties contain pre-rendered HTML. Always read-only.

Calendar query parameters reference

In addition to the standard Data API query parameters, Calendar uses the following optional parameters:

Parameter Meaning Notes
ctz The current timezone. If not specified, times are returned in the calendar time zone.
  • Times in the resulting feed will be represented in this timezone.
  • Replace all spaces with underscores (e.g. "ctz=America/Los_Angeles").
fields Response filter Returns only the requested portions of the resource representation for improved performance and efficiency. See the Google Data Protocol query parameter reference.
futureevents A shortcut to request all events that are scheduled for future times. Overrides the recurrence-expansion-start, recurrence-expansion-end, start-min, and start-max values. Valid values are true (return all future events) or false (ignore this parameter). Default is false.
max-attendees The maximum number of attendees to return for each event. If the number of attendees for the event is greater than max-attendees, only the attendee on whose calendar this copy of the event is and the event's organizer if different.
orderby Specifies order of entries in a feed.

Currently, the only supported values are lastmodified (the default) and starttime.

If you add orderby=lastmodified as a query parameter, then the returned feed's entries are ordered by their <updated> values, which is the default ordering.

If you add orderby=starttime as a query parameter, then the returned feed's entries are in order by the <gd:when> element's starttime attribute.

recurrence-expansion-start Specifies beginning of time period for which to expand recurring events.
  • Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00.
  • The lower bound is inclusive, whereas the upper bound is exclusive.
recurrence-expansion-end Specifies end of time period for which to expand recurring events.
singleevents Indicates whether recurring events should be expanded or represented as a single event. Valid values are true (expand recurring events) or false (leave recurring events represented as single events). Default is false.
showdeleted Displays deleted/canceled events. Valid values are true (display deleted/canceled events) or false (hide deleted/canceled events). Default is false.
showhidden Displays events corresponding to invitations that the user yet to respond to.
  • If 'Automatically add invitations to my calendar' is enabled, this flag has no effect.
  • Defaults to false.
sortorder Specifies direction of sorting. Valid values are ascending (with synonyms ascend and a) and descending (with synonyms descend and d).
start-min Together with start-max creates a timespan such that only events that are within the timespan are returned. If not specified, default start-min is 1970-01-01.
  • Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00.
  • The lower bound is inclusive, whereas the upper bound is exclusive.
  • Events that overlap the range are included.
start-max Together with start-min creates a timespan such that only events that are within the timespan are returned. If not specified, default start-max is 2031-01-01.
updated-min Returns events that have been updated, added and/or deleted since the given date. Use the RFC 3339 timestamp format. For example: 2005-08-09T10:57:00-08:00. When using this parameter, showdeleted=false will have no effects.

Note: If using GData-Version: 2.1 or later, when updated-min is set to a date far enough in the past that data isn't available, such as when the primary calendar has been deleted, an HTTP 410 (Gone) status code will be returned.

To receive a feed of all events that overlap with a given time period, set start-min to the beginning of the period and start-max to the end of the period.

In fact, it's usually a good idea to specify start-min and/or start-max to limit the results you get back.

If the user's calendar contains recurring events, then the returned feed includes information about all recurring-event instances that overlap the specified time period.

Specifically, each recurring event is represented by a <gd:recurrence> element in the result feed, and each of those elements includes a <gd:when> element for each occurrence of that event that falls between the start time and the end time. Looking at <gd:when> elements is much simpler than parsing recurrences and exceptions yourself, so in general if you want to handle recurring events it's a good idea to specify start-min and/or start-max.

For example, say you specify a start-min value of 2006-04-01T00:00:00 and a start-max value of 2006-04-20T23:59:59, and the user's calendar includes a weekly meeting that takes place every Monday in 2006. Then the returned feed will include all the events (single or recurring events) that occur within or overlap with that period, plus any event that contains <gd:when> elements for the meetings on 2006-04-03, 2006-04-10, and 2006-04-17—each of the Mondays within the given date range.

For more information about recurring events and how they're handled by services, see the Common Elements: "Kinds" document.

Calendar does not support Data API category queries. It does support full-text queries, using the standard Data API q query parameter; it searches all of the text fields in events, except for extended properties. It also supports the other standard Data API query parameters. For more information about those parameters, see the Google Data API protocol reference document.

Note: The max-results query parameter for Calendar is set to 25 by default, so that you won't receive an entire calendar feed by accident. If you want to receive the entire feed, you can specify a very large number for max-results.

Calendar elements reference

In addition to the standard Data API elements, Calendar uses elements described in the Common Elements document.

Specifically, each entry in a Calendar feed is an Event kind. Each event may contain any or all of the following:

  • One or more <gd:who> elements that represent people associated with the event, each of whom is described with a Contact kind. The <gd:who> element in Calendar events is extended with gCal:additionalGuests.
  • A <gd:comments> element that points to a feed containing Message kinds.
  • One or more <gd:extendedProperty> elements to store custom data. For example, synchronization tools may find it useful to store non-Calendar event IDs as extended properties. In Calendar, an extended property name must be no more than 44 characters long, and an extended property value must be no more than 1024 characters long.

    The realm attribute value for Calendar <gd:extendedProperty> elements can be either:
    • "http://schemas.google.com/g/2005#shared"

      This means that the extended property can be set only by the event organizer but is visible by all participants.

    • "http://schemas.google.com/gCal/2005#calendar"

      This means that the extended property can only be set or retrieved through the calendar currently being used to access the event.  

    If no realm attribute is specified, the <gd:extendedProperty> is considered shared, by default.

    Note that each calendar gets a separate namespace. As a result, an event could have one shared extended property named "foo," as well as multiple calendar-specific extended properties also named "foo" (on different calendars), and each of these extended properties could have a different value.

There are a few differences between the <feed> element used by the Calendar Data API and the <feed> element used by other Google Data APIs. Specifically:

  • In Calendar, the <author> element of a feed is required. (In other Google Data APIs, it's optional).
  • In Calendar, the <atom:link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/> element is required for updatable feeds.

Also, Calendar supports a few rel and type attribute values for <atom:link> that aren't used in other Google Data APIs:

rel and type value Description
atom:link[@rel='alternate'][@type='text/calendar'] Specifies the URL of the ICS source of the calendar, if it came from an ICS source.
atom:link[@rel='source'][@type='application/atom+xml'] Specifies the URL of the Data API source of the calendar, if it came from a Data API source.
atom:link[@rel='related'] Specifies a URL related to the feed.
atom:link[@rel='http://schemas.google.com/gCal/2005/webContent'] [@type='type'] Specifies "web content" for an event; for more information, see gCal:webContent.

Finally, the Calendar <entry> element may optionally contain an <atom:source> element, which isn't used in entries in other Google Data APIs.

GCal namespace element reference

Google Calendar provides several extension elements for use in a metafeed (the feed that lists the user's calendars). These elements are in the gCal namespace, not the Google Data namespace, because they're specific to Calendar.

gCal:accesslevel

Indicates what level of access the current user (the one whose credentials are being used to request the metafeed) has to the calendar.

Properties
Property Type Description
@value xs:string

Must be one of the following:

none
Current user has no access to the calendar.
read
Current user has read-only access to the calendar.
freebusy
Current user can see only the free/busy information on the calendar, not the details of events.
editor
Current user has full edit access to the calendar, except that they can't change the calendar's access control settings.
owner
Current user has full owner access to the calendar.
root
Available only in Google Apps domains. User is a domain administrator, and therefore has full owner access to the calendar regardless of access control settings.
Example

A calendar for which the current user has full owner access:

<gCal:accesslevel value="owner" />
Schema
start = accesslevel

accesslevel =
  element gCal:accesslevel {
    attribute value { xs:string }
  }

gCal:additionalGuests

Indicates how many additional guests are associated with an event attendee. This field is present in <gd:who> elements only when the number of additional guests is greater than zero.

Properties
Property Type Description
@value? xs:integer Number of additional guests.
Example

An attendee that has five additional guests:

<gCal:additionalGuests value="5" />
Schema
start = additionalGuests

additionalGuests =
  element gCal:additionalGuests {
    attribute value { xs:integer }
  }

gCal:busy

A block of busy times.

Properties
Property Description
gd:when Busy time.
Example

A busy time on 03/13/2010 between 2:00pm and 2:30pm UTC:

<gCal:busy>
  <gd:when startTime='2010-03-13T14:00Z' endTime='2010-03-13T14:30Z'/>
</gCal:busy>
Schema
start = busy

busy =
  element gCal:busy {
    element gd:when
  }

gCal:color

The color used to highlight a calendar in the user's browser.

Properties
Property Type Description
@value xs:string Must be one of the following hexadecimal RGB color values:
#A32929 #B1365F #7A367A #5229A3 #29527A #2952A3 #1B887A
#28754E #0D7813 #528800 #88880E #AB8B00 #BE6D00 #B1440E
#865A5A #705770 #4E5D6C #5A6986 #4A716C #6E6E41 #8D6F47
#853104 #691426 #5C1158 #23164E #182C57 #060D5E #125A12
#2F6213 #2F6309 #5F6B02 #8C500B #8C500B #754916 #6B3304
#5B123B #42104A #113F47 #333333 #0F4B38 #856508 #711616
Example

A color:

<gCal:color value="#A32929" />
Schema
start = color

color =
  element gCal:color {
    attribute value { xs:string }
  }

gCal:hidden

Indicates whether a calendar is visible or not.

Properties
Property Type Description
@value xs:boolean Is calendar visible?
Example

A hidden calendar:

<gCal:hidden value="true" />
Schema
start = hidden

hidden =
  element gCal:hidden {
    attribute value { xs:boolean }
  }

gCal:overrideName

Defines the updated name for shared calendars.

Properties
Property Type Description
@value xs:string Name to override the default calendar.
Example

An overridden name:

<gCal:overrideName value="Awesome Calendar" />
Schema
start = overrideName

overrideName =
  element gCal:overrideName {
    attribute value { xs:string }
  }

gCal:timeRange

Indicates the time range of the current feed.

Properties
Property Description
gd:when Feed time range.
Example
 <gCal:timeRange>
  <gd:when startTime='2010-03-13T00:00:00Z' endTime='2010-03-14T00:00:00Z'/>
<gCal:timeRange>
Schema
start = timeRange

timeRange =
  element gCal:timeRange {
    element gd:when
  }

gCal:selected

Indicates whether calendar is selected.

Properties
Property Type Description
@value xs:boolean Is calendar selected?
Example

A selected calendar:

<gCal:selected value="true" />
Schema
start = selected

selected =
  element gCal:selected {
    attribute value { xs:boolean }
  }

gCal:sendEventNotifications

Indicates whether notifications should be sent to the attendees of an event.

Properties
Property Type Description
@value xs:boolean Should notifications be sent?
Example

An event for which notifications should be sent to attendees:

<gCal:sendEventNotifications value="true" />
Schema
start = sendEventNotifications

sendEventNotifications =
  element gCal:sendEventNotifications {
    attribute value { xs:boolean }
  }

gCal:settingsProperty

Represents a key/value pair from the selected user's Calendar settings.

Settings
Name Description Value Format Examples
locale Currently selected Calendar interface language. ISO 639-1 Language Code. en_GB
en_US
country User country selected for time zone display. ISO two-letter country code. US
GB
timezone User time zone. This is not a time zone of any calendar, but the time zone in which events appear on Calendar UI. Long format time zone ID (not PST, but America/Los_Angeles. America/Los_Angeles
UTC
Europe/Prague
timezoneLabel Custom time zone label if specfied by user. Arbitraty string or empty if not set. My time zone label
Home
displayAllTimezones Indicates whether all time zones are visible in Calendar Settings regardless of selected country. true or false. true
false
dateFieldOrder User's desired date format to use in Calendar UI. One of the following values: DMY (day/month/year), MDY, YMD. DMY
MDY
format24HourTime Indicates whether 24-hour format is used in Calendar UI. true or false. true
false
weekStart Indicates the day of the week that the week starts on in Calendar UI. 0 to 6 integer, 0 for Sunday. 0
6
defaultCalMode The default calendar view to display. day for day view, week for week view, month for month view, list for agenda view, custom for custom view. See customCalMode property. week
custom
customCalMode The number of days to display in custom calendar view mode. custom,days where days is the number of days to display. custom,7
custom,28
userLocation User location, used to display weather. Arbitrary string (common is city name or ZIP code). Empty if not set. Mountain View
93043
weather Whether to show weather based on location, and weather format to use. Empty string if weather is not shown. C for Celsius, F for Fahrenheit format. C
F
showDeclinedEvents Whether to display declined events. true or false. true
false
hideInvitations Whether to hide event invitations which are not yet accepted. true or false. true
false
alternateCalendar Whether alternate calendar view is used and which one. 0 if alternate view is not used. 1 for standard Hijri calendar, 2 for Kuwaiti Hijri calendar, 3 for Saudi Hijri calendar. 0
1
Properties
Property Type Description
@name xs:string Indicates the name of the current setting. See the table above for possible settings and their valid values.
@value xs:string Indicates the value of the current setting.
Example
<gCal:settingsProperty name="timezone" value="America/Los_Angeles"/>
Schema
start = settingsProperty

settingsProperty =
  element gCal:settingsProperty {
    attribute name { xs:string },
    attribute value { xs:string }
  }

gCal:sequence

Indicates the revision sequence number of the event as defined in Section 4.8.7.4 of RFC 2445. Must be non-negative.

Properties
Property Type Description
@value xs:integer Indicates the revision sequence number of the event.
Example
<gCal:sequence value='1' />
Schema
start = sequence

sequence =
  element gCal:sequence {
    attribute value { xs:integer }
  }

gCal:suppressReplyNotifications

Prevents email notifications from being sent to event organizers when an attendee replies to an event.

This must be set by the attendee. If this element is omitted, it is assumed to have a value of false.

Properties
Property Type Description
@value xs:boolean true when reply notifications are disabled, false otherwise.
@methods xs:string Comma-separated list of methods to suppress, currently only email is supported.
Example
<gCal:suppressReplyNotifications value="true" methods="email" />
Schema
start = suppressReplyNotifications

suppressReplyNotifications =
  element gCal:suppressReplyNotifications {
    attribute value { xs:boolean }
    attribute methods { xs:string }
  }

gCal:syncEvent

Indicates whether this is a sync scenario where we allow setting the gCal:uid, the gCal:sequence, and the organizer of an event as an attendee.

This element makes sense only when inserting and updating synced events. This element should primarily be used in a sync scenario.

Properties
Property Type Description
@value xs:boolean Indicates whether this is a sync scenario or not.
Example
<gCal:syncEvent value="true" />
Schema
start = syncEvent

syncEvent =
  element gCal:syncEvent {
    attribute value { xs:boolean }
  }

Warning: By default, gCal:syncEvent only works on a user's primary calendar. In order to work with secondary calendars, the HTTP header X-Redirect-Calendar-Shard: true must be included with the request.

gCal:timezone

A time zone.

Properties
Property Type Description
@value xs:string A time zone ID.
Example

A time zone:

<gCal:timezone value="America/Los_Angeles" />
Schema
start = timezone

timezone =
  element gCal:timezone {
    attribute value { xs:string }
  }

gCal:timesCleaned

The number of times the specified calendar has been completely cleared of events.

Properties
Property Type Description
@value xs:integer The number of times the calendar has been cleared of events
Example
<gCal:timesCleaned value="2" />
Schema
start = timesCleaned

timesCleaned =
  element gCal:timesCleaned {
    attribute value { xs:integer }
  }

gCal:uid

Indicates the globally unique identifier (UID) of the event as defined in Section 4.8.4.7 of RFC 2445.

Must be a globally unique string and must follow specifications in Section 4.8.4.7 of RFC 2445.

Properties
Property Type Description
@value xs:string Indicates the globally unique identifier (UID) of the event.
Example
<gCal:uid value='t9d6o9stha0j0cblaoi4s5l29c' />
Schema
start = uid

uid =
  element gCal:uid {
    attribute value { xs:string }
  }

gCal:webContent

Information about a Calendar Event Gadget, formerly called a web content event. The web content icon appears at the top of a day on a calendar; clicking the icon opens a pop-up window that displays the Calendar Event Gadget. Multiple <gCal:webContentGadgetPrefs> elements can be used to specify user preferences for the gadget.

Note: This element appears only inside a webContent <link> element.

atom:link Properties for webContent
Property Type Description
@rel xs:string Must be "http://schemas.google.com/gCal/2005/webContent".
@title xs:string Human-readable title to appear in the header of the pop-up window, and in the tooltip for the icon.
@href xs:string URL of the icon to display. Icon can be in any image format that can be displayed in a web browser. Image will be scaled to 16 pixels square.
@type xs:string Specifies the type of the content. Allowed values are "application/x-google-gadgets+xml", "text/html", and "image/imageformat", where imageformat is a format name like gif or png.
gCal:webContent Properties
Property Type Description
@height xs:integer Height (in pixels) of the <iframe> or <img> element.
@url xs:string URL of the content to display in the pop-up window. The content can be a gadget, an HTML file or an image, as long as you set the type attribute correctly in the webContent <link> element.
@width xs:integer Width (in pixels) of the <iframe> or <img> element.
gCal:webContentGadgetPrefs Properties
Property Type Description
@name xs:string Name of the gadget user preference.
@value xs:string Value of the gadget user preference.
Example

The DateTime gadget (in green):

<link rel="http://schemas.google.com/gCal/2005/webContent"
     href="http://www.google.com/favicon.ico"
     title="DateTime Gadget (a classic!)"
     type="application/x-google-gadgets+xml">
  <gCal:webContent url="http://google.com/ig/modules/datetime.xml" width="300" height="136">
    <gCal:webContentGadgetPref name="color" value="green" />
  <gCal:webContent>
</link>
Schema
start = webContentLink

webContentLink =
  element atom:link {
    attribute rel { xs:string },
    attribute href { xs:string },
    attribute title { xs:string },
    attribute type { xs:string },
    element gCal:webContent {
      attribute height { xs:integer },
      attribute url { xs:string },
      attribute width { xs:integer }
      element gCal:webContentGadgetPref {
        attribute name { xs:integer },
        attribute value { xs:integer }
      }*
    }
  }

gCal:guestsCanModify

Indicates whether event attendees may modify the original event, so that changes are visible to organizer and other attendees. Otherwise, any changes made by attendees will be restricted to that attendee's calendar.

This element may only be changed by the organizer of the event, and may be set to true only if both gCal:guestsCanInviteOthers and gCal:guestsCanSeeGuests are set to true in the same PUT/POST request. Otherwise, request fails with HTTP error code 400 (Bad Request).

If not included as part of the event entry, this element will default to false during a POST request, and will inherit its previous value during a PUT request.

Properties
Property Type Description
@value xs:boolean true if event attendees can modify original event.
Example
<gCal:guestsCanModify value='true' />
Schema
start = guestsCanModify

guestsCanModify =
  element gCal:guestsCanModify {
    attribute value { xs:boolean }
  }

gCal:guestsCanInviteOthers

Indicates whether event attendees may invite other people to the event.

This element may only be changed by the organizer of the event.

If not included as part of the event entry, this element will default to true during a POST request, and will inherit its previous value during a PUT request.

Properties
Property Type Description
@value xs:boolean true if event attendees can invite others.
Example
<gCal:guestsCanInviteOthers value='true' />
Schema
start = guestsCanInviteOthers

guestsCanInviteOthers =
  element gCal:guestsCanInviteOthers {
    attribute value { xs:boolean }
  }

gCal:guestsCanSeeGuests

Indicates whether event attendees can see other people invited to the event.

The organizer always sees all attendees. Guests always see themselves. This property affects what attendees see in the event's guest list via both the Calendar UI and API feeds.

This element may only be changed by the organizer of the event.

If not included as part of the event entry, this element will default to true during a POST request, and will inherit its previous value during a PUT request.

Properties
Property Type Description
@value xs:boolean true if event attendees can see other attendees besides event organizer and themselves.
Example
<gCal:guestsCanSeeGuests value='true' />
Schema
start = guestsCanSeeGuests

guestsCanSeeGuests =
  element gCal:guestsCanSeeGuests {
    attribute value { xs:boolean }
  }

GAcl namespace element reference

Google defines the Google Data API ACL namespace as http://schemas.google.com/acl/2007. We recommend using the namespace alias gAcl.

Google currently defines two elements in the gAcl namespace:

  • gAcl:scope
  • gAcl:role

Each element appears exactly once in every rule.

gAcl:scope

Defines which set of users are governed by the rule that contains this element.

Properties
Property Type Description
@type xs:string

Must be one of the following:

user
Indicates that this access rule applies to an individual. The value attribute is an email address.
domain
Available only in Google Apps For Your Domain. Indicates that this access rule applies to all users with email addresses in your domain, which allows you to (for example) create calendars that are shared with everyone in your domain. The value attribute should contain your domain name.
default
Indicates that this access rule applies to all users. There is no value attribute.
@value? xs:string

An email address or a domain name, depending on the value of the type attribute.

If a given user matches multiple scopes, then they can perform any operation allowed by any of the levels they have been granted in any scope. Consider an ACL with the following rules:

  • user darcy@gmail.com has the role read
  • default has the role freebusy

Given those rules, user darcy@gmail.com can perform any operation allowed by the read or freebusy access levels.

Example

A specific user:

<gAcl:scope type="user" value="darcy@gmail.com" />
Schema
start = scope

scope =
  element gAcl:scope {
    attribute type { xs:string },
    attribute value { xs:string }?
  }

gAcl:role

Defines an access level that applies to all users specified in the associated <gAcl:scope>.

Properties
Property Type Description
@value xs:string

Every role value listed below, other than none, must start with the namespace http://schemas.google.com/gCal/2005#. For example, read in the below list must appear as http://schemas.google.com/gCal/2005#read. The none value doesn't have a prefix; it's in the gAcl namespace.

The value must be one of the following:

none
The specified users have no rights.
read
The specified users have read-only access to the calendar.
freebusy
The specified users can see only the free/busy information on the calendar, not the details of events.
editor
The specified users have full edit access to the calendar, except that they can't change the calendar's access control settings.
owner
The specified users have full owner access to the calendar.
root
Available only in Google Apps For Your Domain. The specified users have administrator access to the calendar server.
Example

To indicate that the specified users can edit the calendar but can't change ACL settings:

 <gAcl:role value='http://schemas.google.com/gCal/2005#editor'></gAcl:role>
Schema
start = role

role =
  element gAcl:role {
    attribute value { xs:string }
  }

Calendar Feeds Schema Reference

  1. Calendar List Feed
  2. Calendar Event Comments Feed
  3. Calendar Events Feed

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.