Return to Google homepage

Developer's Guide

Calendar data API Terms and Conditions

Related Links

Google Data APIs (Beta) Developer's Guide

Common Elements: "Kinds"

Contents

Introduction

It's often useful for services that use the Google data APIs to be able to provide a consistent set of information about a particular kind of item.

For example, various Google data API (or "GData") services might provide contact information for a person or an organization; it makes sense for all such services to use the same set of contact-information elements.

The collection of elements that together describe a contact is called the Contact "kind." Some of the elements in the Contact kind are ordinary Atom or RSS elements; others are defined by Google in a namespace called the "Google data namespace." By convention, the Google data namespace is usually referred to in XML code using the gd: alias; for example, the element that contains a telephone or fax number is <gd:phoneNumber>. The schema URL for the Google data namespace is http://schemas.google.com/g/2005.

Google defines other kinds as well: Event (a collection of standardized elements that together represent a calendar event) and Message (a collection of elements representing an email message, discussion group posting, blog entry, or other message).

Some elements from the Google data namespace are used by multiple kinds. For example, the <gd:who> element associates a person (described in the <gd:who>) with the entry that contains the <gd:who> element. This element is used in the Event kind to specify organizers, attendees, and so on. It's also used in the Message kind to specify senders and recipients.

When an entry in a Google data API feed uses a given kind, it contains an <atom:category> element with its scheme attribute set to "http://schemas.google.com/g/2005#kind" and its term attribute set to the name of the schema URL followed by the name of the kind. For example, a Contact entry includes the following element:

<atom:category scheme="http://schemas.google.com/g/2005#kind"
  term="http://schemas.google.com/g/2005#contact"/>

This allows clients to quickly and easily determine what kind of data the entry contains—that is, to determine the semantics of the entry. (You can use RSS instead of Atom if you prefer; see the Protocol document for the RSS elements corresponding to Atom elements.)

This document is a reference for some common kinds and the elements they contain.

Undocumented elements

We don't include information about the standard elements of <atom:entry> in kinds where those elements have their standard meanings. For example, <atom:id>, <atom:published>, and <atom:updated> all have their standard meanings when they appear in kinds.

We also don't include information about standard Atom elements that would be meaningless in the given context; for example, <atom:summary> isn't used in the Contact kind, and although <atom:author> is a required element in an entry (unless it's specified in the parent feed), it doesn't have a useful meaning in the Contact kind.

Creating kinds

It may be hard to figure out exactly what information you need to include when creating an entry of a particular kind, especially because some elements in the kinds contain other kinds.

One approach that might help is to use the client libraries we provide rather than to try to construct kinds by hand. The client libraries provide various methods for adding and changing data in an entry of a given kind; see the client library documentation for details.

Extensibility

The information in this document doesn't cover all possible properties and attribute values for kinds. Services may extend kinds, so a particular service may use properties and values not included in this document.

Typographical conventions

In the tables in this document, we use the following conventions for required and optional elements:

elementName Required element
elementName? Optional element
elementName* Optional element, multiple instances allowed

Elements and attributes are presented in standard XPath notation.

Contact kind

Represents a contact: a person, a venue such as a club or a restaurant, or an organization.

Category element: <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>

Note that most of the information about the contact is in the <gd:contactSection> element; see the reference section for that element for details.

Properties

Property Description
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see note at beginning of this section.
atom:content Notes about the contact.
atom:link* Links to more information. Specifically, atom:link[@rel='alternate'] provides a link to an HTML page describing the contact. See the table below for other rel values.
atom:title Contact's name.
gd:contactSection* Collection of contact information entries grouped under a common label. Some properties, such as a mobile phone number or an IM address, may appear in a contact section entry without a label.

rel values for atom:link

rel value Description
http://schemas.google.com/g/2005#image Specifies a URL of an image of the contact.
http://schemas.google.com/g/2005#onlineLocation Specifies a URL of a contact. If this contact is used within <gd:where> of an event entry, it indicates that an event takes place online at the specified URL.

Examples

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
  <category term="user-tag" label="Colleague"/>
  <id>http://contacts.example.com/jo/Jo</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Jo March</title>
  <content/>
  <gd:contactSection>
    <gd:im network="AIM" address="hcc@example.com"/>
    <gd:phoneNumber rel="http://schemas.google.com/g/2005#mobile">(206) 555-1212</gd:phoneNumber>
    <gd:phoneNumber rel="http://schemas.google.com/g/2005#car">(206) 555-1213</gd:phoneNumber>
  </gd:contactSection>
  <gd:contactSection label="Work">
    <gd:email address="jo@example.com"/>
    <gd:phoneNumber rel="http://schemas.google.com/g/2005#work">(650) 555-1212</gd:phoneNumber>
    <gd:phoneNumber rel="http://schemas.google.com/g/2005#pager">(650) 555-1214</gd:phoneNumber>
    <gd:postalAddress>
      1600 Amphitheatre Pkwy
      Mountain View, CA 94043
    </gd:postalAddress>
    <gd:geoPt lat="37.423269" lon="-122.082667"/>
  </gd:contactSection>
  <gd:contactSection label="Home">
    <gd:email address="estor@example.org"/>
    <gd:phoneNumber>(206) 555-1212</gd:phoneNumber>
    <gd:postalAddress>
      800 Main Street
      Mountain View, CA 94041
    </gd:postalAddress>
  </gd:contactSection>
</entry>

Event kind

Represents a calendar event. The event location is represented by a Contact kind embedded in (or linked from) a <gd:where> element; the event planners and attendees are represented as Contact kinds embedded in (or linked from) <gd:who> elements.

Category element: <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>

Properties

Property Description
atom:author Person who created this event.
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see note at beginning of this section.
atom:content Longer description of the event.
atom:link* Links. Specifically, atom:link[@rel='alternate'] provides a link to an HTML page describing the event.
atom:title Brief title for the event.
gd:comments? Comments feed.
gd:eventStatus? Extensible enum documented below.
gd:recurrence? Recurrence rule.
gd:transparency? Extensible enum documented below.
gd:visibility? Extensible enum documented below.
gd:when* Event time. If the event is an all-day event, then the startTime and endTime attributes are not set. In any other case, both attributes must be set.
gd:when/gd:reminder* Reminders for the event.
gd:where* Location of the event or nearby necessities such as parking. If a <gd:where> element is specified at the feed level, but there's no <gd:where> element at the entry level, then the entries inherit the feed-level <gd:where> value.
gd:who* People associated with the event: organizer, attendees, speakers, performers, etc.
gd:who/gd:attendeeStatus? Acceptance status.
gd:who/gd:attendeeType? Attendee type: required or optional.

rel values for gd:where

rel value Description
http://schemas.google.com/g/2005#event or not specified. Place where the event takes place.
http://schemas.google.com/g/2005#event.alternate A secondary location. For example, a remote site with a videoconference link to the main site.
http://schemas.google.com/g/2005#event.parking Nearby parking lot.

gd:eventStatus values

Value Description
http://schemas.google.com/g/2005#event.canceled The event has been canceled.
http://schemas.google.com/g/2005#event.confirmed The event is planned.
http://schemas.google.com/g/2005#event.tentative The event is only tentatively scheduled.

gd:visibility values

Value Description
http://schemas.google.com/g/2005#event.confidential Allow some readers to see the event.
http://schemas.google.com/g/2005#event.default Inherit the behavior from the preferences of the owner of the calendar on which the event appears.
http://schemas.google.com/g/2005#event.private Allow fewest readers to see the event.
http://schemas.google.com/g/2005#event.public Allow most readers to see the event.

gd:transparency values

Value Description
http://schemas.google.com/g/2005#event.opaque Allow most people to see only a free/busy block.
http://schemas.google.com/g/2005#event.transparent Allow most people to see event details.

Examples

Meeting:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>
  <id>http://mycal.example.com/feeds/jo/home/full/e1a2af06df8a563edf9d32ec9fd61e03f7f3b67b</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Discuss BazMat API</title>
  <content>We will discuss integrating GData with BazMat.</content>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <gd:when startTime='2005-01-18T21:00:00Z' endTime='2005-01-18T22:00:00Z'>
    <gd:reminder minutes='15'/>
  </gd:when>
  <gd:where valueString='Building 41, Room X'/>
  <gd:eventStatus value="http://schemas.google.com/g/2005#event.confirmed"/>
  <gd:visibility value="http://schemas.google.com/g/2005#event.public"/>
  <gd:transparency value="http://schemas.google.com/g/2005#event.transparent"/>
</entry>

Online event:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#event"/>
  <id>http://mycal.example.com/feeds/jo/home/full/982307e797979879a</id>
  <published>2005-01-18T21:00:00Z</published>
  <updated>2006-01-01T00:00:00Z</updated>
  <title>Online Chess Tournament</title>
  <content/>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <gd:when startTime='2006-01-24T19:00:00-08:00' endTime='2006-01-24T20:00:00-08:00'>
    <gd:reminder minutes='15'/>
  </gd:when>
  <gd:where>
    <gd:entryLink>
      <entry>
        <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
        <id>http://contacts.example.com/jo/GamePhannz</id>
        <published>2005-01-18T21:00:00Z</published>
        <updated>2006-01-01T00:00:00Z</updated>
        <title>GamePhannz Online Game Server</title>
        <link rel="http://schemas.google.com/g/2005#onlineLocation" type="text/html" href="http://gamephannz.example.com/chess/138fd87e"/>
        <content/>
      </entry>
    </gd:entryLink>
  </gd:where>
  <gd:eventStatus value="http://schemas.google.com/g/2005#event.confirmed"/>
  <gd:visibility value="http://schemas.google.com/g/2005#event.public"/>
  <gd:transparency value="http://schemas.google.com/g/2005#event.transparent"/>
</entry>

Message kind

Represents a message, such as an email, a discussion group posting, or a comment.

Category element: <atom:category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message"/>

Properties

Property Description
atom:category* Categories. Instances with the @label attribute are treated as tags. For information on using the @scheme attribute, see note at beginning of this section. For information on using the @term attribute, see table below.
atom:content Message body.
atom:link* Message attachments. Specifically, to upload an attachment, use <link rel="enclosure"> and put the attachment's content in an Atom media collection.
atom:title Message subject.
gd:geoPt? Geographic location the message was posted from.
gd:rating? Quality rating (as defined by the application).
gd:who* People associated with this message. The exact semantics depends on the @rel value. See table below.

Category @term values

All categories below are in the http://schemas.google.com/g/2005 scheme.

Term Description
http://schemas.google.com/g/2005#message.chat The message is a transcript of a chat session.
http://schemas.google.com/g/2005#message.inbox The message is marked as belonging to the inbox.
http://schemas.google.com/g/2005#message.sent The message is marked as sent.
http://schemas.google.com/g/2005#message.spam The message is considered spam.
http://schemas.google.com/g/2005#message.starred The message is marked as starred.
http://schemas.google.com/g/2005#message.unread The message is unread.

rel values for gd:who

Property Description
http://schemas.google.com/g/2005#message.bcc Message BCC recipient.
http://schemas.google.com/g/2005#message.cc Message CC recipient.
http://schemas.google.com/g/2005#message.from Message (email or IM) sender.
http://schemas.google.com/g/2005#message.reply-to Intended recipient of a reply message.
http://schemas.google.com/g/2005#message.to Message primary recipient.

Example

Email message:

<entry xmlns:gd="http://schemas.google.com/g/2005">
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message"/>
  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#message.sent"/>
  <author>
    <name>Jo March</name>
    <email>jo@example.com</email>
  </author>
  <id>http://mymail.example.com/feeds/jo/home/full/e1a2af06df8a563edf9d32ec9fd61e03f7f3b67b</id>
  <published>2006-01-18T21:00:00Z</published>
  <updated>2006-01-18T21:00:00Z</updated>
  <title>Re: Info?</title>
  <content>Hi, Fritz -- The information you're looking for is on p. 47.</content>
  <gd:who rel="http://schemas.google.com/g/2005#message.from">
    <gd:entryLink href="http://contacts.example.com/jo/Jo"/>
  </gd:who>
  <gd:who rel="http://schemas.google.com/g/2005#message.to">
    <gd:entryLink href="http://contacts.example.com/fritzb/FritzB"/>
  </gd:who>
</entry>

Google data namespace element reference

The rest of this document consists of reference material for the elements used by the kinds.

Enums

Some extension elements need to specify properties whose values come from an enumerated set. The general form of such properties is:

<gd:propertyName value="propertyValue">

If the property value comes from the Google data namespace, it takes the form http://schemas.google.com/g/2005#{kind}.{value}. For example: http://schemas.google.com/g/2005#event.tentative. If the value space is extensible, values may also be in the form of a URI. The recommended form for extended value URIs is {schema URI}#{value}. For example: http://www.example.com/attendeeStatus#AudioConference.

gEnumConstruct = {
   attribute value { text },
   anyAttribute*
}

gdCommonProperties

Common properties used for all Google types. Note that the presence of anyAttribute and anyElement in the schema allows all Google data namespace elements using common properties to be further extended in any namespace. In particular it's legal to nest any gd element or any Atom/RSS element within any other gd element. This should be done judiciously, and in most cases such use should be documented as an explicit property of the containing gd element type.

Properties

Property Type Description
@xml:base uri Standard XML construct for describing base of nested relative URIs.
@xml:lang text Language of nested strings.

Schema

namespace gd = "http://schemas.google.com/g/2005"

gdCommonProperties = {
   atomCommonAttributes,
   anyAttribute*,
   (anyElement*)
}

gd:comments

Contains a comments feed for the enclosing entry (such as a blog post, a calendar event, etc.).

Properties

Property Type Description
@rel? string Type of comments contained within. Currently, there's a distinction between regular comments and reviews.
gd:feedLink? feedLink Comments feed. This feed should implement the Message kind.

rel values

Value Description
http://schemas.google.com/g/2005#regular or not specified Regular comments (from users).
http://schemas.google.com/g/2005#reviews Professional reviews.

Examples

Comments feed:

<gd:comments>
  <gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments" countHint="10">
    <feed>
      <id>http://example.com/Jo/posts/MyFirstPost/comments</id>
      <title>My first post: comments</title>
      ...
      <entry>
         ...
         <content>Good post.</content>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>
</gd:comments>

Reviews feed:

<gd:comments rel="http://schemas.google.com/g/2005#reviews">
  <gd:feedLink href="http://example.com/restaurants/SanFrancisco/432432/reviews" countHint="25">
    <feed>
      <id>http://example.com/restaurants/SanFrancisco/432432/reviews</id>
      <title>La Folie reviews</title>
      ...
      <entry>
         ...
         <content>Good food.</content>
         <gd:rating value="5" min="1" max="5"/>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>
</gd:comments>

Schema

start = comments

comments =
   element gd:comments {
      gdCommonProperties,
      attribute rel { xs:string }?,
      (feedLink?)
   }

gd:contactSection

Collection of contact information entries grouped under a common label.

Properties

Property Type Description
@label? xs:string

Label for a kind of contact information, such as "Home", "Work", "New York Office", "Vacation Home", or "Other". Some properties, such as a mobile phone number or an IM address, may appear in a contact section entry without a label.

gd:email* email Email addresses.
gd:geoPt* geoPt Geographic locations.
gd:im* im IM addresses.
gd:phoneNumber* phoneNumber Phone and fax numbers.
gd:postalAddress* postalAddress Postal addresses.

Example

  <gd:contactSection label="Work">
    <gd:email address="jo@example.com"/>
    <gd:phoneNumber rel="http://schemas.google.com/g/2005#work">(650) 555-1212</gd:phoneNumber>
    <gd:phoneNumber rel="http://schemas.google.com/g/2005#pager">(650) 555-1214</gd:phoneNumber>
    <gd:postalAddress>
      1600 Amphitheatre Pkwy
      Mountain View, CA 94043
    </gd:postalAddress>
    <gd:geoPt lat="37.423269" lon="-122.082667"/>
  </gd:contactSection>

Schema

start = contactSection

contactSection =
   element gd:contactSection {
      gdCommonProperties,
      attribute label { xs:string }?,
      (email*
      & im*
      & phoneNumber*
      & postalAddress*
      & geoPt*)
   }

gd:email

An email address associated with the containing entity (which is usually an entity representing a person or a location).

Properties

Property Type Description
@address xs:string Email address.
@label? xs:string A simple string value used to name this email address. It allows UIs to display a label such as "Work", "Personal", "Preferred", etc.

Examples

<gd:email address="foo@bar.example.com"/>
<gd:email label="Personal" address="fubar@gmail.com"/>

Schema

start = email

email =
   element gd:email {
      attribute label { xs:string }?,
      attribute address { xs:string }
   }

gd:entryLink

Represents a logically nested entry. For example, a <gd:who> representing a contact might have a nested entry from a contact feed.

Properties

Property Type Description
@href? xs:string Specifies the entry URI. If the nested entry is embedded and not linked, this attribute may be omitted.
@readOnly? xs:boolean Specifies whether the contained entry is read-only. The default value is "false".
atom:entry? atomEntry Contents of the entry.

Restrictions

Examples

Contact information within <gd:who>:

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo">
    <entry>
      <category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/g/2005#contact"/>
      <id>http://gmail.com/jo/contacts/Jo</id>
      <category term="user-tag" label="Google"/>
      <title>Jo March</title>
      <gd:contactSection>
        <gd:email address="jo@example.com"/>
        <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
      </gd:contactSection>
    </entry>
  </gd:entryLink>
</gd:who>

External reference only (read-only entry):

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo" readOnly="true"/>
</gd:who>

Schema

start = entryLink

entryLink =
   element gd:entryLink {
      attribute href { xs:string }?,
      attribute readOnly { xs:boolean }?,
      (atomEntry?)
   }

gd:feedLink

Represents a logically nested feed. For example, each entry within a blog's posts feed might have a nested feed representing all comments on the post.

Properties

Property Type Description
@countHint? xs:unsignedInt Hints at the number of entries in the feed. Depending on the implementation, may not be a precise count.
@href? xs:string Specifies the feed URI. If the nested feed is embedded and not linked, this attribute may be omitted.
@readOnly? xs:boolean Specifies whether the contained feed is read-only.
atom:feed? atomFeed Contents of the feed.

Restrictions

Examples

Blogging:

<gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments" countHint="10">
    <feed>
      <id>http://example.com/Jo/posts/MyFirstPost/comments</id>
      <title>My first post: comments</title>
      ...
      <entry>
         ...
         <content>Good post.</content>
      </entry>
      <entry>
         ...
      </entry>
      ...
    </feed>
  </gd:feedLink>

External reference only:

<gd:feedLink href="http://example.com/Jo/posts/MyFirstPost/comments"
            countHint="10"/>

Embedded feed within an Atom entry representing a list:

<gd:feedLink>
  <feed>
    <id>cid:1</id>
    <entry>
       <id>cid:1.1</id>
       <content>list item 1</content>
    </entry>
    <entry>
       <id>cid:1.2</id>
       <content>list item 2</content>
    </entry>
  </feed>
</gd:feedLink>

Schema

start = feedLink

feedLink =
   element gd:feedLink {
      attribute href { xs:string }?,
      attribute readOnly { xs:boolean }?,
      attribute countHint { xs:unsignedInt }?,
      (atomFeed?)
   }

gd:geoPt

A geographical location (latitude, longitude, elevation).

Properties

Property Type Description
@elev? xs:float Elevation in meters. Negative values indicate depths below mean sea level.
@label? xs:string A simple string value used to name this location. It allows UIs to display a label such as "Current Position".
@lat xs:float Latitude in degrees. Positive values mean North, negative values mean South. The range is [-90.0, 90.0].
@lon xs:float Longitude in degrees. Positive values mean East, negative values mean West. The range is [-180.0, 180.0].
@time? xs:dateTime Timestamp.

Examples

<gd:geoPt lat="40.75" lon="-74.0"/>
<gd:geoPt lat="27.98778" lon="86.94444" elev="8850.0"/>

Schema

start = geoPt

geoPt =
   element gd:geoPt {
      attribute label { xs:string }?,
      attribute lat { xs:float },
      attribute lon { xs:float },
      attribute elev { xs:float }?,
      attribute time { xs:dateTime }?
   }

gd:im

An instant messaging address associated with the containing entity.

Properties

Property Type Description
@address xs:string IM address.
@label? xs:string A simple string value used to name this IM address. It allows UIs to display a label such as "Work", "Personal", "Preferred", etc.
@protocol? xs:string Identifies the IM network. The value may be either one of the standard values (shown below) or a URI identifying a proprietary IM network.

protocol attribute values

The following table shows some likely possible values for the @protocol attribute.

Value Description
sip SIP/SIMPLE
unknown Unknown or unspecified protocol
xmpp XMPP (the protocol used by Google Talk, among others)
http://www.aim.com/ AIM
http://www.icq.com/ ICQ
http://messenger.msn.com/ MSN Messenger
http://messenger.yahoo.com/ Yahoo Messenger

Examples

A SIP/SIMPLE IM address:

<gd:im protocol="sip" address="foo@bar.example.com"/>

A user-provided IM address an unspecified protocol. Such an address is useful for display purposes, but is difficult to handle programmatically.

<gd:im label="Other" address="foo@baz.example.com"/>

Schema

start = im

im =
   element gd:im {
      attribute label { xs:string }?,
      attribute protocol { xs:string }?,
      attribute address { xs:string }?
   }

gd:originalEvent

Used in <gd:recurrenceException> to link to the original recurring event that the containing event is an exception to.

Contains a <gd:when> element specifying the original start time of the instance that has become an exception.

Properties

Property Type Description
@id xs:string The event ID for the original recurring event.
@href xs:string The event feed URL for the original recurring event.

Example

The original recurring event:

<gd:originalEvent id="i8fl1nrv2bl57c1qgr3f0onmgg"
   
href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID">
  <gd:when startTime="2006-03-17T22:00:00.000Z"/>
</gd:originalEvent>

Schema

start = originalEvent

originalEvent =
   element gd:originalEvent {
      attribute id { xs:string },
      attribute href { xs:string },

      (xs:string)
   }

gd:phoneNumber

A phone number associated with the containing entity (which is usually an entity representing a person or a location).

Properties

Property Type Description
@label? xs:string A simple string value used to name this phone number. In most cases, @label is not necessary as @rel uniquely identifies a number and allows UIs to display a proper label such as "Mobile", "Home", "Work", etc. However, in the case where one person has (for example) multiple mobile phones, this property can be used to disambiguate them.
@rel? xs:string A programmatic value that identifies the type of phone number; see below for details.
@uri? xs:string An optional "tel URI" used to represent the number in a formal way, useful for programmatic access, such as a VoIP/PSTN bridge. See RFC 3966 for more information on tel URIs.
text() xs:string Human-readable phone number; may be in any telephone number format. Leading and trailing whitespace is insignificant. Newlines within the string are also insignificant, and may be removed or flattened out to a single space.

rel values

Value Description
http://schemas.google.com/g/2005#car Number of a car phone.
http://schemas.google.com/g/2005#fax
http://schemas.google.com/g/2005#general or not specified Unknown or unspecified type, such as a business phone number that doesn't belong to a particular person.
http://schemas.google.com/g/2005#home
http://schemas.google.com/g/2005#internal-extension Phone number that makes sense only in a context known to the user (such as an enterprise PBX).
http://schemas.google.com/g/2005#mobile
http://schemas.google.com/g/2005#other A special type of number for which no other rel value makes sense. For example, a TTY device. label can be used to indicate the actual type.
http://schemas.google.com/g/2005#pager
http://schemas.google.com/g/2005#satellite
http://schemas.google.com/g/2005#voip
http://schemas.google.com/g/2005#work

Examples

Simple phone number entered by a user:

<gd:phoneNumber>(425) 555-8080 ext. 72585</gd:phoneNumber>

Same phone number drawn from a directory:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#work" uri="tel:+1-425-555-8080;ext=52585">
  (425) 555-8080 ext. 52585
</gd:phoneNumber>

Internal phone number entered by a user:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#internal-extension">x72585</gd:phoneNumber>

Same internal phone number drawn from a directory:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#internal-extension" uri="tel:72585;phone-context=example.com">
  x72585
</gd:phoneNumber>

Number with a label:

<gd:phoneNumber rel="http://schemas.google.com/g/2005#mobile" label="Personal calls only" uri="tel:+12065551212">
  +1 206 555 1212
</gd:phoneNumber>

Schema

start = phoneNumber

phoneNumber =
   element gd:phoneNumber {
      attribute rel { xs:string }?,
      attribute label { xs:string }?,
      attribute uri { xs:string }?,
      (xs:string)
   }

gd:postalAddress

A postal address.

Properties

Property Type Description
@label? xs:string A simple string value used to name this address.
text() xs:string Address. Leading and trailing whitespace is insignificant. Newlines within the string are significant.

Examples

<gd:postalAddress>
  500 West 45th Street
  New York, NY 10036
</gd:postalAddress>

Schema

start = postalAddress

postalAddress =
   element gd:postalAddress {
      attribute label { xs:string }?,
      (xs:string)
   }

gd:rating

Represents a numeric rating of the enclosing entity, such as a comment. Each rating supplies its own scale, although it may be normalized by a service; for example, some services might convert all ratings to a scale from 1 to 5.

Properties

Property Type Description
@max xs:int The rating scale's maximum value.
@min xs:int The rating scale's minimum value
@rel? xs:string Specifies the aspect that's being rated. If not specified, the rating is an overall rating.
@value xs:int Rating value.

rel values

Value Description
http://schemas.google.com/g/2005#overall or not specified Overall rating. Higher values mean better ratings.
http://schemas.google.com/g/2005#price Price rating. Higher values mean higher prices.
http://schemas.google.com/g/2005#quality Quality rating. Higher values mean better quality.

Examples

4/5 overall rating:

<gd:rating value="4" min="1" max="5"/>

Most expensive price range rating:

<gd:rating rel="http://schemas.google.com/g/2005#price" value="5" min="1" max="5"/>

Schema

start = rating

rating =
   element gd:rating {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute value { xs:int },
      attribute min { xs:int },
      attribute max { xs:int }
   }

gd:recurrence

Represents the dates and times when a recurring event takes place.

The string that defines the recurrence consists of a set of properties, each of which is defined in the iCalendar standard (RFC 2445).

Specifically, the string usually begins with a DTSTART property that indicates the starting time of the first instance of the event, and often a DTEND property or a DURATION property to indicate when the first instance ends. Next come RRULE, RDATE, EXRULE, and/or EXDATE properties, which collectively define a recurring event and its exceptions (but see below). (See section 4.8.5 of RFC 2445 for more information about these recurrence component properties.) Last comes a VTIMEZONE component, providing detailed timezone rules for any timezone ID mentioned in the preceding properties.

Google services like Google Calendar don't generally generate EXRULE and EXDATE properties to represent exceptions to recurring events; instead, they generate <gd:recurrenceException> elements. However, Google services may include EXRULE and/or EXDATE properties anyway; for example, users can import events and exceptions into Calendar, and if those imported events contain EXRULE or EXDATE properties, then Calendar will provide those properties when it sends a <gd:recurrence> element.

Note the the use of <gd:recurrenceException> means that you can't be sure just from examining a <gd:recurrence> element whether there are any exceptions to the recurrence description. To ensure that you find all exceptions, look for <gd:recurrenceException> elements in the feed, and use their <gd:originalEvent> elements to match them up with <gd:recurrence> elements.

Properties

Property Type Description
text() xs:string Recurrence description.

Example

A recurring event that takes place every morning from 6:00 to 7:00 a.m., Pacific time, from March 14 through March 21, 2006:

<gd:recurrence>
  DTSTART;TZID=America/Los_Angeles:20060314T060000
  DURATION:PT3600S
  RRULE:FREQ=DAILY;UNTIL=20060321T220000Z
  BEGIN:VTIMEZONE
  TZID:America/Los_Angeles
  X-LIC-LOCATION:America/Los_Angeles
  BEGIN:STANDARD
  TZOFFSETFROM:-0700
  TZOFFSETTO:-0800
  TZNAME:PST
  DTSTART:19671029T020000
  RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU
  END:STANDARD
  BEGIN:DAYLIGHT
  TZOFFSETFROM:-0800
  TZOFFSETTO:-0700
  TZNAME:PDT
  DTSTART:19870405T020000
  RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=1SU
  END:DAYLIGHT
  END:VTIMEZONE
</gd:recurrence>

Schema

start = recurrence

recurrence =
   element gd:recurrence {
      gdCommonProperties,
      ( xs:string }
   }

gd:recurrenceException

Represents an event that's an exception to a recurring event—that is, an instance of a recurring event in which one or more aspects of the recurring event (such as attendance list, time, or location) have been changed.

Contains a <gd:originalEvent> element that specifies the original recurring event that this event is an exception to.

When you change an instance of a recurring event, that instance becomes an exception. Depending on what change you made to it, the exception behaves in either of two different ways when the original recurring event is changed:

For example, say you have a meeting every Tuesday and Thursday at 2:00 p.m. If you change the attendance list for this Thursday's meeting (but not for the regularly scheduled meeting), then it becomes an exception. If you change the time for this Thursday's meeting (but not for the regularly scheduled meeting), then it becomes specialized.

Regardless of whether an exception is specialized or not, if you do something that deletes the instance that the exception was derived from, then the exception is deleted. Note that changing the day or time of a recurring event deletes all instances, and creates new ones.

For example, after you've specialized this Thursday's meeting, say you change the recurring meeting to happen on Monday, Wednesday, and Friday. That change deletes all of the recurring instances of the Tuesday/Thursday meeting, including the specialized one.

If a particular instance of a recurring event is deleted, then that instance appears as a <gd:recurrenceException> containing a <gd:entryLink> that has its <gd:eventStatus> set to "http://schemas.google.com/g/2005#event.canceled". (For more information about canceled events, see RFC 2445.)

Properties

Property Type Description
@specialized xs:boolean Indicates whether the exception is specialized or not.
gd:entryLink entryLink An Event entry providing the details about the exception.
gd:originalEvent originalEvent The original recurring event that this is an exception to.

Example

An exception to a recurring event (with some pieces replaced by brief italicized identifiers for clarity):

<gd:recurrenceException specialized="true">
  <gd:entryLink>
    <entry>
      <id>i8fl1nrv2bl57c1qgr3f0onmgg_20060317T220000Z</id>
      <published>2006-03-17T23:00:00.000Z</published>
      <updated>2006-03-14T21:33:12.000Z</updated>
      <category scheme="http://schemas.google.com/g/2005#kind"
        term="http://schemas.google.com/g/2005#event"/>
      <title type="text">recurrence</title>
      <content type="text"/>
      <link rel="alternate" type="text/html"
        href="http://www.google.com/calendar/event?eid=idString"
        title="alternate"/>
      <author>
        <name>exception</name>
      </author>
      <gd:eventStatus
        value="http://schemas.google.com/g/2005#event.confirmed"/>
      <gd:comments>
        <gd:feedLink
            href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID/comments/">
          <feed>
            <updated>2006-03-14T21:36:23.250Z</updated>
            <title type="text">Comments for: recurrence</title>
            <link rel="alternate" type="text/html"
              href="http://www.google.com/calendar/feeds/userID/private-magicCookie/full/eventID/comments/"
              title="alternate"/>
          </feed>
        </gd:feedLink>
      </gd:comments>
      <gd:transparency
        value="http://schemas.google.com/g/2005#event.opaque "/>
      <gd:originalEvent id="i8fl1nrv2bl57c1qgr3f0onmgg"
          href="http://www.google.com/calendar/feeds/userID/private-magicCookie/composite/eventID">
        <gd:when startTime="2006-03-17T22:00:00.000Z"/>
      </gd:originalEvent>
      <gd:where valueString="Home"/>
      <gd:when startTime="2006-03-17T23:00:00.000Z"
        endTime="2006-03-18T00:00:00.000Z"/>
    </entry>
  </gd:entryLink>
</gd:recurrenceException>

Schema

start = recurrenceException

recurrenceException =
   element gd:recurrenceException {
      attribute specialized { xs:boolean },

      (xs:string)
   }

gd:reminder

Most often used in: <gd:when>

A time interval, indicating how long before the containing entity's @startTime or @dueTime attribute a reminder should be issued. Alternatively, may specify an absolute time at which a reminder should be issued.

Properties

Property Type Description
@absoluteTime? xs:dateTime Absolute time at which the reminder should be issued. This is typically used when a user uses a "snooze" feature to delay a previous reminder. If the timezone is not specified, the observer's local time is assumed.
@days? xs:unsignedInt Period of time before gd:when/@startTime when a reminder should be issued. If the parent entity's target time is a date rather than a specific time, then these attributes are relative to midnight (00:00) on that date.
@hours? xs:unsignedInt
@minutes? xs:unsignedInt

Restrictions

Examples

A 15-minute reminder for a meeting:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00">
  <gd:reminder minutes="15"/>
</gd:when>

Same meeting as above, but snoozed for 10 minutes after the reminder at 16:45:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00">
  <gd:reminder minutes="15"/>
  <gd:reminder absoluteTime="2005-06-06T16:55:00-08:00"/>
</gd:when>

Schema

start = reminder

reminder =
   element gd:reminder {
      gdCommonProperties,
      attribute absoluteTime { xs:dateTime }?,
attribute days { xs:unsignedInt }?, attribute hours { xs:unsignedInt }?, attribute minutes { xs:unsignedInt }? }

gd:when

Represents a period of time or an instant.

Properties

Property Type Description
@endTime? xs:dateTime or xs:date Describes when the event ends. If the timezone is not specified, the observer's local timezone is assumed.
@startTime xs:dateTime or xs:date Describes when the event starts or (for zero-duration events) when it occurs. If the timezone is not specified, the observer's local timezone is assumed.
@valueString? xs:string A simple string value that can be used as a representation of this time period.

Restrictions

Examples

A one-day event:

<gd:when startTime="2005-06-06"/>

A two-day event with a string description:

<gd:when startTime="2005-06-06" endTime="2005-06-07" valueString="This weekend"/>

A one-hour meeting:

<gd:when startTime="2005-06-06T17:00:00-08:00" endTime="2005-06-06T18:00:00-08:00"/>

A zero-duration event:

<gd:when startTime="2005-06-06T17:00:00-08:00"/>

Schema

start = when

when =
   element gd:when {
      gdCommonProperties,
      attribute startTime { choice(xs:date, xs:dateTime) },
      attribute endTime { choice(xs:date, xs:dateTime) }?
      attribute valueString { xs:string }?,
   }

gd:where

A place (such as an event location) associated with the containing entity. The type of the association is determined by the rel attribute; the details of the location are contained in an embedded or linked-to Contact entry.

A <gd:where> element is more general than a <gd:geoPt> element. The former identifies a place using a text description and/or a Contact entry, while the latter identifies a place using a specific geographic location.

Properties

Property Type Description
@label? xs:string Specifies a user-readable label to distinguish this location from other locations.
@rel? xs:string Specifies the relationship between the containing entity and the contained location. Possible values (see below) are defined by other elements. For example, <gd:when> defines http://schemas.google.com/g/2005#event.
@valueString? xs:string A simple string value that can be used as a representation of this location.
gd:entryLink? entryLink Entry representing location details. This entry should implement the Contact kind.

rel values

Value Description
http://schemas.google.com/g/2005#event or not specified Place where the enclosing event takes place.
http://schemas.google.com/g/2005#event.alternate A secondary location. For example, a remote site with a videoconference link to the main site.
http://schemas.google.com/g/2005#event.parking A nearby parking lot.

Examples

Event location:

<gd:where valueString="Google Cafeteria (Building 40)"/>

More complicated event location:

<gd:where rel="http://schemas.google.com/g/2005#event" valueString="Joe's Pub">
  <gd:entryLink href="http://local.example.com/10018/JoesPub">
    <gd:entry>
      <id>http://local.example.com/10018/JoesPub</id>
      <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/g/2005#contact"/>
      <content>Nice place to listen to jazz music</content>
      <link href="http://www.joespub.com"/>
      <gd:contactSection>
        <gd:postalAddress>500 West 45th Street, New York, NY 10018</gd:postalAddress>
        <gd:geoPt lat="40.75" lon="-74.0"/>
        <gd:phoneNumber>(212) 555-1212</gd:phoneNumber>
        <gd:email address="info@joespub.com"/>
      </gd:contactSection>
    </gd:entry>
  </gd:entryLink>
</gd:where>

Event with multiple locations:

<gd:where label="Mountain View Location (main)"
         valueString="Google Cafeteria (Building 40)"/>

<gd:where rel="http://schemas.google.com/g/2005#event.alternate"
         label="New York Location (videoconference)"
         valueString="Metropolis"/>

Schema

start = where

where =
   element gd:where {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute label { xs:string }?,
      attribute valueString { xs:string }?,
      (entryLink?)
   }

gd:who

A person associated with the containing entity. The type of the association is determined by the rel attribute; the details about the person are contained in an embedded or linked-to Contact entry.

The <gd:who> element can be used to specify email senders and recipients, calendar event organizers, and so on.

Properties

Property Type Description
@email? xs:string Email address. This property is typically used when <gd:entryLink> is not specified.
@rel xs:string Specifies the relationship between the containing entity and the contained person. See below for possible values.
@valueString? xs:string A simple string value that can be used as a representation of this person.
gd:attendeeStatus? gEnumConstruct Status of event attendee. Extensible enum documented below.
gd:attendeeType? gEnumConstruct Type of event attendee. Extensible enum documented below.
gd:entryLink? entryLink Entry representing person details. This entry should implement the Contact kind. In many cases, this entry will come from a contact feed.

rel values

The valid values for @rel depend on which kind the <gd:who> element appears in.

Value Kind Description
http://schemas.google.com/g/2005#event.attendee Event A general meeting/event attendee.
http://schemas.google.com/g/2005#event.organizer Event Event organizer. An organizer is not necessarily an attendee.
http://schemas.google.com/g/2005#event.performer Event Performer. Similar to http://schemas.google.com/g/2005#event.speaker, but with more emphasis on art than speech delivery.
http://schemas.google.com/g/2005#event.speaker Event Speaker.
http://schemas.google.com/g/2005#message.bcc Message Message BCC recipient.
http://schemas.google.com/g/2005#message.cc Message Message CC recipient.
http://schemas.google.com/g/2005#message.from Message Message (email or IM) sender.
http://schemas.google.com/g/2005#message.reply-to Message Intended recipient of a reply message.
http://schemas.google.com/g/2005#message.to Message Message primary recipient.

gd:attendeeType Values

Value Description
http://schemas.google.com/g/2005#event.optional Optional attendee.
http://schemas.google.com/g/2005#event.required Required attendee.

gd:attendeeStatus Values

Value Description
http://schemas.google.com/g/2005#event.accepted Attendee has accepted.
http://schemas.google.com/g/2005#event.declined Attendee has declined.
http://schemas.google.com/g/2005#event.invited Invitation has been sent, but the person has not accepted.
http://schemas.google.com/g/2005#event.tentative Attendee has accepted tentatively.

Examples

Email recipients:

<gd:who rel="http://schemas.google.com/g/2005#message.from" email="jo@example.com"/>
<gd:who rel="http://schemas.google.com/g/2005#message.to" valueString="Elizabeth" email="liz@example.com"/>

Meeting attendee:

<gd:who rel="http://schemas.google.com/g/2005#event.attendee" valueString="Jo">
  <gd:attendeeType value="http://schemas.google.com/g/2005#event.required"/>
  <gd:attendeeStatus value="http://schemas.google.com/g/2005#event.tentative"/>
  <gd:entryLink href="http://gmail.com/jo/contacts/Jo">
    <entry>
      <id>http://gmail.com/jo/contacts/Jo</id>
      <category term="user-tag" label="Google"/>
      <title>Jo March</title>
      <gd:contactSection>
        <gd:email address="jo@example.com"/>
        <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
      <gd:contactSection>
    </entry>
  </gd:entryLink>
</gd:who>

Event organizer:

<gd:who rel="http://schemas.google.com/g/2005#event.organizer" valueString="Receptionist 41"/>

Schema

start = who

who =
   element gd:who {
      gdCommonProperties,
      attribute rel { xs:string },
      attribute email { xs:string },
      (entryLink?
       & element gd:attendeeType { gEnumConstruct }?
       & element gd:attendeeStatus { gEnumConstruct }?)
   }

Last modified: