# List and retrieve media items

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](https://developers.google.com/photos/ambient/guides/devices) for the user.
- **Understand the Ambient API flow:** Review the [Ambient API Flow](https://developers.google.com/photos/ambient/guides/get-started-ambient#ambient-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`](https://developers.google.com/photos/ambient/reference/rest/v1/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`](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list),
   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`](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems#AmbientMediaItem%22)
   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`](https://developers.google.com/photos/picker/reference/rest/v1/mediaItems)
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.

> [!NOTE]
> **Note:** Requests to a `PickedMediaItem.mediaFile` baseUrl must include an Authorization header with a valid OAuth 2.0 bearer token.

**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`.

> [!WARNING]
> **Warning:** If you use the base URL you must specify a download parameter, or both the maximum width and the maximum height.

### 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](https://developers.google.com/photos/ambient/guides/media-items#get-media-item) 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](https://developers.google.com/photos/ambient/guides/media-items#image-base-urls). 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](https://developers.google.com/photos/ambient/guides/media-items#image-base-urls) 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](https://developers.google.com/photos/ambient/guides/media-items#image-base-urls). **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](https://developers.google.com/photos/ambient/guides/media-items#image-base-urls) or [video base
URLs](https://developers.google.com/photos/ambient/guides/media-items#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](https://developers.google.com/photos/ambient/guides/media-items#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](https://developers.google.com/photos/ambient/guides/media-items#image-base-urls). |

## Content Policy and Filtering

Google Photos applies standard content filtering by default for images and
videos displayed on a shared device such as a TV or digital display. This filter
is designed to optimize the viewing experience by excluding content such as:

- Functional images (e.g., screenshots, documents, receipts).
- Images that may render poorly on a large screen (e.g., very low resolution, blur, excessive grain).
- Content identified as highly personal or sensitive, which may not be intended for general display in a shared setting.

All content filtering is automated. To give users more control over the
content displayed, you can allow them to manually select and update the media
sources used for the ambient display.

## Next Steps

- **Sample Application:** Our [sample application](https://developers.google.com/photos/ambient/samples) 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](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems) for detailed information on all available methods, request and response parameters, and error codes.