Picker API Developer's Guide

Conventional, platform-specific applications often provide File Open dialogs. But for countless web applications, the only choice presented to users is a plain input control. Users must cut-and-paste a URL, typically from another web browser tab or window.

Google Picker aims to change this by providing users a more modern experience:

Familiar — The look-and-feel users will recognize from Google Drive and other Google properties.
Graphical — A dialog experience, with many views showing previews or thumbnails.
Streamlined — An inline, modal window, so users never leave the main application.

Web developers can incorporate Google Picker API by just adding a few lines of JavaScript.

Audience

This documentation is intended for developers who wish to add Google Picker API to their pages. A basic level of JavaScript fluency is required.

Read through this document to see code samples for common scenarios.

Consult the JSON Guide to understand the object format returned by the Google Picker API.

Refer to the Reference Guide for a complete API listing for the Google Picker API.

Application Requirements

Applications that use this interface must abide by all existing Terms of Service. Most importantly, you must correctly identify yourself in your requests.

Register your project

To get started using Google Picker API, you need to first use the setup tool, which guides you through creating a project in the Google API Console, enabling the API, and creating credentials.

If you haven't done so already, create your application's API key by clicking Create credentials > API key. Next, look for your API key in the API keys section.

If you haven't done so already, create your OAuth 2.0 credentials by clicking Create credentials > OAuth client ID. After you've created the credentials, you can see your client ID on the Credentials page. Click the client ID for details, such as client secret, redirect URIs, JavaScript origins address, and email address. Your application must send an OAuth 2.0 token when creating a Picker object with views that accesses private user data.

The "Hello World" Application

Create a Picker object using a PickerBuilder object. The Picker instance represents the Google Picker dialog, and is rendered on the page inside an IFRAME. Here's an example where a view with user's Photos is shown:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Picker Example</title>

    <script type="text/javascript">

      // The Browser API key obtained from the Google API Console.
      var developerKey = 'xxxxxxxYYYYYYYY-12345678';

      // The Client ID obtained from the Google API Console. Replace with your own Client ID.
      var clientId = '1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com';

      // Scope to use to access user's photos.
      var scope = 'https://www.googleapis.com/auth/photos';

      var pickerApiLoaded = false;
      var oauthToken;

      // Use the API Loader script to load google.picker and gapi.auth.
      function onApiLoad() {
        gapi.load('auth2', onAuthApiLoad);
        gapi.load('picker', onPickerApiLoad);
      }

      function onAuthApiLoad() {
        var authBtn = document.getElementById('auth');
        authBtn.disabled = false;
        authBtn.addEventListener('click', function() {
          gapi.auth2.init({ client_id: clientId }).then(function(googleAuth) {
            googleAuth.signIn({ scope: scope }).then(function(result) {
              handleAuthResult(result.getAuthResponse());
            })
          })
        });
      }

      function onPickerApiLoad() {
        pickerApiLoaded = true;
        createPicker();
      }

      function handleAuthResult(authResult) {
        if (authResult && !authResult.error) {
          oauthToken = authResult.access_token;
          createPicker();
        }
      }

      // Create and render a Picker object for picking from Google Photos.
      function createPicker() {
        if (pickerApiLoaded && oauthToken) {
          var picker = new google.picker.PickerBuilder().
              addView(google.picker.ViewId.PHOTOS).
              setOAuthToken(oauthToken).
              setDeveloperKey(developerKey).
              setCallback(pickerCallback).
              build();
          picker.setVisible(true);
        }
      }

      // A simple callback implementation.
      function pickerCallback(data) {
        var url = 'nothing';
        if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
          var doc = data[google.picker.Response.DOCUMENTS][0];
          url = doc[google.picker.Document.URL];
        }
        var message = 'You picked: ' + url;
        document.getElementById('result').innerHTML = message;
      }
    </script>
  </head>
  <body>
    <button type="button" id="auth" disabled>Authenticate</button>

    <div id="result"></div>

    <!-- The Google API Loader script. -->
    <script type="text/javascript" src="https://apis.google.com/js/api.js?onload=onApiLoad"></script>
  </body>
</html>

Note: If you intend to support older browsers such as Microsoft Internet Explorer 6, modify the example slightly as shown in the Supporting Older Browsers section.

Let's walk through the relevant sections. First the Google API Loader script is loaded. It is instructed to load the Google Picker JavaScript and the Authentication API when its loading has completed. A callback is provided to create the Google Picker dialog once the Google Picker API script is loaded and the authentication is complete.

    <script type="text/javascript">
      function onApiLoad() {
        // Use the API Loader script to load the Authentication script.
        gapi.load('auth', {'callback': onAuthApiLoad});

        // Use the API Loader script to load the google.picker script.
        gapi.load('picker', {'callback': onPickerApiLoad});
      }
    </script>
    <!-- Load the Google API Loader script. -->
    <script type="text/javascript" src="https://apis.google.com/js/api.js?onload=onApiLoad"></script>

A Picker renders one view at a time. Specify at least one view, either by ID (google.picker.ViewId.*) or by creating an instance of a type (google.picker.*View). Specifiy the view by type if you want additional control over how that view is rendered. If more than one view is added to the Picker, users switch from one view to another by clicking a tab on the left. Tabs can be logically grouped with ViewGroup objects.

In this simple application, a single view is specified by ID. A Browser API key should be obtained from Google API Console and passed to the PickerBuilder instance using the setDeveloperKey(developerKey) method. An OAuth 2.0 token is obtained using the Authentication API and passed to the PickerBuilder instance using the setOAuthToken(oauthToken) method. List of scopes needed to obtain the OAuth token for the corresponding Picker view is available here.

A method to call when the user selects an item (or cancels the dialog) is also specified. Once the Picker object is constructed, setVisible(true) is called so the user can see it.

    // Create and render a Picker object for picker user Photos.
    function createPicker() {
        var picker = new google.picker.PickerBuilder().
            addView(google.picker.ViewId.PHOTOS).
            setOAuthToken(oauthToken).
            setDeveloperKey(developerKey).
            setCallback(pickerCallback).
            build();
        picker.setVisible(true);
    }

The following code illustrates what you can do once the user selects Select or Cancel in the Google Picker dialog. The data object below is JSON-encoded. The google.picker.Response.ACTION field will always be set. If the user selects an item, the google.picker.Response.DOCUMENTS array is also populated. In this example the google.picker.Document.URL is shown on the main page. Find details about the data fields in the JSON Guide.

    // A simple callback implementation.
    function pickerCallback(data) {
      var url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        var doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      var message = 'You picked: ' + url;
      document.getElementById('result').innerHTML = message;
    }

Showing Different Views

Specify a view by ViewId, or by an instance of a subclass of google.picker.View. Standard views offered by Google Picker API are the following:

View Description	ViewId or Equivalent Class	OAuth Scope
All Google Drive items.	google.picker.ViewId.DOCS or google.picker.DocsView	https://www.googleapis.com/auth/drive.file
Google Drive photos.	google.picker.ViewId.DOCS_IMAGES	https://www.googleapis.com/auth/drive.file
Google Drive Documents.	google.picker.ViewId.DOCUMENTS	https://www.googleapis.com/auth/drive.file
Google Drive Presentations.	google.picker.ViewId.PRESENTATIONS	https://www.googleapis.com/auth/drive.file
Google Drive Spreadsheet.	google.picker.ViewId.SPREADSHEETS	https://www.googleapis.com/auth/drive.file
Google Drive Forms.	google.picker.ViewId.FORMS	https://www.googleapis.com/auth/drive.file
Google Drive photos and videos.	google.picker.ViewId.DOCS_IMAGES_AND_VIDEOS	https://www.googleapis.com/auth/drive.file
Google Drive videos.	google.picker.ViewId.DOCS_VIDEOS	https://www.googleapis.com/auth/drive.file
Google Drive Folders.	google.picker.ViewId.FOLDERS	https://www.googleapis.com/auth/drive.file
Adobe PDF files stored in Google Drive.	google.picker.ViewId.PDFS	https://www.googleapis.com/auth/drive.file
Upload documents to Google Drive.	google.picker.DocsUploadView	https://www.googleapis.com/auth/drive.file
Google Photos albums.	google.picker.ViewId.PHOTO_ALBUMS or google.picker.PhotoAlbumsView	https://www.googleapis.com/auth/photos
Photos from Google Photos.	google.picker.ViewId.PHOTOS or google.picker.PhotosView	https://www.googleapis.com/auth/photos
Upload to Google Photos.	google.picker.ViewId.PHOTO_UPLOAD	https://www.googleapis.com/auth/photos.upload
Google Image Search.	google.picker.ViewId.IMAGE_SEARCH or google.picker.ImageSearchView
Google Maps.	google.picker.ViewId.MAPS or google.picker.MapsView
Video Search.	google.picker.ViewId.VIDEO_SEARCH or google.picker.VideoSearchView
Webcam photos.	google.picker.ViewId.WEBCAM or google.picker.WebCamView	https://www.googleapis.com/auth/photos.upload
Your YouTube videos.	google.picker.ViewId.YOUTUBE	https://www.googleapis.com/auth/youtube
A collection of most recently selected items.	google.picker.ViewId.RECENTLY_PICKED	Use any of the above scopes.

The third column mentions the scope code that would be needed to obtain the OAuth 2.0 token for the view.

Note: The user must be logged in to create the picker with the https://www.googleapis.com/auth/drive.file scope.

Use a class instance instead of the ViewId when you need type-specific control. For example, use the PhotosView to show Google Photos.

    var picker = new google.picker.PickerBuilder().
        addView(new google.picker.PhotosView().
            setType(google.picker.PhotosView.Type.UPLOADED)).
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        build();

For a comprehensive list of methods and classes, see the Reference Guide.

Ordinarily, the set of views provided to the PickerBuilder are listed vertically in a single line in the left of the Google Picker window. You may, however, prefer some of your views to be grouped visually under a common heading. Use view groups to achieve this effect. Note that the common heading must also be a view. For example, you can create a view group of photos views, headed by the Google Photos album view, like the following:

    var picker = new google.picker.PickerBuilder().
        addViewGroup(
            new google.picker.ViewGroup(google.picker.ViewId.PHOTOS).
                addView(new google.picker.PhotosView().
                    setType(google.picker.PhotosView.Type.UPLOADED)).
        addView(google.picker.ViewId.RECENTLY_PICKED).
        setOAuthToken(oauthToken).
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        build();

Use view groups as a way of filtering out specific items. In the following example, the "Google Drive" sub-view shows only the documents and presentations, respectively, not other items.

    var picker = new google.picker.PickerBuilder().
        addViewGroup(
            new google.picker.ViewGroup(google.picker.ViewId.DOCS).
                addView(google.picker.ViewId.DOCUMENTS).
                addView(google.picker.ViewId.PRESENTATIONS)).
        setOAuthToken(oauthToken).
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        build();

Use PickerBuilder.enableFeature() to fine-tune the appearance of the Google Picker window. For instance, if you only have a single view, you may want to hide the navigation pane to give users more space to see items. Here's an example of a Google video search picker demonstrating this feature:

    var picker = new google.picker.PickerBuilder().
        addView(google.picker.ViewId.VIDEO_SEARCH).
        enableFeature(google.picker.Feature.NAV_HIDDEN).
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        build();

Use View.setQuery() to pre-populate search terms for views that include a web search. The following is a video search search example:

    picker = new google.picker.PickerBuilder().
        addView(new google.picker.View(google.picker.ViewId.VIDEO-SEARCH).
            setQuery('Hugging Cat')).
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        build();

Handling Google Drive Items

The picker interface can display a list of the currently authenticated user's Google Drive files. When a user selects a file from the list, the file ID is returned, and the ID may be used by an app to access the file.

The following picker example illustrates an image selector/uploader page that could be opened from an Open or Upload Drive files button in a web app. This example demonstrates how to set the AppId value, and incorporates some useful picker features such as enabling multi-select, hiding the navigation pane, and choosing the user account with the app's current OAuth 2.0 token:

drive/picker/helloworld.html

View on GitHub

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Google Picker Example</title>

    <script type="text/javascript">

    // The Browser API key obtained from the Google API Console.
    // Replace with your own Browser API key, or your own key.
    var developerKey = 'xxxxxxxYYYYYYYY-12345678';

    // The Client ID obtained from the Google API Console. Replace with your own Client ID.
    var clientId = "1234567890-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com"

    // Replace with your own project number from console.developers.google.com.
    // See "Project number" under "IAM & Admin" > "Settings"
    var appId = "1234567890";

    // Scope to use to access user's Drive items.
    var scope = ['https://www.googleapis.com/auth/drive.file'];

    var pickerApiLoaded = false;
    var oauthToken;

    // Use the Google API Loader script to load the google.picker script.
    function loadPicker() {
      gapi.load('auth', {'callback': onAuthApiLoad});
      gapi.load('picker', {'callback': onPickerApiLoad});
    }

    function onAuthApiLoad() {
      window.gapi.auth.authorize(
          {
            'client_id': clientId,
            'scope': scope,
            'immediate': false
          },
          handleAuthResult);
    }

    function onPickerApiLoad() {
      pickerApiLoaded = true;
      createPicker();
    }

    function handleAuthResult(authResult) {
      if (authResult && !authResult.error) {
        oauthToken = authResult.access_token;
        createPicker();
      }
    }

    // Create and render a Picker object for searching images.
    function createPicker() {
      if (pickerApiLoaded && oauthToken) {
        var view = new google.picker.View(google.picker.ViewId.DOCS);
        view.setMimeTypes("image/png,image/jpeg,image/jpg");
        var picker = new google.picker.PickerBuilder()
            .enableFeature(google.picker.Feature.NAV_HIDDEN)
            .enableFeature(google.picker.Feature.MULTISELECT_ENABLED)
            .setAppId(appId)
            .setOAuthToken(oauthToken)
            .addView(view)
            .addView(new google.picker.DocsUploadView())
            .setDeveloperKey(developerKey)
            .setCallback(pickerCallback)
            .build();
         picker.setVisible(true);
      }
    }

    // A simple callback implementation.
    function pickerCallback(data) {
      if (data.action == google.picker.Action.PICKED) {
        var fileId = data.docs[0].id;
        alert('The user selected: ' + fileId);
      }
    }
    </script>
  </head>
  <body>
    <div id="result"></div>

    <!-- The Google API Loader script. -->
    <script type="text/javascript" src="https://apis.google.com/js/api.js?onload=loadPicker"></script>
  </body>
</html>

The AppId and the client ID, used for authorizing access to a user's files, must be contained in the same app. Within the API Console, AppId can be identified as the "Project number" on the "IAM & Admin" > "Settings" page, in the developer console.

Important:The setOAuthToken function allows an app to use the current auth token to determine which Google account the picker uses to display the files. If a user is signed into multiple Google accounts, this allows the picker to display the files of the appropriate authorized account.

After obtaining the file ID from the picker when opening files, an application can then fetch the file metadata and download the file content as described in the reference documentation for files.get.

Rendering in Other Languages

Specify the UI language by providing the locale to the PickerBuilder instance using the setLocale(locale) method. The following is a French example:

    var picker = new google.picker.PickerBuilder().
        addView(google.picker.ViewId.IMAGE_SEARCH).
        setLocale('fr').
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        build();

The following is the list of locales currently supported:

af
am
ar
bg
bn
ca
cs da
de
el
en
en-GB
es
es-419 et
eu
fa
fi
fil
fr
fr-CA gl
gu
hi
hr
hu
id
is it
iw
ja
kn
ko
lt
lv ml
mr
ms
nl
no
pl
pt-BR pt-PT
ro
ru
sk
sl
sr
sv sw
ta
te
th
tr
uk
ur vi
zh-CN
zh-HK
zh-TW
zu

Supporting Older Browsers

If you intend to support users using older browsers, follow these one-time steps:

Download this file: https://www.google.com/ajax/picker/resources/rpc_relay.html.
Place the file somewhere in the same domain as you application.
Modify the Picker creation code, using the corrected path:

    var picker = new google.picker.PickerBuilder().
        addView(google.picker.ViewId.IMAGE_SEARCH).
        setDeveloperKey(developerKey).
        setCallback(pickerCallback).
        setRelayUrl('http://www.yoursite.com/somedir/rpc_relay.html').
        build();

Behind the scenes, the Google Picker API passes messages to your web page from a service hosted at Google. This is cross-domain communication, which is why special logic is necessary. On modern browsers, browser channels are used to relay the messages around. On older browsers, however, the security model requires us to bounce messages off of your server, in the same domain as your application.