Google Data Protocol

Google Data APIs
- API Directory
- Client Library Downloads

Google Data Protocol
- Developer's Guide
- - Version 2.0
  - Version 1.0
- JSON Alt Type
- Batch Processing

More Resources
- Authentication
- Client Library
  - Using JavaScript
- Resumable Upload

Frequently Asked Questions

Overview

Authentication

Client Libraries

Troubleshooting

Overview

What is a Google Data API?

A Google Data API is an API based upon the Google Data protocol. The Google Data protocol is based on the Atom 1.0 and RSS 2.0 syndication formats, plus the Atom Publishing Protocol (APP).

The Google Data protocol extends those standards in various ways, using the extension mechanisms built into the standards. Feeds conform to either the Atom or RSS syndication formats. The publishing model conforms to the Atom Publishing Protocol.

The protocol also provides a general model for feeds, queries, and results. You can use it to send queries and updates to any Data API.

I have a feature request or a bug report. Where should I post?

Check out our issue tracker at http://code.google.com/p/gdata-issues/issues/list. Look for your feature request and star it to add your support and receive updates on its status.

Where should I ask a question on a particular API?

If your issue isn't listed here or you want further clarification, there are discussion groups specific to each Google Data API:

What is JSON?

JSON refers to JavaScript Object Notation.

JSON is a lightweight data interchange format whose simplicity has resulted in widespread use among web developers. It is easy to read and write; you can parse it using any programming language, and its structures map directly to data structures used in most programming languages.

Read more about Using JSON with the Google Data APIs.

Do I have to use XML? Are other data formats available?

The default data format for the Google Data APIs is XML, in the form of an Atom feed. However, when requesting a feed you can specify an alternative format using the alt query parameter.

alt=rss
The response data is formatted as an RSS feed.
alt=json or alt=json-in-script
Returns a JSON representation of the Atom feed's XML structure. The added benefit of JSON is that it is easier to "parse" in JavaScript client code. At this time, using JSON is only available as read-only option. However, using the JavaScript client library with Blogger, Contacts, or Calendar services allows for both reading and writing data.
Read more about Requesting and using JSON feeds.
alt=atom-in-script
Similar to alt=json-in-script, but results are returned as an Atom XML string rather than JSON.
alt=rss-in-script
Similar to alt=atom-in-script, but results are returned as an RSS XML string rather than Atom.

Read more about the alternate formats in the Google Data Reference Guide.

Why are you using REST?

REST is simple, lightweight, scalable, and maps very well to representing and exposing data.

Do you have any tips or short sample code for common issues?

You should browse the Google Data API Tips Blog for help with both our client libraries and making raw requests.

Does Gmail have a Data API?

No, but you can use Gmail's Atom feed with AuthSub or OAuth 1 to request read-only access to a user's unread messages. The scope should be set to https://mail.google.com/mail/feed/atom/. An example query would be:

GET https://mail.google.com/mail/feed/atom/

If you're interested in managing your mail, Gmail also has IMAP/POP support.

Authentication

In the Google Data APIs documentation, "OAuth" refers to OAuth 1; for OAuth 2.0 details, see the documentation for your individual API.

What is the service name in ClientLogin for each Data API?

A "service name" is a brief string that the ClientLogin authentication system uses to identify a Google service.

Google API	Service name
Google Analytics Data APIs	`analytics`
Google Apps APIs (Domain Information & Management)	`apps`
Google Sites Data API	`jotspot`
Blogger Data API	`blogger`
Book Search Data API	`print`
Calendar Data API	`cl`
Google Code Search Data API	`codesearch`
Contacts Data API	`cp`
Content API for Shopping	`structuredcontent`
Documents List Data API	`writely`
Finance Data API	`finance`
Gmail Atom feed	`mail`
Health Data API	`health` `weaver` (H9 sandbox)
Maps Data APIs	`local`
Picasa Web Albums Data API	`lh2`
Sidewiki Data API	`annotateweb`
Spreadsheets Data API	`wise`
Webmaster Tools API	`sitemaps`
YouTube Data API	`youtube`

For more information on the other parameters used in a ClientLogin request, see the ClientLogin documentation.

When a user logs out of an application, is it necessary to inform the API servers?

No, it is not necessary to inform the Google Data API when a user logs out of an application. However, if your application no longer needs to use an issued AuthSub token, it should revoke the token.

Does a ClientLogin authentication token have an expiration date?

A ClientLogin token can last for 2 weeks from the issue date, but this limit is service-specific and can be shorter.

I have a general question about Google Accounts. Where should I go?

Visit the Google Accounts Help Center.

How do I authenticate to an API?

Your HTTP request must include an Authorization header that contains a token obtained by using either ClientLogin, AuthSub, or OAuth 1.

What value should I use for the AuthSub/Oauth 1 scope parameter?

A scope parameter is required by AuthSub and OAuth 1 to identify which Google service(s) your application will have access to. For OAuth 2.0 details, see the documentation for your specific API.

Google API	ClientLogin Service Name
Google Analytics Data API	`https://www.google.com/analytics/feeds/`
Google Sites Data API	`http(s)://sites.google.com/feeds/`
Blogger Data API	`http://www.blogger.com/feeds/`
Book Search Data API	`http://www.google.com/books/feeds/`
Calendar Data API	`http(s)://www.google.com/calendar/feeds/`
Contacts Data API	`http(s)://www.google.com/m8/feeds/`
Content API for Shopping	`https://www.googleapis.com/auth/structuredcontent`
Documents List Data API	`http(s)://docs.google.com/feeds/`
Finance Data API	`http://finance.google.com/finance/feeds/`
Gmail Atom feed	`https://mail.google.com/mail/feed/atom/`
Health Data API	`https://www.google.com/health/feeds/` `https://www.google.com/h9/feeds/` (H9 sandbox)
Maps Data API	`http://maps.google.com/maps/feeds/`
Picasa Web Albums Data API	`http://picasaweb.google.com/data/`
Portable Contacts API	`http://www-opensocial.googleusercontent.com/api/people`
Sidewiki Data API	`http://www.google.com/sidewiki/feeds/`
Spreadsheets Data API	`http(s)://spreadsheets.google.com/feeds/`
Webmaster Tools API	`http://www.google.com/webmasters/tools/feeds/`
YouTube Data API	`http://gdata.youtube.com`

Are there different types of AuthSub tokens? Do the tokens expire?

There are two types of AuthSub tokens. The first is a single use token that is presented to your web application via the 'token' query parameter. This token expires the first time it is used with the service for which it was issued or when it is exchanged for a session token.

Session tokens do not expire unless the token is explicitly revoked via the user or the AuthSubRevokeToken API call. A single use token can only be exchanged for a session token if the original AuthSubRequest URL specified session=1 as a query parameter.

What is the main difference between ClientLogin and AuthSub/OAuth 1?

AuthSub is designed for web applications. It ensures that user credentials are securely sent directly from a user's web browser to Google's servers rather than through a 3rd party web site.

ClientLogin is for installed desktop applications. It requires the requesting application to transmit user credentials to Google on behalf of the user.

See the documentation on Google Account Authentication API.

Can I use ClientLogin authentication in third party web applications?

Using ClientLogin in third party web applications is acceptable, but strongly discouraged. As a best practice, the web application should never ask a user for their login credentials (this may be susceptible to snooping). Instead, an application should store user credentials server-side, and have a single "service-account" which is always used to authenticate with Google.

What is a CAPTCHA?

A CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is a type of challenge-response test used to determine whether or not the user is human. The term is trademarked by Carnegie Mellon University. See more details on Wikipedia. We have implemented CAPTCHA in ClientLogin.

How do I generate a CAPTCHA challenge?

A proprietary algorithm is used to determine when a CAPTCHA challenge is required during authentication. Repeated authentication attempts with bad credentials will often generate a CAPTCHA challenge.

Should I use ClientLogin in my web application?

No, ClientLogin should be used by installed applications on user-owned hardware. Usage of the ClientLogin API in web applications is insecure and strongly discouraged.

How do I find out the user's username when using AuthSub/OAuth 1?

Since you are only given a token from Google that grants access to the user's feeds, you may not know what their username is. This can pose a problem if the feed URL you want to use contains the username as part of it. In this case you can use the special username default to mean "the user whose authentication token I am using."

How do I use OAuth 1 with the Google Data API client libraries?

See the article Using OAuth 1 with the Google Data API Client Libraries.

How do I use AuthSub with the Google Data API client libraries?

See the article Using AuthSub with the Google Data API Client Libraries.

How do I use ClientLogin with the Google Data API client libraries?

See the article Using ClientLogin with the Google Data API Client Libraries.

Client Libraries

What programming languages have client libraries supported by Google?

The Java , .NET, Python and Objective-C client libraries are officially supported by Google. In addition, our partner Zend has written a PHP client library. Using these libraries, you can construct Google Data protocol requests, send them to a service, and process server responses. There is also a JavaScript client library that currently only supports Blogger, Calendar, and Google Contacts.

If you write a client library in a language other than Java, .Net, Python or Objective-C, and would like to share with the Data API developer community, post in the Google Data APIs discussion group. We would love to hear from you!

How do I report a bug or feature request for one of the client libraries?

Bugs or feature requests for the client libraries can be reported at the following locations:

After posting your bug, create a thread in the developer forum for the appropriate API.

How do I enable debugging options in the Google Data API client libraries?

Please see the following article for information on enabling debugging with some of the client libraries: Debugging Google Data API Clients: Exploring Traffic from Within your Program

Where can I find reference documents for the client library classes?

Client Library	Reference Guide
Java	Javadoc
JavaScript	JSdoc
.NET	NDoc
PHP	phpDoc
Python	PyDoc

Troubleshooting

What are some good tools for HTTP debugging?

There are a number of tools listed below, but you may also want to read the article On the Wire: Network Capture Tools for API Developers which describes in depth examples of both WireShark and Fiddler.

Wireshark: Wireshark is a "network protocol analyzer." It provides the ability to capture network traffic and analyze the content. It is very useful in debugging the traffic occurring in libraries where you don't have direct access to the HTTP request and response streams. Traffic between your application and the authentication services cannot be analyzed using Wireshark as the communication is encrypted using SSL. Wireshark can also be used to analyze traffic captured using tools such as tcpdump. Wireshark is available from the developers as both source code and a Windows installer. Third-party packages are available for many platforms.
Fiddler: Fiddler is an "HTTP debugging proxy". If you can configure your code or runtime environment to use a proxy server for HTTP traffic, Fiddler will sit between your application and Google Data services where it will allow you to inspect the traffic. Fiddler 2 includes support for SSL. Fiddler is currently available only for Windows.
cURL: cURL is a command-line tool which can perform HTTP/HTTPS requests. It is very useful for quick testing of interactions with a service without having to first build HTTP support in your client.

How do I get HTTP logging information in the Java client library?

The Java client libraries use the java.util.logging package to enable logging of HTTP requests. This will allow you to enable logging of headers for requests and responses, as well as status codes and request URLs. It does not currently log the full request and response streams. The logger name used for these logs is com.google.gdata.client.http.HttpGDataRequest.

In the case that an error code is returned from the servers, an Exception is thrown. The exception classes inherit from com.google.gdata.util.ServiceException and include a public method called getResponseBody(). Look at the Javadoc for more information.

How do I get HTTP logging information in the .NET client library?

The .NET library uses the System.Diagnostics tracing methods to log the path of execution, if tracing is enabled. Also, in the case of an error, a GDataRequestException is thrown. The exception contains a ResponseString which allows you to access the body of the HTTP response.

How can I enable gzip encoding from Google Data feeds?

In order to receive a gzip encoded response from one of the Google Data APIs you must do two things: set an "Accept-Encoding" header and modify your user agent to contain the string "gzip". An example of properly formed headers:

User-Agent: my program (gzip)
Accept-Encoding: gzip

Why am I seeing an "Unable to Connect to sslv2" error when using the PHP client?

Beginning July 2009, we began to disable SSLv2 on our servers as a precautionary measure to improve security. Unfortunately, there is a bug in early versions of the PHP client library released before July 2007 (version 1.0.0 and earlier) that forces connections to use SSLv2. When connecting to a server that has SSLv2 disabled, this results in the following error:

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

To correct this error, upgrade to a newer release of the PHP client library, available from http://framework.zend.com/download.

If you are unable to upgrade to a newer release, you can fix this by adding the following code to your application, where $gdata is your existing instance of Zend_Gdata (or appropriate subclass):

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));

How do I get the Atom service document that describes a feed?

You can get the Atom service document by passing the alt=atom-service parameter in the request. Note: Only version 2 of the Google Data APIs will return a service document that conforms to the AtomPub service document syntax. The version 1 of the Google Data APIs will still return a service document but it is based upon an earlier AtomPub draft specification (there are syntax and namespace changes between the two versions).

Google Data Protocol

Google Data APIs