Default
can also be used instead of the user's e-mail address (it tells the server to return the contact groups for the user whose credentials accompany the request).full
would have the following URL:default
value) and projection:full
can be obtained using the URL:default
for the user's email address, which tells the server toreturn the contact groups for the authenticated user whose credentials accompany the request.value
(arbitrary string) or an XMLblob (these are mutually exclusive; instead of a valid XML blob plain text can be used).Each contact may have at most ten (10) extended properties associated. Each of them should be reasonably small, that is it should not be a photo, ringtone etc.full
, property-KEY
or thin
.full
projection, there are some other useful projections.Projection name | Description |
---|---|
thin | No gd:extendedProperty elements are returned/updated. |
property-KEY | KEY indicates the key of an extended property (gd:extendedProperty element) that will be returned (for GET) or should be updated (for PUT/POST). Absence of the extended property during update operation deletes the property. |
full | All gd:extendedProperty elements are returned and all of them have to be included during an update. |
Name | Description |
---|---|
alt | The type of feed to return, such as atom (the default), rss , or json . |
q | Fulltext query on contacts data fields. The API currently supports simple search queries such as q=term1 term2 term3 and exact search queries such as q='term1 term2 term3' |
max-results | The maximum number of entries to return. If you want to receive all of the contacts, rather than only the default maximum, you can specify a very large number for max-results . |
start-index | The 1-based index of the first result to be retrieved (for paging). |
updated-min | The lower bound on entry update dates. |
Name | Description |
---|---|
orderby | Sorting criterion. The only supported value is lastmodified . |
showdeleted | Include deleted contacts in the returned contacts feed. Deleted contacts are shown as entries that contain nothing but an <atom:id> element and a <gd:deleted> element. (Google usually retains placeholders for deleted contacts for 30 days after deletion; during that time, you can request the placeholders using the showdeleted query parameter.) Valid values are true or false . When the server decides it cannot guarantee that it still has information about all deleted contacts pertinent to the query, then it's behavior depends on the value of the requirealldeleted query parameter. |
requirealldeleted | Only relevant if showdeleted and updated-min are also provided. It dictates the behavior of the server in case it detects that placeholders of some entries deleted since the point in time specified as updated-min may have been lost. If requirealldeleted is false , the server simply returns all the placeholders it still knows about. If true , the server returns the 410 HTTP response code. The default value is false . |
sortorder | Sorting order direction. Can be either ascending or descending . |
group | Constrains the results to only the contacts belonging to the group specified. Value of this parameter specifies group ID (see also: gContact:groupMembershipInfo ). |
<atom:entry>
element that contains various extension elements from the Google Data namespace. Besides these standard extensions, the Contacts API also supports additional extensionsbelonging to the gContact namespace.category
element indicating that the entry is a contact looks like this:rel
attribute or a label
attribute, but not both, for the following elements:gd:email
gd:im
gd:organization
gd:phoneNumber
gd:postalAddress
rel
and label
(or neither) for any of those elements, then the server rejects the entry.gd
namespace:gd:when
gd:when
as a subelement of gContact:event
.@startTime
attribute is supported. Furthermore, its value must be a pure date,without the time component.gd:where
gd:where
element can be used in two contexts: directly under an entry of the Contact kind,or as a subelement of gd:organization
.gd:where
element in all its generality: the only supported property is the @valueString
attribute.@rel
and @label
, as well as the gd:entryLink
subelement, are not supported.@valueString
property is the only supported one, it is required.gd:structuredPostalAddress
gd:structuredPostalAddress
are supported by the Contacts API.gd:agent
, gd:housename
, and gd:subregion
subelements,and the attributes mailClass
and usage
.gd:extendedProperty
, which stores client-specific properties (see: Extended properties and projections).full
projection):full
or property-NAME
projection.atom:link
<atom:link>
element with rel='http://schemas.google.com/contacts/2008/rel#photo'
provides a URL (in its href
attribute) for adding, retrieving, updating, or deleting a contact's photo.gd:etag
attribute.Extension element | Description |
---|---|
gContact:billingInformation ? | Contacts billing information. |
gContact:birthday ? | Contact's birthday. |
gContact:calendarLink * | Link to a calendar associated with the contact. |
gContact:directoryServer ? | Directory server associated with the contact. |
gContact:event * | Event associated with the contact. |
gContact:externalId * | External identifier associated with the contact as set by a client |
gContact:gender ? | Gender associated with the contact. |
gContact:groupMembershipInfo * | Group membership information. |
gContact:hobby * | Hobby associated with the contact. |
gContact:initials ? | Contact's initials. |
gContact:jot * | Jot associated with the contact. |
gContact:language * | Language associated with the contact. |
gContact:maidenName ? | Maiden name associated with the contact. |
gContact:mileage ? | Mileage associated with the contact. |
gContact:nickname ? | Nickname associated with the contact. |
gContact:occupation ? | Occupation associated with the contact. |
gContact:priority ? | Priority ascribed to the contact. |
gContact:relation * | Relation associated with the contact. |
gContact:sensitivity ? | Sensitivity ascribed to the contact. |
gContact:shortName ? | Contact's short name. |
gContact:subject ? | Subject associated with the contact. |
gContact:userDefinedField * | User defined field attached to the contact. |
gContact:website * | Website associated with the contact. |
protocol
attribute of the gd:im element.Property | Description |
---|---|
atom:category | Scheme: http://schemas.google.com/g/2005#kind |
atom:updated | The modification time for a group is greater than or equal to the time the user actually modified the item. Applications should not use the modification time to break ties. |
atom:title | Group's name. |
atom:content | Group's name. Not directly updatable; changes whenever the name of the group is updated via atom:title. |
gd:deleted | If present, denotes, that the group was deleted. |
gd:extendedProperty * | Stores client-specific properties. There are client-specific projections created, that support independent read/modify on the properties. |
gContact:systemGroup ? | If present, indicates the group is a system group. |
group
parameter.http://schemas.google.com/contact/2008
contains many contacts-specific elements.gContact
.Property | Description |
---|---|
when | Birthday date, given in format YYYY-MM-DD (with the year), or --MM-DD (without the year). |
Property | Description |
---|---|
rel | Predefined calendar link type. Can be one of work , home or free-busy . |
label | User-defined calendar link type. |
primary | Boolean flag denoting the calendar link as primary. |
href | The URL of the calendar. |
rel
and label
are mutually exclusive (but one must be specified). Only one calendar link can be marked as primary at a time.Property | Type | Description |
---|---|---|
text() | xs:string | The name or address of the directory server. May not be empty or all whitespace. Other than that, the Contacts API does not constrain the form of the string describing the directory server in any way. |
Property | Type | Description |
---|---|---|
@label ? | xs:string | A simple string value used to name this event. It allows UIs to display a label such as 'Start Date'. May not be empty or all whitespace. |
@rel ? | xs:string | A programmatic value that identifies the type of event. |
gd:when | when | Gives the time of the event. Warning: not every correct gd:when can be used: its startTime attribute must be of type xs:date . |
Value | Description |
---|---|
anniversary | An anniversary |
other | Other event type |
label
and rel
attributes must be provided.Property | Type | Description |
---|---|---|
@label ? | xs:string | A simple string value used to name this ID. |
@rel | xs:string | A programmatic value that identifies the type of external ID. |
@value | xs:string | The value of this external ID. |
Value | Description |
---|---|
account | Contact's account number. |
customer | Contact's customer ID. |
network | Network identifier of the contact. |
organization | Identifier related to an organization the contact is associated with. |
Property | Description |
---|---|
value | The person's gender, either male or female |
Property | Description |
---|---|
href | Identifies the group to which the contact belongs or belonged. The group is referenced by its id. |
deleted='true' ? | Means, that the group membership was removed for the contact. This attribute will only be included if showdeleted is specified as query parameter, otherwise groupMembershipInfo for groups a contact does not belong to anymore is simply not returned. |
rel
attribute and a text value. The element can be repeated.Property | Description |
---|---|
rel | Specifies the type of the jot. Can be one of the following values: home , work , other , keywords , user . |
@label
attribute,or using the @code
attribute, whose value must conform to the IETF BCP 47specification.Property | Type | Description |
---|---|---|
@code ? | xs:string | A language code conforming to the IETF BCP 47 specification. The server returns an error if a nonconformant value is provided. |
@label ? | xs:string | A freeform name of a language. Must not be empty or all whitespace. |
<gContact:language>
element that makes use of the @code
attribute,the server is allowed to perform some normalization, for example to replace 'en-us'
with 'en-US'
.Property | Description |
---|---|
rel | Specifies contact's priority. Can be either low , normal or high . |
gContact:relation
element may be repeated.Property | Type | Description |
---|---|---|
@label ? | xs:string | A simple string value used to name this relation. The value must not be empty or all whitespace. |
@rel ? | xs:string | A programmatic value that identifies the type of relation. |
text() | xs:string | The entity in relation with the contact. |
Value | Description |
---|---|
assistant | Contact's assistant. |
brother | Contact's brother. |
child | Contact's child. |
domestic-partner | Contact's domestic partner. |
father | Contact's father. |
friend | Contact's friend. |
manager | Contact's manager. |
mother | Contact's mother. |
parent | Contact's parent. |
partner | Contact's (business) partner. |
referred-by | Contact's referrer. |
relative | Contact's relative. |
sister | Contact's sister. |
spouse | Contact's spouse. |
label
and rel
attributes must be provided.Property | Description |
---|---|
rel | Specifies contact's sensitivity. Can be either confidential , normal , personal or private . |
Property | Description |
---|---|
@id | System group identifier. |
id
id
attribute can have any one of the following values:Contacts
Friends
Family
Coworkers
Property | Type | Description |
---|---|---|
@key | xs:string | A simple string value used to name this field. Case-sensitive. |
@value | xs:string | The value of this field. |
Property | Type | Description |
---|---|---|
@href | xs:string | A link to the website. |
@label ? | xs:string | A simple string value used to name this website. |
@primary ? | xs:string | When multiple websites appear in an entry, indicates which is primary. At most one website may be primary. Default value is false . |
@rel | xs:string | A programmatic value that identifies the type of a website. |
Value | Description |
---|---|
home-page | The home page of the contact. |
blog | Contact's blog. |
profile | Contact's profile. |
home | Contact's home-related site. |
work | Contact's work-related site. |
other | Contact's site of other type. |
ftp | Contact's FTP site. |