Google APIs.

Google APIs support based on the Apache HTTP Client.

Google APIs support based on the Apache HTTP Client v5.

Google's additions to OAuth 2.0 authorization as specified inUsing OAuth 2.0 to Access Google APIs.

Before using this library, you must register your application at theAPIs Console. The result of this registration process is a set of values that are known to both Google and your application, such as the "Client ID", "Client Secret", and "Redirect URIs".

These are the typical steps of the web server flow based on an authorization code, as specified inUsing OAuth 2.0 for Web Server Applications:

• Redirect the end user in the browser to the authorization page usingcom.google.api.client.googleapis.auth.oauth2.GoogleAuthorizationCodeRequestUrl to grant your application access to the end user's protected data.
• Process the authorization response usingcom.google.api.client.auth.oauth2.AuthorizationCodeResponseUrl to parse the authorization code.
• Request an access token and possibly a refresh token usingcom.google.api.client.googleapis.auth.oauth2.GoogleAuthorizationCodeTokenRequest.
• Access protected resources usingcom.google.api.client.googleapis.auth.oauth2.GoogleCredential. Expired access tokens will automatically be refreshed using the refresh token (if applicable).

These are the typical steps of the browser-based client flow specified inUsing OAuth 2.0 for Client-side Applications:

• Redirect the end user in the browser to the authorization page usingcom.google.api.client.googleapis.auth.oauth2.GoogleBrowserClientRequestUrl to grant your browser application access to the end user's protected data.
• Use theGoogle API Client library for JavaScript to process the access token found in the URL fragment at the redirect URI registered at theAPIs Console.

Batch for Google API's.

JSON batch for Google API's.

com.google.api.client.util.Beta
Support forGoogle Compute Engine.

com.google.api.client.util.Beta
Utilities for Account Manager for Google accounts on Android Eclair (SDK 2.1) and later.

com.google.api.client.util.Beta
Utilities based onGoogle Play services.

Google App Engine utilities for OAuth 2.0 for Google APIs.

com.google.api.client.util.Beta
Support for subscribing to topics and receiving notifications on servlet-based platforms.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.extensions.appengine.auth.oauth2 package.

com.google.api.client.util.Beta
Support for subscribing to topics and receiving notifications on servlet-based platforms.

com.google.api.client.util.Beta
Support for subscribing to topics and receiving notifications on servlet-based platforms usingjakarta.servlet namespace.

Google API's support based on thejava.net package.

Google's JSON support (see detailed package specification).

Package Specification

User-defined Partial JSON data models allow you to defined Plain Old Java Objects (POJO's) to define how the library should parse/serialize JSON. Each field that should be included must have an @com.google.api.client.util.Key annotation. The field can be of any visibility (private, package private, protected, or public) and must not be static. By default, the field name is used as the JSON key. To override this behavior, simply specify the JSON key use the optional value parameter of the annotation, for example@Key("name"). Any unrecognized keys from the JSON are normally simply ignored and not stored. If the ability to store unknown keys is important, usecom.google.api.client.json.GenericJson.

Let's take a look at a typical partial JSON-C video feed from the YouTube Data API (as specified inYouTube Developer's Guide: JSON-C / JavaScript)

"data":{"updated":"2010-01-07T19:58:42.949Z","totalItems":800,"startIndex":1,"itemsPerPage":1,"items":[{"id":"hYB0mn5zh2c","updated":"2010-01-07T13:26:50.000Z","title":"Google Developers Day US - Maps API Introduction","description":"Google Maps API Introduction ...","tags":["GDD07","GDD07US","Maps"],"player":{"default":"http://www.youtube.com/watch?v=hYB0mn5zh2c"},...}]}

Here's one possible way to design the Java data classes for this (each class in its own Java file):

importcom.google.api.client.util.*;importjava.util.List;publicclassVideoFeed{@KeypublicintitemsPerPage;@KeypublicintstartIndex;@KeypublicinttotalItems;@KeypublicDateTimeupdated;@KeypublicList<Video>items;}publicclassVideo{@KeypublicStringid;@KeypublicStringtitle;@KeypublicDateTimeupdated;@KeypublicStringdescription;@KeypublicList<String>tags;@KeypublicPlayerplayer;}publicclassPlayer{// "default" is a Java keyword, so need to specify the JSON key manually@Key("default")publicStringdefaultUrl;}

You can also use the @com.google.api.client.util.Key annotation to defined query parameters for a URL. For example:

{@code public class YouTubeUrl extends GoogleUrl {

@Key public String author;

@Key("max-results") public Integer maxResults;

public YouTubeUrl(String encodedUrl) { super(encodedUrl); this.alt = "jsonc"; } }

To work with the YouTube API, you first need to set up the com.google.api.client.http.HttpTransport. For example:

{@code private static HttpTransport setUpTransport() throws IOException { HttpTransport result = new NetHttpTransport(); GoogleUtils.useMethodOverride(result); HttpHeaders headers = new HttpHeaders(); headers.setApplicationName("Google-YouTubeSample/1.0"); headers.gdataVersion = "2"; JsonCParser parser = new JsonCParser(); parser.jsonFactory = new GsonFactory(); transport.addParser(parser); // insert authentication code... return transport; } }

Now that we have a transport, we can execute a request to the YouTube API and parse the result:

{@code public static VideoFeed list(HttpTransport transport, YouTubeUrl url) throws IOException { HttpRequest request = transport.buildGetRequest(); request.url = url; return request.execute().parseAs(VideoFeed.class); } }

If the server responds with an error the com.google.api.client.http.HttpRequest#execute method will throw an com.google.api.client.http.HttpResponseException, which has an com.google.api.client.http.HttpResponse field which can be parsed the same way as a success response inside of a catch block. For example:

{@code try { ... } catch (HttpResponseException e) { if (e.response.getParser() != null) { Error error = e.response.parseAs(Error.class); // process error response } else { String errorContentString = e.response.parseAsString(); // process error response as string } throw e; } }

NOTE: As you might guess, the library uses reflection to populate the user-defined data model. It's not quite as fast as writing the wire format parsing code yourself can potentially be, but it's a lot easier.

NOTE: If you prefer to use your favorite JSON parsing library instead (there are many of them listed for example onjson.org), that's supported as well. Just callcom.google.api.client.http.HttpRequest#execute() and parse the returned byte stream.

@since 1.0

@author Yaniv Inbar

Media for Google API's.

Mutual TLS utilities for the Google API Client Library.

com.google.api.client.util.Beta
Support for notification channels to listen for changes to watched Google API resources.

com.google.api.client.util.Beta
JSON-based notification handling for notification channels.

com.google.api.client.util.Beta
Notification channel handling based on theGSON JSON library.

com.google.api.client.util.Beta
Notification channel handling based on theJackson 2 JSON library.

Contains the basis for the generated service-specific libraries.

Contains the basis for the generated service-specific libraries based on the JSON format.

com.google.api.client.util.Beta
Contains the basis for the generated service-specific libraries based on the Protobuf format.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.auth.oauth2 package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.compute package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.json package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.notifications package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.services package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.services.json package.

com.google.api.client.util.Beta
Test utilities for thecom.google.api.client.googleapis.protobuf package.

Utilities for the Google API Client Library.

com.google.api.client.util.Beta
Utilities for Google's Atom XML implementation (see detailed package specification).

Package Specification

User-defined Partial XML data models allow you to defined Plain Old Java Objects (POJO's) to define how the library should parse/serialize XML. Each field that should be included must have an @com.google.api.client.util.Key annotation. The field can be of any visibility (private, package private, protected, or public) and must not be static.

The optional value parameter of this @com.google.api.client.util.Key annotation specifies the XPath name to use to represent the field. For example, an XML attributea has an XPath name of@a, an XML element<a> has an XPath name of a, and an XML text content has an XPath name oftext(). These are named based on their usage with thepartial response/update syntax for Google API's. If the @com.google.api.client.util.Key annotation is missing, the default is to use the Atom XML namespace and the Java field's name as the local XML name. By default, the field name is used as the JSON key. Any unrecognized XML is normally simply ignored and not stored. If the ability to store unknown keys is important, usecom.google.api.client.xml.GenericXml.

Let's take a look at a typical partial Atom XML album feed from the Picasa Web Albums Data API:

<?xmlversion='1.0'encoding='utf-8'?><feedxmlns='http://www.w3.org/2005/Atom'xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'xmlns:gphoto='http://schemas.google.com/photos/2007'><linkrel='http://schemas.google.com/g/2005#post'type='application/atom+xml'href='http://picasaweb.google.com/data/feed/api/user/liz' /><author><name>Liz</name></author><openSearch:totalResults>1</openSearch:totalResults><entrygd:etag='"RXY8fjVSLyp7ImA9WxVVGE8KQAE."'><categoryscheme='http://schemas.google.com/g/2005#kind'term='http://schemas.google.com/photos/2007#album' /><title>lolcats</title><summary>HilariousFelines</summary><gphoto:access>public</gphoto:access></entry></feed>

Here's one possible way to design the Java data classes for this (each class in its own Java file):

importcom.google.api.client.util.*;importjava.util.List;publicclassLink{@Key("@href")publicStringhref;@Key("@rel")publicStringrel;publicstaticStringfind(List<Link>links,Stringrel){if(links!=null){for(Linklink:links){if(rel.equals(link.rel)){returnlink.href;}}}returnnull;}}publicclassCategory{@Key("@scheme")publicStringscheme;@Key("@term")publicStringterm;publicstaticCategorynewKind(Stringkind){Categorycategory=newCategory();category.scheme="http://schemas.google.com/g/2005#kind";category.term="http://schemas.google.com/photos/2007#"+kind;returncategory;}}publicclassAlbumEntry{@KeypublicStringsummary;@KeypublicStringtitle;@Key("gphoto:access")publicStringaccess;publicCategorycategory=newKind("album");privateStringgetEditLink(){returnLink.find(links,"edit");}}publicclassAuthor{@KeypublicStringname;}publicclassAlbumFeed{@KeypublicAuthorauthor;@Key("openSearch:totalResults")publicinttotalResults;@Key("entry")publicList<AlbumEntry>photos;@Key("link")publicList<Link>links;privateStringgetPostLink(){returnLink.find(links,"http://schemas.google.com/g/2005#post");}}

You can also use the @com.google.api.client.util.Key annotation to defined query parameters for a URL. For example:

publicclassPicasaUrlextendsGoogleUrl{@Key("max-results")publicIntegermaxResults;@KeypublicStringkinds;publicPicasaUrl(Stringurl){super(url);}publicstaticPicasaUrlfromRelativePath(StringrelativePath){PicasaUrlresult=newPicasaUrl(PicasaWebAlbums.ROOT_URL);result.path+=relativePath;returnresult;}}

To work with a Google API, you first need to set up thecom.google.api.client.http.HttpTransport. For example:

privatestaticHttpTransportsetUpTransport()throwsIOException{HttpTransportresult=newNetHttpTransport();GoogleUtils.useMethodOverride(result);HttpHeadersheaders=newHttpHeaders();headers.setApplicationName("Google-PicasaSample/1.0");headers.gdataVersion="2";AtomParserparser=newAtomParser();parser.namespaceDictionary=PicasaWebAlbumsAtom.NAMESPACE_DICTIONARY;transport.addParser(parser);// insert authentication code...returntransport;}

Now that we have a transport, we can execute a partial GET request to the Picasa Web Albums API and parse the result:

publicstaticAlbumFeedexecuteGet(HttpTransporttransport,PicasaUrlurl)throwsIOException{url.fields=GoogleAtom.getFieldsFor(AlbumFeed.class);url.kinds="photo";url.maxResults=5;HttpRequestrequest=transport.buildGetRequest();request.url=url;returnrequest.execute().parseAs(AlbumFeed.class);}

If the server responds with an error thecom.google.api.client.http.HttpRequest#execute method will throw ancom.google.api.client.http.HttpResponseException, which has ancom.google.api.client.http.HttpResponse field which can be parsed the same way as a success response inside of a catch block. For example:

try{...}catch(HttpResponseExceptione){if(e.response.getParser()!=null){Errorerror=e.response.parseAs(Error.class);// process error response}else{StringerrorContentString=e.response.parseAsString();// process error response as string}throwe;}

To update an album, we use the transport to execute an efficient partial update request using the PATCH method to the Picasa Web Albums API:

publicAlbumEntryexecutePatchRelativeToOriginal(HttpTransporttransport,AlbumEntryoriginal)throwsIOException{HttpRequestrequest=transport.buildPatchRequest();request.setUrl(getEditLink());request.headers.ifMatch=etag;AtomPatchRelativeToOriginalContentcontent=newAtomPatchRelativeToOriginalContent();content.namespaceDictionary=PicasaWebAlbumsAtom.NAMESPACE_DICTIONARY;content.originalEntry=original;content.patchedEntry=this;request.content=content;returnrequest.execute().parseAs(AlbumEntry.class);}privatestaticAlbumEntryupdateTitle(HttpTransporttransport,AlbumEntryalbum)throwsIOException{AlbumEntrypatched=album.clone();patched.title="An alternate title";returnpatched.executePatchRelativeToOriginal(transport,album);}

To insert an album, we use the transport to execute a POST request to the Picasa Web Albums API:

publicAlbumEntryinsertAlbum(HttpTransporttransport,AlbumEntryentry)throwsIOException{HttpRequestrequest=transport.buildPostRequest();request.setUrl(getPostLink());AtomContentcontent=newAtomContent();content.namespaceDictionary=PicasaWebAlbumsAtom.NAMESPACE_DICTIONARY;content.entry=entry;request.content=content;returnrequest.execute().parseAs(AlbumEntry.class);}

To delete an album, we use the transport to execute a DELETE request to the Picasa Web Albums API:

publicvoidexecuteDelete(HttpTransporttransport)throwsIOException{HttpRequestrequest=transport.buildDeleteRequest();request.setUrl(getEditLink());request.headers.ifMatch=etag;request.execute().ignore();}

NOTE: As you might guess, the library uses reflection to populate the user-defined data model. It's not quite as fast as writing the wire format parsing code yourself can potentially be, but it's a lot easier.

NOTE: If you prefer to use your favorite XML parsing library instead (there are many of them), that's supported as well. Just callcom.google.api.client.http.HttpRequest#execute() and parse the returned byte stream.