Once a user has selected media items using the Picker API, you can retrieve information about them and access their content. This guide outlines the process of listing and retrieving media items.
Before you start
- Understand the flow: Review get started with the Picker API for an overview of the entire photo selection process.
- Complete media item selection: Make sure the user has successfully selected media items from their session. Refer to the guide on sessions for more details.
- Review required authorization scopes: Working with sessions requires the
photospicker.mediaitems.readonly
scope. For more information on scopes, see Authorization scopes.
List picked media items
Use the
mediaItems.list
endpoint: Make a GET request to https://photospicker.googleapis.com/v1/mediaItems, providing thesessionId
as a query parameter.Handle pagination (if necessary):
If the user selects a large number of items, the response might be paginated. Use the
nextPageToken
in the response to retrieve subsequent pages of results.Process the media items: The response will contain an array of
PickedMediaItem
objects, each representing a selected media item. These objects include essential details like:id
: The unique identifier for the media item.baseUrl
: The base URL from which you can construct URLs to access the media item's content at various resolutions.mimeType
: The MIME type of the media item (e.g., image/jpeg, video/mp4).
Retrieve picked media items
Ensure you have a valid OAuth 2.0 access token with the
https://www.googleapis.com/auth/photospicker.mediaitems.readonly
scope to
authorize your requests.
Construct the content URL: Use the
baseUrl
from thePickedMediaItem
object. Append the resolution or file format to the baseUrl. See the section on base urls for more details.Fetch the content: Make a GET request to the media item's base URL. The response will contain the bytes of the media item (image or video). There are a number of different baseURL options available.
Base URLs
Base URLs in the Google Photos APIs provide access to the raw bytes of media items, enabling your app to download or display them. These URLs are included in responses when listing albums (Library API) or accessing media items (both Library and Picker APIs). Remember, base URLs require additional parameters to function correctly.
For the Picker API:
All PickedMediaItem.mediaFile
objects include a baseUrl
.
Base URLs remain active for 60 minutes, but can expire sooner if the user revokes your app's permissions through their Google Account settings.
For the Library API:
Base URLs remain active for 60 minutes.
The various base URLs are:
baseUrl
: Directly access photo, thumbnail for a video or download video bytes.coverPhotoBaseUrl
: Directly access the cover photo for the album.profilePictureBaseUrl
: Directly access the profile photo of the owner of amediaItem
.
Image base URLs
Here is the list of options you can use with the image base URLs:
Parameter | |
---|---|
w , h |
Description The width, To access an image media item, such as a photo or a thumbnail for a video, you must specify the dimensions that you plan to display in your application (so that the image can be scaled into these dimensions while preserving the aspect ratio). To do this, concatenate the base URL with your required dimensions as shown in the examples. Examples: base-url=wmax-width-hmax-height Here is an example to display a media item no wider than 2048 px and no taller than 1024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Description The crop, If you want to crop the image to the exact width and height
dimensions you have specified, concatenate the base URL with the
optional The size (in pixels) should be in the range [1, 16383]. If either the width or the height of the image, exceeds the requested size, the image is scaled down and cropped (maintaining the aspect ratio). Examples: base-url=wmax-width-hmax-height-c In this example, the application displays a media item that is exactly 256 px wide by 256 px high, such as a thumbnail: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Description The download, If you want to download the image retaining all the Exif metadata
except the location metadata, concatenate the base URL with the
Examples: base-url=d In this example, the application downloads an image with all metadata except the location metadata: https://lh3.googleusercontent.com/p/Az....XabC=d |
Video base URLs
Here is the list of options you can use with the video base URLs:
Parameter | |
---|---|
dv |
Description To access the bytes of a video The dv parameter requests a high quality, transcoded version of the original video. The parameter is not compatible with the w and h parameters. Base URLs for video downloads can take up to a few seconds to return bytes. Before using this parameter, check that the media items's
Examples: base-url=dv The following example shows you how to download the bytes of a video: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c , and
d |
Description To access the thumbnail of the video use any of the image base URL parameters. By default, all video thumbnails include an overlay of a playback button. See the -no parameter to remove this overlay. Examples: Refer to the image base URLs table for examples. |
no |
Description The remove thumbnail overlay, If you want to retrieve the thumbnail of a video without the overlay of a playback button, concatenate the base URL with the no parameter. The no parameter must be used with at least one of the image base URL parameters. Examples: base-url=wmax-width-hmax-height-no The following example displays a video thumbnail that is exactly 1280 px wide by 720 px high and does not include a playback button overlay: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Motion photo base URLs
Motion photos contain both photo and video elements. You can use parameters from
either image base URLs or video base
URLs for motion photo baseUrl
requests.
Parameter | |
---|---|
dv |
Description To retrieve the video element of a motion photo media item, use
the |
w , h , c , and
d |
Description To retrieve the photo element of a motion photo media item, use the format for image base URLs. |