# Frequently Asked Questions
## Overview
1. [What is a Google Data API?](https://developers.google.com/gdata/faq#whatis)
2. [I have a feature request or a bug report. Where should
I post?](https://developers.google.com/gdata/faq#feedback)
3. [Where should I ask a question on a particular
API?](https://developers.google.com/gdata/faq#discussion_groups)
4. [What is JSON?](https://developers.google.com/gdata/faq#json)
5. [Do I have to use XML? Are other data formats
available?](https://developers.google.com/gdata/faq#alternate_data_formats)
6. [Why are you using REST?](https://developers.google.com/gdata/faq#rest)
7. [Do you have any tips or short sample code for common issues?](https://developers.google.com/gdata/faq#tips)
8. [Does Gmail have a Data API?](https://developers.google.com/gdata/faq#GmailAtomFeed)
## Authentication
9. [What is the service name in ClientLogin for each Data
API?](https://developers.google.com/gdata/faq#clientlogin)
10. [When a user logs out of an application, is it necessary to
inform the API servers?](https://developers.google.com/gdata/faq#logout)
11. [Does a ClientLogin authentication token have
an expiration date?](https://developers.google.com/gdata/faq#clientlogin_expire)
12. [I have a general question about Google Accounts. Where
should I go?](https://developers.google.com/gdata/faq#accounts)
13. [How do I authenticate to an API?](https://developers.google.com/gdata/faq#authorization)
14. [What value should I use for the AuthSub/OAuth 1 scope
parameter?](https://developers.google.com/gdata/faq#AuthScopes)
15. [Are there different types of AuthSub tokens? Do
the tokens expire?](https://developers.google.com/gdata/faq#AuthAuthsubTokens)
16. [What is the main difference between ClientLogin
and AuthSub/OAuth 1?](https://developers.google.com/gdata/faq#which_auth_mech)
17. [Can I use ClientLogin authentication in 3rd
party web applications?](https://developers.google.com/gdata/faq#AuthClientLoginWebapps)
18. [What is a CAPTCHA?](https://developers.google.com/gdata/faq#captcha)
19. [How do I generate a CAPTCHA challenge?](https://developers.google.com/gdata/faq#need_captcha)
20. [Should I use ClientLogin in my web application?](https://developers.google.com/gdata/faq#clientlogin_web)
21. [How do I find out the user's username when using AuthSub/OAuth
1?](https://developers.google.com/gdata/faq#using_default)
22. [How do I use OAuth 1 with the Google Data API client
libraries?](https://developers.google.com/gdata/faq#OAuthLibraries)
23. [How do I use AuthSub with the Google Data API client
libraries?](https://developers.google.com/gdata/faq#AuthSubLibraries)
24. [How do I use ClientLogin with the Google Data
API client libraries?](https://developers.google.com/gdata/faq#ClientLoginLibraries)
## Client Libraries
25. [What programming languages have client libraries supported
by Google?](https://developers.google.com/gdata/faq#clientlibs)
26. [How do I report a bug or feature request for
one of the Google Data client libraries?](https://developers.google.com/gdata/faq#clientlib_feedback)
27. [How do I enable debugging options in the client
libraries?](https://developers.google.com/gdata/faq#clientlib_debug)
28. [Where can I find reference documents for the client library
classes?](https://developers.google.com/gdata/faq#javadoc)
## Troubleshooting
29. [What are some good tools for HTTP debugging?](https://developers.google.com/gdata/faq#debug_tools)
30. [How do I get HTTP logging information in the Java client
library?](https://developers.google.com/gdata/faq#java_log)
31. [How do I get HTTP logging information in the .NET client
library?](https://developers.google.com/gdata/faq#dotnet_log)
32. [How can I enable gzip encoding from Google Data feeds?](https://developers.google.com/gdata/faq#gzip)
33. [Why am I seeing an "Unable to Connect to sslv2" error when
using the PHP client?](https://developers.google.com/gdata/faq#phpsslv2)
34. [How do I get the Atom service document that describes
a feed?](https://developers.google.com/gdata/faq#atom_service_doc)
*** ** * ** ***
### Overview
What is a Google Data API?
: A Google Data API is an API based upon the [Google
Data protocol](https://developers.google.com/gdata/docs/developers-guide). The Google Data protocol is based on the [Atom
1.0](http://www.atomenabled.org/developers/syndication/atom-format-spec.php) and [RSS 2.0](http://feedvalidator.org/docs/rss2.html) syndication
formats, plus the [Atom
Publishing Protocol](http://ietfreport.isoc.org/idref/draft-ietf-atompub-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](https://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:
- [G Suite](https://developers.google.com/google-apps) (See individual APIs within the G Suite family)
- [Base](http://groups.google.com/group/Google-Base-data-API)
- [Blogger](http://groups.google.com/group/bloggerDev)
- [Calendar](http://groups.google.com/group/google-calendar-help-dataapi)
- [Code Search](http://groups.google.com/group/Google-Code-Search)
- [Contacts](http://groups.google.com/group/google-contacts-api)
- [Google Sites](http://groups.google.com/group/google-sites-data-api)
- [Spreadsheets](http://groups.google.com/group/google-spreadsheets-api)
- [Documents
List](http://groups.google.com/group/google-documents-list-api)
- [Federated
Login / OpenID](http://groups.google.com/group/google-federated-login-api)
- [Finance](http://groups.google.com/group/google-finance-apis)
- [Health](http://groups.google.com/group/googlehealthdevelopers)
- [Picasa
Web Albums](http://groups.google.com/group/Google-Picasa-Data-API)
- [Webmaster
Tools](http://groups.google.com/group/Google_Webmaster_Help)
- [YouTube](http://groups.google.com/group/youtube-api)
What is JSON?
: JSON refers to [JavaScript Object Notation](http://www.json.org).
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](https://developers.google.com/gdata/docs/json).
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](https://developers.google.com/gdata/docs/js) with [Blogger](https://developers.google.com/blogger/docs/1.0/developers_guide_js), [Contacts](https://developers.google.com/google-apps/contacts/v3), or [Calendar](https://developers.google.com/google-apps/calendar) services allows for both reading and writing data.
Read more about [Requesting and using JSON feeds](https://developers.google.com/gdata/docs/json#Request).
- `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](https://developers.google.com/gdata/docs/2.0/reference#Queries).
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](http://gdatatips.blogspot.com/) 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](http://gmail.google.com/support/bin/answer.py?answer=13465) with [AuthSub](https://developers.google.com/gdata/docs/auth/overview#authsub) or [OAuth
1](https://developers.google.com/gdata/docs/auth/overview#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](http://mail.google.com/support/bin/answer.py?hl=en&answer=75725) support.
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` |
| G Suite 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](https://developers.google.com/accounts/docs/AuthForInstalledApps).
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](https://developers.google.com/accounts/docs/AuthSub#AuthSubRevokeToken).
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](http://www.google.com/support/accounts/).
How do I authenticate to an API?
: Your HTTP request must include an Authorization header that contains a token
obtained by using either [ClientLogin](https://developers.google.com/accounts/docs/AuthForInstalledApps), [AuthSub](https://developers.google.com/accounts/docs/AuthSub),
or [OAuth 1](https://developers.google.com/accounts/docs/OAuth).
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`](https://developers.google.com/accounts/docs/AuthSub#AuthSubRevokeToken) API
call. A single use token can only be exchanged for a session token if the original [`AuthSubRequest`](https://developers.google.com/accounts/docs/AuthSub#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](https://developers.google.com/accounts).
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](http://en.wikipedia.org/wiki/Captcha).
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](https://developers.google.com/gdata/docs/auth/oauth).
How do I use AuthSub with the Google Data API client
libraries?
: See the article [Using AuthSub with the Google
Data API Client Libraries](https://developers.google.com/gdata/docs/auth/authsub).
How do I use ClientLogin with the Google Data API
client libraries?
: See the article [Using ClientLogin with
the Google Data API Client Libraries](https://developers.google.com/gdata/docs/auth/clientlogin).
What programming languages have client libraries supported
by Google?
: The [Java](https://developers.google.com/gdata/client-java), [.NET](https://developers.google.com/gdata/client-cs), [Python](https://code.google.com/p/gdata-python-client) and [Objective-C](https://code.google.com/p/gdata-objectivec-client/) client
libraries are officially supported by Google. In addition, our partner Zend
has written a [PHP client
library](https://framework.zend.com/manual/1.12/en/zend.gdata.html). 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](https://developers.google.com/gdata/docs/js) 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](http://groups.google.com/group/google-help-dataapi). 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](https://code.google.com/p/gdata-java-client/issues/list)
- [JavaScript](https://code.google.com/p/gdata-javascript-client/issues/list)
- [.NET](https://code.google.com/p/google-gdata/issues/list)
- [PHP](http://framework.zend.com/issues/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=10000&sorter/order=DESC&sorter/field=priority&resolution=-1&component=10088)
- [Python](https://code.google.com/p/gdata-python-client/issues/list)
- [Objective-C](https://code.google.com/p/gdata-objectivec-client/issues/list)
After posting your bug, create a thread in the [developer
forum](https://developers.google.com/gdata/faq#feedback) 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](https://developers.google.com/gdata/articles/debugging_client_libs)
Where can I find reference documents for the client library classes?
:
| Client Library | Reference Guide |
|---|---|
| Java | [Javadoc](https://developers.google.com/gdata/javadoc) |
| JavaScript | [JSdoc](https://developers.google.com/gdata/jsdoc/2.2) |
| .NET | [NDoc](http://google-gdata.googlecode.com/svn/docs/) |
| PHP | [phpDoc](https://framework.zend.com/manual/1.12/en/zend.gdata.html) |
| Python | [PyDoc](https://pythonhosted.org/gdata/index.html) |
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](https://developers.google.com/gdata/articles/wireshark) which describes in depth examples of both
WireShark and Fiddler.
[Wireshark](http://www.wireshark.org/)
: 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](http://www.fiddlertool.com/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](http://curl.haxx.se/)
: 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](https://developers.google.com/gdata/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 .
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](http://bitworking.org/projects/atom/rfc5023.html#appdocs) 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).