google-api-java-client

Additional

Language
Java
Version
v1.29.3 (Jul 2, 2019)
Created
Oct 28, 2014
Updated
Aug 8, 2019
Owner
Google (google)
Contributors
gk5885
cushon
rmistry
aiuto
peleyal
anthmgoogle
wonderfly
ImJasonH
neshkeev
kevinthecheung
ejona86
eheilm
rbraunstein
wilford
dorireuv
lukecwik
sqrrrl
Galabar001
Show all (47)47
Activity
Badge
Generate
Download
Source code

Promotion

Google APIs Client Library for Java

Library Maintenance

These client libraries are officially supported by Google. However, these libraries are considered complete and are in maintenance mode. This means that we will address critical bugs and security issues, but will not add any new features. If you're working with Google Cloud Platform APIs such as Datastore, Pub/Sub and many others, consider using the Cloud Client Libraries for Java instead. These are the new and idiomatic Java libraries targeted specifically at Google Cloud Platform Services.

Building locally

One time setup
mkdir /tmp/foo && cd /tmp/foo
wget https://dl.google.com/dl/android/maven2/com/google/android/gms/play-services-basement/8.3.0/play-services-basement-8.3.0.aar
unzip play-services-basement-8.3.0.aar
mvn install:install-file \
  -Dfile=classes.jar \
  -DgroupId=com.google.android.google-play-services \
  -DartifactId=google-play-services \
  -Dversion=1 \
  -Dpackaging=jar
cd -

# we need the google-http-java-client jar cached locally
git clone https://github.com/google/google-http-java-client.git
cd google-http-java-client && mvn compile && mvn install && cd ..

# we need the google-oauth-java-client jar cached locally
git clone https://github.com/google/google-oauth-java-client.git
cd google-oauth-java-client && mvn compile && mvn install
Building And Testing
mvn install

Overview

The Google APIs Client Library for Java is a flexible, efficient, and powerful Java client library for accessing any HTTP-based API on the web, not just Google APIs.

The library has the following features:

Accessing Google APIs

To use Google's Java client libraries to call any Google API, you need two libraries:

  • The core Google APIs Client Library for Java (google-api-java-client), which is the generic runtime library described here. This library provides functionality common to all APIs, for example HTTP transport, error handling, authentication, JSON parsing, media download/upload, and batching.
  • An auto-generated Java library for the API you are accessing, for example the generated Java library for the BigQuery API. These generated libraries include API-specific information such as the root URL, and classes that represent entities in the context of the API. These classes are useful for making conversions between JSON objects and Java objects.

To find the generated library for a Google API, visit Google APIs Client Library for Java. The API-specific Java packages include both the core google-api-java-client and the client-specific libraries.

If you are using the old GData library, you need to migrate.

Developing for Android

If you are developing for Android and the Google API you want to use is included in the Google Play Services library, use that library for the best performance and experience.

To access other Google APIs, use the Google APIs Client Library for Java, which supports Android 4.0 (Ice Cream Sandwich) (or higher).

Other Java environments

Highlighted Features

Simple to call Google APIs

You can call Google APIs using Google service-specific generated libraries with the Google APIs Client Library for Java. Here's an example that makes a call to the Google Calendar API:

// Show events on user's calendar.
View.header("Show Calendars");
CalendarList feed = client.calendarList().list().execute();
View.display(feed);

Authentication

The authentication library can reduce the amount of code needed to handle OAuth 2.0, and sometimes a few lines is all you need. For example:

/** Authorizes the installed application to access user's protected data. */
private static Credential authorize() throws Exception {
  // load client secrets
  GoogleClientSecrets clientSecrets = GoogleClientSecrets.load(JSON_FACTORY,
      new InputStreamReader(CalendarSample.class.getResourceAsStream("/client_secrets.json")));
  // set up authorization code flow
  GoogleAuthorizationCodeFlow flow = new GoogleAuthorizationCodeFlow.Builder(
      httpTransport, JSON_FACTORY, clientSecrets,
      Collections.singleton(CalendarScopes.CALENDAR)).setDataStoreFactory(dataStoreFactory)
      .build();
  // authorize
  return new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user");
}

Batching

Each HTTP connection that your client makes results in overhead. To reduce overhead, you can batch multiple API calls together into a single HTTP request.

The main classes of interest are BatchRequest and JsonBatchCallback. The following example shows how to use these classes with service-specific generated libraries:

JsonBatchCallback<Calendar> callback = new JsonBatchCallback<Calendar>() {

  public void onSuccess(Calendar calendar, HttpHeaders responseHeaders) {
    printCalendar(calendar);
    addedCalendarsUsingBatch.add(calendar);
  }

  public void onFailure(GoogleJsonError e, HttpHeaders responseHeaders) {
    System.out.println("Error Message: " + e.getMessage());
  }
};

...

Calendar client = Calendar.builder(transport, jsonFactory, credential)
  .setApplicationName("BatchExample/1.0").build();
BatchRequest batch = client.batch();

Calendar entry1 = new Calendar().setSummary("Calendar for Testing 1");
client.calendars().insert(entry1).queue(batch, callback);

Calendar entry2 = new Calendar().setSummary("Calendar for Testing 2");
client.calendars().insert(entry2).queue(batch, callback);

batch.execute();

Media upload

Resumable media upload

When you upload a large media file to a server, use resumable media upload to send the file chunk by chunk. The Google API generated libraries contain convenience methods for interacting with resumable media upload, which was introduced in the 1.7.0-beta version of the Google API Client Library for Java.

The resumable media upload protocol is similar to the resumable media upload protocol described in the Google Drive API documentation.

Protocol design

The following sequence diagram shows how the resumable media upload protocol works:

Implementation details

The main classes of interest are MediaHttpUploader and MediaHttpProgressListener.

If methods in the service-specific generated libraries contain the mediaUpload parameter in the Discovery document, then a convenience method is created for these methods that takes an InputStreamContent as a parameter. (For more about using media upload with the Google APIs Discovery Service, see Media upload.)

For example, the insert method of the Drive API supports mediaUpload, and you can use the following code to upload a file:

class CustomProgressListener implements MediaHttpUploaderProgressListener {
  public void progressChanged(MediaHttpUploader uploader) throws IOException {
    switch (uploader.getUploadState()) {
      case INITIATION_STARTED:
        System.out.println("Initiation has started!");
        break;
      case INITIATION_COMPLETE:
        System.out.println("Initiation is complete!");
        break;
      case MEDIA_IN_PROGRESS:
        System.out.println(uploader.getProgress());
        break;
      case MEDIA_COMPLETE:
        System.out.println("Upload is complete!");
    }
  }
}

File mediaFile = new File("/tmp/driveFile.jpg");
InputStreamContent mediaContent =
    new InputStreamContent("image/jpeg",
        new BufferedInputStream(new FileInputStream(mediaFile)));
mediaContent.setLength(mediaFile.length());

Drive.Files.Insert request = drive.files().insert(fileMetadata, mediaContent);
request.getMediaHttpUploader().setProgressListener(new CustomProgressListener());
request.execute();

You can also use the resumable media upload feature without the service-specific generated libraries. Here is an example:

File mediaFile = new File("/tmp/Test.jpg");
InputStreamContent mediaContent =
    new InputStreamContent("image/jpeg",
        new BufferedInputStream(new FileInputStream(mediaFile)));
mediaContent.setLength(mediaFile.length());


MediaHttpUploader uploader = new MediaHttpUploader(mediaContent, transport, httpRequestInitializer);
uploader.setProgressListener(new CustomProgressListener());
HttpResponse response = uploader.upload(requestUrl);
if (!response.isSuccessStatusCode()) {
  throw GoogleJsonResponseException(jsonFactory, response);
}

Direct media upload

Resumable media upload is enabled by default, but you can disable it and use direct media upload instead, for example if you are uploading a small file. Direct media upload was introduced in the 1.9.0-beta version of the Google API Client Library for Java.

Direct media upload uploads the whole file in one HTTP request, as opposed to the resumable media upload protocol, which uploads the file in multiple requests. Doing a direct upload reduces the number of HTTP requests but increases the chance of failures (such as connection failures) that can happen with large uploads.

The usage for direct media upload is the same as what is described above for resumable media upload, plus the following call that tells MediaHttpUploader to only do direct uploads:

mediaHttpUploader.setDirectUploadEnabled(true);

Media download

Resumable media downloads

When you download a large media file from a server, use resumable media download to download the file chunk by chunk. The Google API generated libraries contain convenience methods for interacting with resumable media download, which was introduced in the 1.9.0-beta version of the Google API Client Library for Java.

The resumable media download protocol is similar to the resumable media upload protocol, which is described in the Google Drive API documentation.

Implementation details

The main classes of interest are MediaHttpDownloader and MediaHttpDownloaderProgressListener. Media content is downloaded in chunks, and chunk size is configurable. If a server error is encountered in a request, then the request is retried.

If methods in the service-specific generated libraries support download in the Discovery document, then a convenient download method is created for these methods that takes in an OutputStream. (For more about using media download with the Google APIs Discovery Service, see Media download.)

For example:

class CustomProgressListener implements MediaHttpDownloaderProgressListener {
  public void progressChanged(MediaHttpDownloader downloader) {
    switch (downloader.getDownloadState()) {
      case MEDIA_IN_PROGRESS:
        System.out.println(downloader.getProgress());
        break;
      case MEDIA_COMPLETE:
        System.out.println("Download is complete!");
    }
  }
}

OutputStream out = new FileOutputStream("/tmp/driveFile.jpg");

DriveFiles.Get request = drive.files().get(fileId);
request.getMediaHttpDownloader().setProgressListener(new CustomProgressListener());
request.executeMediaAndDownloadTo(out);

You can also use this feature without service-specific generated libraries. Here is an example:

OutputStream out = new FileOutputStream("/tmp/Test.jpg");

MediaHttpDownloader downloader = new MediaHttpDownloader(transport, httpRequestInitializer);
downloader.setProgressListener(new CustomProgressListener());
downloader.download(requestUrl, out);

Direct media download

Resumable media download is enabled by default, but you can disable it and use direct media download instead, for example if you are downloading a small file. Direct media download was introduced in the 1.9.0-beta version of the Google API Client Library for Java.

Direct media download downloads the whole media content in one HTTP request, as opposed to the resumable media download protocol, which can download in multiple requests. Doing a direct download reduces the number of HTTP requests but increases the chance of failures (such as connection failures) that can happen with large downloads.

The usage is the same as what is described above, plus the following call that tells MediaHttpDownloader to do direct downloads:

mediaHttpDownloader.setDirectDownloadEnabled(true);

Running on Google App Engine

App Engine-specific helpers make quick work of authenticated calls to APIs, and you do not need to worry about exchanging code for tokens. For example:

@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
  AppIdentityCredential credential =
      new AppIdentityCredential(Arrays.asList(UrlshortenerScopes.URLSHORTENER));
  Urlshortener shortener =
      new Urlshortener.Builder(new UrlFetchTransport(), new JacksonFactory(), credential)
      .build();
  UrlHistory history = shortener.URL().list().execute();
  ...
}

Running on Android (@Beta)

If you are developing for Android and the Google API you want to use is included in the Google Play Services library, use that library for the best performance and experience.

To access other Google APIs, use the Google Client Library for Java's Android-specific helper classes, which are well-integrated with Android AccountManager. For example:

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // Google Accounts
  credential =
      GoogleAccountCredential.usingOAuth2(this, Collections.singleton(TasksScopes.TASKS));
  SharedPreferences settings = getPreferences(Context.MODE_PRIVATE);
  credential.setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null));
  // Tasks client
  service =
      new com.google.api.services.tasks.Tasks.Builder(httpTransport, jsonFactory, credential)
          .setApplicationName("Google-TasksAndroidSample/1.0").build();
}

Installation

The Google APIs Client Library for Java is easy to install, and you can download the binary directly from the Downloads page, or you can use Maven or Gradle.

To use Maven, add the following lines to your pom.xml file:

<project>
  <dependencies>
    <dependency>
      <groupId>com.google.api-client</groupId>
      <artifactId>google-api-client</artifactId>
      <version>1.30.2</version>
    </dependency>
  </dependencies>
</project>

To use Gradle, add the following lines to your build.gradle file:

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.google.api-client:google-api-client:1.30.2'
}

CI Status

Java Version Status
Java 7
Java 8
Java 11

Dependencies

This library is built on top of two common libraries, also built by Google, and also designed to work with any HTTP service on the web:

Important Warnings

@Beta

Features marked with the @Beta annotation at the class or method level are subject to change. They might be modified in any way, or even removed, in any major release. You should not use beta features if your code is a library itself (that is, if your code is used on the CLASSPATH of users outside your own control).

Deprecations

Deprecated non-beta features will be removed eighteen months after the release in which they are first deprecated. You must fix your usages before this time. If you don't, any type of breakage might result, and you are not guaranteed a compilation error.

Documentation

Links

For questions or concerns, please file an issue in the GitHub repository.