# Access app-created media items

After making calls to [list the contents of a photo library or
album](https://developers.google.com/photos/library/guides/list), instead of storing the returned media
items, your application should store the IDs of the media items. This is because
the content of the media items may change and after a certain time, the URLs
included in the response expire. The media item ID uniquely identifies a media
item, such as a photo or a video inside a user's library.

## Required authorization scopes

Accessing app-created media items requires the
`photoslibrary.readonly.appcreateddata` scope. For more information on scopes,
see [Authorization scopes](https://developers.google.com/photos/overview/authorization).

## Media items

A [`mediaItem`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems#resource-mediaitem)
is a representation of media such as a photo or a video that's been uploaded to
the Google Photos library. It is a top-level object and its properties can
differ based on the underlying media type.

The following table lists the `mediaItem` properties:

| Properties ||
|---|---|
| `id` | A permanent, stable ID used to identify the object. |
| `description` | Description of the media item as seen inside Google Photos. |
| `baseUrl` | Used to access the raw bytes. For more information, see [Base URLs](https://developers.google.com/photos/library/guides/access-media-items#base-urls). |
| `productUrl` | A link to the image inside Google Photos. This link can't be opened by the developer, only by the user. URLs point to a media item in the library. If the URL was retrieved from an [album search](https://developers.google.com/photos/library/guides/list#listing-album-contents), it points to the item within the album. |
| `mimeType` | The type of the media item to help easily identify the type of media (for example: `image/jpg`). |
| `filename` | The filename of the media item shown to the user in the Google Photos app (within the item's info section). |
| `mediaMetadata` | Varies depending on the underlying type of the media, such as, [`photo`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems#Photo) or [`video`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems#Video). To reduce the payload, field masks can be used. |

### Get a media item

To retrieve a media item, call
[mediaItems.get](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/get) using the
`mediaItemId`. The request returns a single media item.

The `mediaItem` contains properties, such as the ID, description, and URL. The
additional information within `photo` or `video` is based on the metadata within
the file. Not all properties may be present.

If the media item is a video, the video file must be processed first. The
`mediaItem` contains a `status` field inside `mediaMetadata` which describes the
processing state of the video file. A newly uploaded file returns the
[`videoProcessingStatus`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems#VideoProcessingStatus)
with the value `PROCESSING` first, before it is `READY` for use. The `baseUrl`
of a video media item isn't available until the video has been processed.

### REST

Here is a GET request:

```
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token
```

The response for a photo media item looks like this. The photo
property contains metadata for photo items.

```restructuredtext
{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}
```

The response for a video media item looks like this. The video
property contains metadata for video items.

```restructuredtext
{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}
```

### Get multiple media items

To retrieve multiple media items by their identifiers, call
[`mediaItems.batchGet`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/batchGet)
using the `mediaItemId`s.

The request returns a list of
[`MediaItemResults`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/batchGet#MediaItemResult)
in the order of the media items identifiers supplied in the request. Each result
contains a [`MediaItem`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems#MediaItem)
or a [`Status`](https://developers.google.com/photos/library/reference/rest/v1/Status) if there was an error.

The maximum number of media items you can request in one call is 50. The list of
media items must not contain duplicate identifiers and cannot be empty.

### REST

Here is a GET request that shows successful and unsuccessful access of
media items. Specify each media item identifier as a new
`mediaItemIds` query parameter as part of the request:

```
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token
```

The GET request returns the following response:

```restructuredtext
{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}
```

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