What is Google Picker?
Google Picker is a “File Open” dialog for the information stored in Google servers.
With Google Picker, your users can select photos, videos, maps, and documents stored in Google servers. The selection is passed back to your web page or web application for further use.
Use Google Picker to let users:
- Access their files stored across Google services.
- Upload new files to Google, which they can use in your application.
- Select any image or video from the Internet, which they can use in your application.
To start using Google Picker, please read the Developer’s Guide!
Google 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.
Table of Contents
- Audience
- Application Requirements
- The “Hello World” Application
- Showing Different Views
- Handling Google Drive Items
- Rendering in Other Languages
- Supporting Older Browsers
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.
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 Google Image Search view 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>
<!-- The standard Google Loader script. -->
<script src="http://www.google.com/jsapi"></script>
<script type="text/javascript">
// Use the Google Loader script to load the google.picker script.
google.setOnLoadCallback(createPicker);
google.load('picker', '1');
// Create and render a Picker object for searching images.
function createPicker() {
var picker = new google.picker.PickerBuilder().
addView(google.picker.ViewId.IMAGE_SEARCH).
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>
<div id="result"></div>
</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 common Google Loader is invoked to load the Google Picker JavaScript. Here the loader is also instructed which method to call when the loading completes. The second argument to google.load() is the version, and for Google Picker this value must be ‘1’.
// Use the Google Loader script to load the google.picker script.
google.setOnLoadCallback(createPicker);
google.load('picker', '1');
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 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 searching images.
function createPicker() {
var picker = new google.picker.PickerBuilder().
addView(google.picker.ViewId.IMAGE_SEARCH).
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:
| Name | Description | Equivalent Class |
|---|---|---|
| google.picker.ViewId.DOCS | All Google Drive items. | google.picker.DocsView |
| google.picker.ViewId.DOCS_IMAGES | Google Drive photos. | |
| google.picker.ViewId.DOCS_IMAGES_AND_VIDEOS | Google Drive photos and videos. | |
| google.picker.ViewId.DOCS_VIDEOS | Google Drive videos. | |
| google.picker.ViewId.DOCUMENTS | Google Drive Documents. | |
| google.picker.ViewId.FOLDERS | Google Drive Folders. | |
| google.picker.ViewId.FORMS | Google Drive Forms. | |
| google.picker.ViewId.IMAGE_SEARCH | Google Image Search. | google.picker.ImageSearchView |
| google.picker.ViewId.MAPS | Google Maps. | google.picker.MapsView |
| google.picker.ViewId.PDFS | Adobe PDF files stored in Google Drive. | |
| google.picker.ViewId.PHOTO_ALBUMS | Picasa Web Albums photo albums. | google.picker.PhotoAlbumsView |
| google.picker.ViewId.PHOTO_UPLOAD | Upload to Picasa Web Albums. | |
| google.picker.ViewId.PHOTOS | Picasa Web Albums photos. | google.picker.PhotosView |
| google.picker.ViewId.PRESENTATIONS | Google Drive Presentations. | |
| google.picker.ViewId.RECENTLY_PICKED | A collection of most recently selected items. | |
| google.picker.ViewId.SPREADSHEETS | Google Drive Spreadsheet. | |
| google.picker.ViewId.VIDEO_SEARCH | Video Search. | google.picker.VideoSearchView |
| google.picker.ViewId.WEBCAM | Webcam photos and videos. | google.picker.WebCamView |
| google.picker.ViewId.YOUTUBE | Your YouTube videos. |
The third column shows the class equivalent for the ViewId, if available. Use a class instance instead of the ViewId when you need type-specific control. For example, use the PhotosView to show Picasa Web Album’s Featured Photos gallery.
var picker = new google.picker.PickerBuilder(). addView(new google.picker.PhotosView(). setType(google.picker.PhotosView.Type.FEATURED)). 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 Picasa Web Albums 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(new google.picker.PhotosView(). setType(google.picker.PhotosView.Type.FEATURED))). addView(google.picker.ViewId.RECENTLY_PICKED). 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)). 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). 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')).
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:
<!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>
<!-- The standard Google Loader script; use your own key. -->
<script src="http://www.google.com/jsapi?key=AIzaSyBV6MeANy_ZaLB2f2c-XKCMA7hIu2Fy744"></script>
<script type="text/javascript">
// Use the Google Loader script to load the google.picker script.
google.setOnLoadCallback(createPicker);
google.load('picker', '1');
// Create and render a Picker object for searching images.
function createPicker() {
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(YOUR_APP_ID)
.setOAuthToken(AUTH_TOKEN) //Optional: The auth token used in the current Drive API session.
.addView(view)
.addView(new google.picker.DocsUploadView())
.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>
</body>
</html>
The AppId set here and the client ID used for authorizing access to a user’s files must be contained in the same app. These values are shown in the APIs console for a registered app.
Important:The optional 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. In cases where no auth token is available, apps can use the setAuthUser function to specify which Google account the picker uses.
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 an optional third argument when you call google.load(). The following is a French example:
google.load('picker', '1', {'language':'fr'});
The following is the list of locales currently supported:
afamarbgbncacs |
dadeelenen-GBeses-419 |
eteufafifilfrfr-CA |
glguhihrhuidis |
itiwjaknkoltlv |
mlmrmsnlnoplpt-BR |
pt-PTroruskslsrsv |
swtatethtrukur |
vizh-CNzh-HKzh-TWzu |
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
Pickercreation code, using the corrected path:
var picker = new google.picker.PickerBuilder().
addView(google.picker.ViewId.IMAGE_SEARCH).
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.
JSON Guide
When a user selects one or more items, the Google Picker API returns a JSON-formatted object in the callback. Depending on the view from which the selection was made, different fields are present in this data object.
{
Response.ACTION: action,
Response.VIEW: [
view_id,
undefined,
view_options {
query: user_query,
parent: parent_ID,
...
}
],
Response.DOCUMENTS: [
{
Document.ADDRESS_LINES: [
address_line,
...
],
Document.AUDIENCE: audience,
Document.DESCRIPTION: description,
Document.DURATION: duration,
Document.EMBEDDABLE_URL: embed_URL,
Document.ICON_URL: icon_URL,
Document.ID: item_id,
Document.IS_NEW: is_new,
Document.LAST_EDITED_UTC: timestamp,
Document.LATITUDE: latitude_value,
Document.LONGITUDE: longitude_value,
Document.MIME_TYPE: MIME_type,
Document.NAME: item_name,
Document.PARENT_ID: parent_ID,
Document.PHONE_NUMBERS:
{
type: phone_type,
number: phone_number,
}
...
],
Document.SERVICE_ID: service_id,
Document.THUMBNAILS: [
{
Thumbnail.URL: thumbnail_URL,
Thumbnail.WIDTH: thumbnail_width,
Thumbnail.HEIGHT: thumbnail_height
}
...
],
Document.TYPE: type,
Document.URL: item_URL
},
...
]
Response.PARENTS: [
{
Document.AUDIENCE: audience,
Document.DESCRIPTION: description,
Document.LAST_EDITED_UTC: timestamp,
Document.MIME_TYPE: MIME_type,
Document.NAME: item_name,
Document.ICON_URL: icon_URL,
Document.ID: item_ID,
Document.IS_NEW: is_new,
Document.SERVICE_ID: service_id,
Document.THUMBNAILS: [
{
Thumbnail.URL: thumbnail_URL,
Thumbnail.WIDTH: thumbnail_width,
Thumbnail.HEIGHT: thumbnail_height
}
...
],
Document.TYPE: type,
Document.URL: item_URL,
},
...
}
}
|
|
| action | The Action taken by the user to close the picker dialog. |
| address_line | The address of a picked location. |
| audience | The Audience of a Picasa Web Albums photo album. |
| description | A description of the item, if provided. |
| duration | The duration of a picked video. |
| embed_URL | A URL for an embeddable version of the item. |
| icon_URL | A URL for a publicly accessible version for an icon, if available. |
| is_new | True if the picked item was uploaded then immediately picked. |
| item_URL | A URL linking directly to the item. |
| item_id | ID of the picked item. |
| item_name | Name of the picked item. |
| latitude_value | Latitude of a picked location (or of where the photo was taken if it has geo data), in degrees. |
| longitude_value | Longitude of a picked location (or of where the photo was taken if it has geo data), in degrees. |
| MIME_type | The MIME type of the picked item (not valid for maps). |
| parent_ID | ID of parent item, if applicable. |
| phone_number | The phone number of a picked location. |
| phone_type | The type of phone number for a picked location. |
| service_id | A ServiceId that describes the service this file was picked from. |
| thumbnail_height | The height of the publicly accessible thumbnail. |
| thumbnail_URL | A URL for the publicly accessible thumbnail. |
| thumbnail_width | The width of the publicly accessible thumbnail. |
| timestamp | The number of milliseconds since January 1, 1970, 00:00:00 GMT. |
| type | The Type of the picked item. |
| user_query | Query string, if one was set in View.setQuery(). |
| view_ID | The ViewId of the View the item was picked from. |
| view_options | Additional information, if known. Otherwise undefined. |