Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the Google Data APIs directory, many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see Google Accounts Authentication and Authorization.

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, 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 reference 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:

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/contact/2008#contact"/>

Note: If you're using the Contact kind in the context of the Contacts API, please remember that the Contact kind version 2.0 (described in this document) is used by the Contacts API since version 3.0 of the API.

Properties

Examples

<entry xmlns='http://www.w3.org/2005/Atom' xmlns:gd='http://schemas.google.com/g/2005'>
  <category scheme='http://schemas.google.com/g/2005#kind' 
      term='http://schemas.google.com/contact/2008#contact'/>
  <title>Elizabeth Bennet</title>
  <content>My good friend, Liz.  A little quick to judge sometimes, but nice girl.</content>
  <gd:email rel='http://schemas.google.com/g/2005#work' primary='true' address='liz@gmail.com'/>
  <gd:email rel='http://schemas.google.com/g/2005#home' address='liz@example.org'/>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#work' primary='true'>
    (206)555-1212
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#home'>
    (206)555-1213
  </gd:phoneNumber>
  <gd:phoneNumber rel='http://schemas.google.com/g/2005#mobile'>
    (206) 555-1212
  </gd:phoneNumber>
  <gd:im rel='http://schemas.google.com/g/2005#home' 
      protocol='http://schemas.google.com/g/2005#GOOGLE_TALK' 
      address='liz@gmail.com'/>
  <gd:postalAddress rel='http://schemas.google.com/g/2005#work' primary='true'>
    1600 Amphitheatre Pkwy 
    Mountain View, CA 94043
  </gd:postalAddress>
  <gd:postalAddress rel='http://schemas.google.com/g/2005#home'>
    800 Main Street
    Mountain View, CA 94041
  </gd:postalAddress>
  <gd:organization>
    <gd:orgName>Google, Inc.</gd:orgName>
    <gd:orgTitle>Tech Writer</gd:orgTitle>
  </gd:organization>
</entry>

Profile kind

Represents a profile associated with a Google user or other entity. The Profile kind shares much structure with the Contact kind. However, it differs in some ways: it cannot contain extended properties or be marked as deleted, for example.

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

The Profile kind was introduced in version 3.0 of the Contacts API.

Properties

Examples

<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gContact='http://schemas.google.com/contact/2008'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
  <category scheme='http://schemas.google.com/g/2005#kind'
  term='http://schemas.google.com/contact/2008#profile' />
  <title>Elizabeth Bennett</title>
  <gd:name>
    <gd:givenName>Elizabeth</gd:givenName>
    <gd:familyName>Bennett</gd:familyName>
  </gd:name>
  <gd:structuredPostalAddress rel='http://schemas.google.com/g/2005#work'>
    <gd:formattedAddress>Longbourne, Nr. Meryton, Hertfordshire, England</gd:formattedAddress>
  </gd:structuredPostalAddress>
</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

rel values for gd:where

gd:eventStatus values

gd:visibility values

gd:transparency values

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

Category @term values

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

rel values for gd:who

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
• gdCommonProperties
• gd:additionalName
• gd:comments
• gd:country
• gd:deleted
• gd:email
• gd:entryLink
• gd:extendedProperty
• gd:familyName
• gd:feedLink
• gd:geoPt
• gd:givenName
• gd:im
• gd:organization
• gd:orgDepartment
• gd:orgJobDescription
• gd:orgName
• gd:orgSymbol
• gd:orgTitle
• gd:originalEvent
• gd:phoneNumber
• gd:postalAddress
• gd:rating
• gd:recurrence
• gd:recurrenceException
• gd:reminder
• gd:structuredPostalAddress
• gd:when
• gd:where
• gd:who

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

Schema

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

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

gd:additionalName

Specifies additional (eg. middle) name of the person, eg. "Susan".

Properties

Example

<gd:additionalName yomi="'suz@n">Susan<gd:additionalName>

Schema

start = additionalName

additionalName =
   element gd:additionalName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:comments

Contains a comments feed for the enclosing entry (such as a calendar event.).

Properties

rel values

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:deleted

A marker element that, when present, indicates the containing entry is deleted.

Properties

None.

Schema

start = deleted

deleted =
   element gd:deleted

gd:country

Country name along with optional country code. The latter is given in accordance with ISO 3166-1 alpha-2.

Properties

Examples

<gd:country code='PL'>Poland</gd:country>
<gd:country>Gabon</gd:country>

Schema

start = country

country =
   element gd:country {
      attribute code { xs:string }?,
      xs:string?
   }

gd:email

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

Properties

rel values

Examples

<gd:email address="foo@bar.example.com" displayName="Foo Bar" />
<gd:email label="Personal" rel="http://schemas.google.com/g/2005#home" address="fubar@gmail.com" primary="true"/>

Schema

start = email

email =
   element gd:email {
      attribute address { xs:string },
      attribute displayName { xs:string }?,
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?
   }

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

Restrictions

• Either or both of @href or <atom:entry> must be present.
• If atom:entry is not present, the client can fetch the contents from the entry URI in @href. If atom:entry is present, the contents must be the same as what would be retrieved from @href at the time the entry was generated.
• When a PUT or a POST contains a <gd:entryLink> and the @href attribute is specified, the attribute's value is used to create a link; if the atom:entry element is also present, it is ignored. If the @href attribute is not specified, then the atom:entry element is either stored as an embedded entry or stored in another feed and linked to. Note that some services may not support all of these options.

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:email address="jo@example.com"/>
      <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
    </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:extendedProperty

Allows you to store a limited amount of custom data as an auxiliary property of the enclosing entity.

Note that the presence of anyForeignElement allows feed to optionally embed any valid XML within gd:extendedProperty element (mutually exclusive with value attribute).

Properties

Example

An external identifier for a calendar event:

<gd:extendedProperty name="http://www.example.com/schemas/2007#mycal.id"
  value="1234"></gd:extendedProperty> 

Additional xml for contact entry

<gd:extendedProperty name="com.google">
  <some_xml>value</some_xml>
</gd:extendedProperty>

Schema

start = extendedProperty

extendedProperty =
   element gd:extendedProperty {
      attribute name { xs:string },
      attribute value { xs:string } ?,
      (anyForeignElement*),
      attribute realm { xs:string } ?
   }

gd:familyName

Specifies family name of the person, eg. "Smith".

Properties

Example

<gd:familyName yomi="smɪð">Smith<gd:familyName>

Schema

start = familyName

familyName =
   element gd:familyName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:feedLink

Represents a logically nested feed. For example, a calendar feed might have a nested feed representing all comments on entries.

Properties

Restrictions

• Either or both of @href or <atom:feed> must be present.
• If atom:feed is not present, the client can fetch the contents from the URI in @href. If it is present, the contents must the same as what would be retrieved from @href at the time the feed was generated.
• When a PUT or a POST contains a <gd:feedLink> and the @href attribute is specified, the attribute's value is used to create a link; if the <atom:feed> element is also present, it is ignored. If the @href attribute is not specified, then the <atom:feed> element is stored as an embedded feed. Note that some services may not support all of these options.

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).

Deprecated. This element is deprecated. For geotagging data, use GeoRSS instead.

Properties

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

rel values

protocol attribute values

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

Examples

An IM address for MSN Messenger:

<gd:im protocol="http://schemas.google.com/g/2005#MSN" address="foo@bar.msn.com" rel="http://schemas.google.com/g/2005#home" primary="true"/>

A user-provided IM address with 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 address { xs:string },
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute protocol { xs:string }?,
      attribute primary { xs:boolean }?
   }

gd:givenName

Specifies given name of the person, eg. "John".

Properties

Example

<gd:givenName yomi="dʒon">John<gd:givenName>

Schema

start = givenName

givenName =
   element gd:givenName {
      attribute yomi { xs:string }?,
      (xs:string)
   }

gd:money

Specifies an amount of money in a particular currency.

Properties

Example

<gd:money amount='650.0' currencyCode='EUR'/>

Schema

element gd:money {
  attribute amount { xsd:float },
  attribute currencyCode { xsd:string }
}

gd:name

Allows storing person's name in a structured way. Consists of given name, additional name, family name, prefix, suffix and full name.

Properties

Example

Structured representation of Sir Winston Leonard Spencer-Churchill, KG

<gd:name>
  <gd:givenName>Winston</gd:givenName>
  <gd:additionalName>Leonard</gd:additionalName>
  <gd:familyName>Spencer-Churchill</gd:familyName>
  <gd:namePrefix>Sir</gd:namePrefix>
  <gd:nameSuffix>OG</gd:nameSuffix>
</gd:name>

Schema

start = name

name =
   element gd:name {
      givenName?
      & additionalName?
      & familyName?
      & namePrefix?
      & nameSuffix?
   }

Restrictions

• Unstructured component of the name should be consistent with its structured representation.

gd:organization

An organization, typically associated with a contact.

Properties

rel values

Examples

<gd:organization rel="http://schemas.google.com/g/2005#work" label="Work" primary="true">
  <gd:orgName>Google, Inc.</gd:orgName>
  <gd:orgTitle>Tech Writer</gd:orgTitle>
  <gd:orgJobDescription>Writes documentation</gd:orgJobDescription>
  <gd:orgDepartment>Software Development</gd:orgDepartment>
  <gd:orgSymbol>GOOG</gd:orgSymbol>
</gd:organization>

Schema

start = organization

organization =
   element gd:organization {
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?,
      ( orgDepartment? &
      orgJobDescription? &
      orgName? &
      orgSymbol? &
      orgTitle? &
      where? )
   }

gd:orgDepartment

Describes a department within an organization. Must appear within a gd:organization element.

Example

<gd:orgDepartment>Research and Development</gd:orgDepartment>

Schema

start = orgDepartment

orgDepartment = element gd:orgDepartment { xs:string }

gd:orgJobDescription

Describes a job within an organization. Must appear within a gd:organization element.

Example

<gd:orgJobDescription>Documenting public APIs</gd:orgJobDescription>

Schema

start = orgJobDescription

orgJobDescription = element gd:orgJobDescription { xs:string }

gd:orgName

The name of the organization. Must appear within a gd:organization element.

Properties

Example

<gd:orgName>Google, Inc.</gd:orgName>

Schema

start = orgName

orgName =
   element gd:orgName {
     attribute yomi {xs:string},
     xs:string
   }

gd:orgSymbol

Provides a symbol of an organization. Must appear within a gd:organization element.

Example

<gd:orgSymbol>GOOG</gd:orgSymbol>

Schema

start = orgSymbol

orgSymbol = element gd:orgSymbol { xs:string }

gd:orgTitle

The title of a person within an organization. Must appear within a gd:organization element.

Example

<gd:orgTitle>President and CEO</gd:orgTitle>

Schema

start = orgTitle

orgTitle =
   element gd:orgTitle { xs:string }

gd:originalEvent

Equivalent to the Recurrence ID property specified in section 4.8.4.4 of RFC 2445. Appears in every instance of a recurring event, to identify the original event.

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

Properties

Example

Specifying an original 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 },
      when
   }

gd:phoneNumber

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

Properties

rel values

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>

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 }?,
      attribute primary { xs:boolean }?,
      (xs:string)
   }

gd:postalAddress

A postal address.

Properties

rel values

Examples

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

Schema

start = postalAddress

postalAddress =
   element gd:postalAddress {
      attribute label { xs:string }?,
      attribute rel { xs:string }?,
      attribute primary { xs:boolean }?,
      (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

rel values

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"/>

Rated by 200 users with an average rating of 4.65 out of 5:

<gd:rating average="4.65" min="1" max="5" numRaters="200"/>

Schema

start = rating

rating =
   element gd:rating {
      gdCommonProperties,
      attribute rel { xs:string }?,
      attribute value { xs:int }?,
      attribute average { xs:float }?,
      attribute min { xs:int },
      attribute max { xs:int },
      attribute numRaters { 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

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 {
      (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:

• If you add, change, or remove comments, attendees, or attendee responses, then the exception remains tied to the original event, and changes to the original event also change the exception.
• If you make any other changes to the exception (such as changing the time or location) then the instance becomes "specialized," which means that it's no longer as tightly tied to the original event. If you change the original event, specialized exceptions don't change. But see below.

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

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 },
      (entryLink
       & originalEvent)
   }

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. Also specifies a notification method, indicating what medium the system should use to remind the user.

Properties

When you create or edit a <gd:when> entry, use the following conventions to achieve particular results:

• To tell the service to use the user's default reminders, include a <gd:reminder> element with no attributes. If you specify a duration but no method attribute, then the service uses the user's default notification methods with the duration you specified.
• To tell the service to not issue any reminders for the event (or to remove existing reminders when updating an event), don't include any <gd:reminder> elements.

Restrictions

• At most one of @days, @hours, @minutes, or @absoluteTime may be specified. To specify a mixed duration, convert to the most precise unit. For example, to specify 1 hour 30 minutes, use @minutes="90".
• You can't use negative values for the attributes (so if you want a reminder to occur after the start time, you must use @absoluteTime).
• A given event can't have more than five reminders associated with it.
• When you're adding a reminder to an event, if you specify the alert, email, or sms methods, you must also specify a duration.

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 method { xs:string }?,
      attribute days { xs:unsignedInt }?,
      attribute hours { xs:unsignedInt }?,
      attribute minutes { xs:unsignedInt }?
   }

gd:resourceId

An opaque resource identifier, distinct from atom:id as it need not be a valid URI. Some services provide a separate identifier to be used when constructing subsequent requests. Exact usage is service specific.

Example

<gd:resourceId>9749638</gd:resourceId>

Schema

start = resourceId

resourceId =
   element gd:resourceId { xs:string }

gd:structuredPostalAddress

Postal address split into components. It allows to store the address in locale independent format. The fields can be interpreted and used to generate formatted, locale dependent address. The following elements reperesent parts of the address: agent, house name, street, P.O. box, neighborhood, city, subregion, region, postal code, country. The subregion element is not used for postal addresses, it is provided for extended uses of addresses only. In order to store postal address in an unstructured form formatted address field is provided.

Properties

rel values

mailClass values

usage values

Examples

Corporate address:

<gd:structuredPostalAddress mailClass='http://schemas.google.com/g/2005#letters' label='John at Google'>
  <gd:street>1600 Amphitheatre Parkway</gd:street>
  <gd:city>Mountain View</gd:city>
  <gd:region>CA</gd:region>
  <gd:postcode>94043</gd:postcode>
</gd:structuredPostalAddress>

Private address:

<gd:structuredPostalAddress mailClass='http://schemas.google.com/g/2005#both' label='Madame Duval'>
  <gd:street>27, rue Pasteur</gd:street>
  <gd:city>CABOURG</gd:city>
  <gd:postcode>14390</gd:postcode>
  <gd:country>FRANCE</gd:country>
</gd:structuredPostalAddress>

Schema

start = structuredPostalAddress

structuredPostalAddress =
   element gd:structuredPostalAddress {
      attribute label { xs:string }?,
      attribute mailClass { xs:string }?,
      attribute primary { xs:boolean }?,
      attribute rel { xs:string }?,
      attribute usage { xs:string }?,
      (agent?
       & housename?
       & street?
       & poBox?
       & neighborhood?
       & city?
       & subregion?
       & region?
       & postcode?
       & country?
       & formattedAddress? )
}

Restrictions

• It is forbidden to have both 'gd:postalAddress' and 'gd:structuredPostalAddress' in one entity.
• Only one structured address can be specified as primary.
• The unstructured postal address must be consistent with the structured data.

gd:when

Represents a period of time or an instant.

Properties

Restrictions

• It's not possible to mix xs:dateTime with xs:date in startTime/endTime.
• If endTime is not specified, then the event is considered to be an instant in time (if @startTime includes a time) or a one-day event (if @startTime is only a date).

Examples

A one-day event:

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

Alternative representation of a one-day event:

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

A two-day event (on June 6 and June 7) with a string description:

<gd:when startTime="2005-06-06" endTime="2005-06-08" 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 { (xs:date | xs:dateTime) },
      attribute endTime { (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

rel values

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: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: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

rel values

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

gd:attendeeType Values

gd:attendeeStatus Values

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:email address="jo@example.com"/>
      <gd:phoneNumber label="work">(650) 555-1212</gd:phoneNumber>
    </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 }?,
      attribute valueString { xs:string }?,
      (entryLink?
       & element gd:attendeeType { gEnumConstruct }?
       & element gd:attendeeStatus { gEnumConstruct }?)
   }

Back to top

Changes since 1.0

Changes to the contact kind

The following elements not present in version 1.0 were added in version 2.0 of the contact kind:

• gd:name
• gd:structuredPostalAddress
• gd:where

The following phone types not present in version 1.0 were added in version 2.0:

• http://schemas.google.com/g/2005#assistant
• http://schemas.google.com/g/2005#callback
• http://schemas.google.com/g/2005#car
• http://schemas.google.com/g/2005#company_main
• http://schemas.google.com/g/2005#isdn
• http://schemas.google.com/g/2005#main
• http://schemas.google.com/g/2005#other_fax
• http://schemas.google.com/g/2005#radio
• http://schemas.google.com/g/2005#telex
• http://schemas.google.com/g/2005#tty_tdd
• http://schemas.google.com/g/2005#work_mobile
• http://schemas.google.com/g/2005#work_pager

The following IM type not present in version 1.0 was added in version 2.0:

• http://schemas.google.com/g/2005#netmeeting

The following elements of the 1.0 contact kind are no longer supported:

• atom:title — still present in entries returned by the server, but ignored on PUT and POST requests. Replaced by gd:name.
• gd:postalAddress — replaced by gd:structuredPostalAddress.

Changes to gd:email

The new attribute @displayName was added in gd:email in 2.0

Changes to gd:organization

The following subelements of gd:organization were introduced in 2.0:

• gd:orgDepartment
• gd:orgJobDescription
• gd:orgSymbol
• gd:where

Changes to gd:orgName

In version 2.0 the element gd:orgName was enhanced by adding the @yomi attribute to it.

Back to top