List and retrieve media items

  • This guide is not yet available, but resources are provided to understand its future content.

  • A sample application demonstrates how to list and retrieve media items using the checkMediaSourcesSet and fetch_media_item_list functions.

  • Reference documentation on media items is available for review.

Once a user has configured their ambient device and selected media sources in Google Photos, your application can list and retrieve those media items to display.

Before you start

  • Check device setup: Make sure you have successfully created and configured a device for the user.
  • Understand the Ambient API flow: Review the Ambient API Flow to understand the overall process, especially the step involving polling for mediaSourcesSet.

Poll for mediaSourcesSet

Before you can list media items for a device, the user must have selected the photos they want to share with your application within the Google Photos app. Your application must poll the device to determine when this selection has been made.

Periodically call the devices.get method for the specific deviceId. Monitor the mediaSourcesSet field in the AmbientDevice response. It will initially be false. Once the user has successfully selected media sources, this field will change to true.

The AmbientDevice response includes a pollingConfig with a pollInterval that you should use as a guideline for your polling frequency.

List Media Items

Once mediaSourcesSet is true for a device, you can begin fetching the media items selected by the user.

  1. Use the mediaItems.list endpoint: Make a GET request to https://photosambient.googleapis.com/v1/mediaItems, providing the deviceId in the path.

  2. Handle pagination (if necessary): The response may be paginated. Use the pageSize parameter to specify the maximum number of items to return, and the pageToken from a previous response to retrieve subsequent pages of results.

  3. Process the media items: The response will contain an array of AmbientMediaItem objects, each representing a selected media item. These objects include essential details like:

    • id: The unique identifier for the media item.
    • creationTime: The timestamp when the media item was created.
    • mediaFile: An object containing details to access the actual content.

The mediaFile field includes the baseUrl. This baseUrl is what you will use to construct URLs to access the media item's content at various resolutions or formats.

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 a mediaItem.

Image base URLs

Here is the list of options you can use with the image base URLs:

Parameter
w, h

Description

The width, w and height, h parameters.

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, c parameter.

If you want to crop the image to the exact width and height dimensions you have specified, concatenate the base URL with the optional -c parameter along with the mandatory w and h parameters.

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, d parameter.

If you want to download the image retaining all the Exif metadata except the location metadata, concatenate the base URL with the d parameter.

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 mediaItem, concatenate the baseUrl with the download video, dv parameter.

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 mediaMetadata.status field is READY. Otherwise, if your media item has not finished processing you may receive an error.

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, no parameter.

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 dv parameter as you would to download from video base URLs.
w, h, c, and d

Description

To retrieve the photo element of a motion photo media item, use the format for image base URLs.

Next Steps

  • Sample Application: Our sample application includes an example of listing and retrieving media items. Check out the checkMediaSourcesSet and fetch_media_item_list functions for more info.
  • Reference Documentation: Review the comprehensive reference docs on media items for detailed information on all available methods, request and response parameters, and error codes.