Frequently Asked Questions

Overview

1. What is a Google Data API?
3. I have a feature request or a bug report. Where should I post?
4. Where should I ask a question on a particular API?
5. What is JSON?
6. Do I have to use XML? Are other data formats available?
7. Why are you using REST?
8. Do you have any tips or short sample code for common issues?
9. Does Gmail have a Data API?

Authentication

10. What is the service name in ClientLogin for each Data API?
11. When a user logs out of an application, is it necessary to inform the API servers?
12. Does a ClientLogin authentication token have an expiration date?
13. I have a general question about Google Accounts. Where should I go?
14. How do I authenticate to an API?
15. What value should I use for the AuthSub/OAuth scope parameter?
16. Are there different types of AuthSub tokens? Do the tokens expire?
17. What is the main difference between ClientLogin and AuthSub/OAuth?
18. Can I use ClientLogin authentication in 3rd party web applications?
19. What is a CAPTCHA?
20. How do I generate a CAPTCHA challenge?
21. Should I use ClientLogin in my web application?
22. How do I find out the user's username when using AuthSub/OAuth?

Client Libraries

23. What programming languages have client libraries supported by Google?
24. How do I report a bug or feature request for one of the Google data client libraries?
25. How do I enable debugging options in the client libraries?
26. Where can I find reference documents for the client library classes?

Troubleshooting

27. What are some good tools for HTTP debugging?
28. How do I get HTTP logging information in the Java client library?
29. How do I get HTTP logging information in the .NET client library?
30. How can I enable gzip encoding from Google data feeds?

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:

• Google Apps
• Base
• Blogger
• Calendar
• Code Search
• Contacts
• Docs (Documents and Spreadsheets)
• Federated Login / OpenID
• Finance
• Health
• Notebook
• Picasa Web Albums
• Webmaster Tools
• YouTube

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

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 Apps Provisioning APIs	apps
Google Base Data API	gbase
Blogger Data API	blogger
Book Search Data API	print
Calendar Data API	cl
Google Code Search Data API	codesearch
Contacts Data API	cp
Documents List Data API	writely
Finance Data API	finance
Gmail Atom feed	mail
Health Data API	health weaver (H9 sandbox)
Notebook Data API	notebook
Picasa Web Albums Data API	lh2
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.

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

A scope parameter is required by AuthSub and OAuth to identify which Google service(s) your application will have access to.

Google API	Service name
Google Base Data API	http://www.google.com/base/feeds/
Blogger Data API	http://www.blogger.com/feeds/
Book Search Data API	http://www.google.com/books/feeds/
Calendar Data API	http://www.google.com/calendar/feeds/
Contacts Data API	http://www.google.com/m8/feeds/
Documents List Data API	http://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)
Picasa Web Albums Data API	http://picasaweb.google.com/data/
Spreadsheets Data API	http://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?

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?

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

---

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:

• Java
• JavaScript
• .NET
• PHP
• Python
• Objective-C

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