Access media items

After making calls to list the contents of a photo library or album, 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.

Note that your application shouldn't cache a user's photo or video for long periods of time, but depending on your use case, you may store or cache the media item ID for as long as necessary. You should also note that access to user data is governed by privacy obligations.

Required authorization scopes

To access media items, your app must request at least one of the following authorization scopes. Access to the media items returned in the response depends on the scopes you have requested.

photoslibrary.readonly allows access to all media items in the user's library
photoslibrary.readonly.appcreateddata allows access only to media items that were created by the app

Media items

A 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.
`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, 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` or `video`. To reduce the payload, field masks can be used.
`contributorInfo`	This field is only populated if the media item is in a shared album created by this app and the user has granted the `photoslibrary.sharing` scope. Contains information about the contributor who added this media item. For more details, see Share media.

Get a media item

To retrieve a media item, call 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. ContributorInfo contains metadata for items that are part of a shared album. This field is only included when listing the contents of a shared album where the user has granted the photoslibrary.sharing authorization scope.

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

{
  "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.

{
  "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"
  }
}

Java

The photo property contains metadata for photo items.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...
    if (metadata.hasPhoto()) {
      // This media item is a photo and has additional photo metadata
      Photo photoMetadata = metadata.getPhoto();
      String cameraMake = photoMetadata.getCameraMake();
      String cameraModel = photoMetadata.getCameraModel();
      float aperture = photoMetadata.getApertureFNumber();
      int isoEquivalent = photoMetadata.getIsoEquivalent();
      // ...
    }
  }
  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

The video property contains metadata for video items.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...

    if (metadata.hasVideo()) {
      // This media item is a video and has additional video metadata
      Video videoMetadata = metadata.getVideo();
      VideoProcessingStatus status = videoMetadata.getStatus();
      if (status.equals(VideoProcessingStatus.READY)) {
        // This video media item has been processed
        String cameraMake = videoMetadata.getCameraMake();
        String cameraModel = videoMetadata.getCameraModel();
        double fps = videoMetadata.getFps();
        // ...
      }
    }
  }

  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

The photo property contains metadata for photo items.

try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $photoMetadata = $metadata->getPhoto();
        if (!is_null($photoMetadata)) {
            // This media item is a photo and has additional photo metadata
            $cameraMake = $photoMetadata->getCameraMake();
            $cameraModel = $photoMetadata->getCameraModel();
            $aperture = $photoMetadata->getApertureFNumber();
            $isoEquivalent = $photoMetadata->getIsoEquivalent();
            // ...
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

The video property contains metadata for video items.

  try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $videoMetadata = $metadata->getVideo();
        if (!is_null($videoMetadata)) {
            // This media item is a video and has additional video metadata
            if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
            // This video media item has been processed
                $cameraMake = $videoMetadata->getCameraMake();
                $cameraModel = $videoMetadata->getCameraModel();
                $fps = $videoMetadata->getFps();
                // ...
            }
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Get multiple media items

To retrieve multiple media items by their identifiers, call mediaItems.batchGet using the mediaItemIds.

The request returns a list of MediaItemResults in the order of the media items identifiers supplied in the request. Each result contains a MediaItem or a 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:

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

Java

try {
  // List of media item IDs to retrieve
  List<String> mediaItemIds = Arrays
      .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");

  // Get a list of media items using their IDs
  BatchGetMediaItemsResponse response = photosLibraryClient
      .batchGetMediaItems(mediaItemIds);

  // Loop over each result
  for (MediaItemResult result : response.getMediaItemResultsList()) {

    // Each MediaItemresult contains a status and a media item
    if (result.hasMediaItem()) {
      // The media item was successfully retrieved, get some properties
      MediaItem item = result.getMediaItem();
      String id = item.getId();
      // ...
    } else {
      // If the media item is not set, an error occurred and the item could not be loaded
      // Check the status and handle the error
      Status status = result.getStatus();
      // ...
    }

  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {

    // List of media item IDs to retrieve
    $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];

    // Get a list of media items using their IDs
    $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);

    // Loop over each result
    foreach ($response->getMediaItemResults() as $itemResult) {

        // Each MediaItemresult contains a status and a media item
        $mediaItem = $itemResult->getMediaItem();

        if(!is_null($mediaItem)){
            // The media item was successfully retrieved, get some properties
            $id = $mediaItem->getId();
            // ...
        } else {
            // If the media item is null, an error occurred and the item could not be loaded
        }
    }

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Base URLs

Base URLs within the Google Photos Library API allow you to access the bytes of the media items. Using the various base URLs, your app can either download the media items or display the media items within your app. Base URLs are strings which are included in the response when you list albums or access media items. They are valid for 60 minutes and require additional parameters as they cannot be used as is.

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

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`=w`max-width`-h`max-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`=w`max-width`-h`max-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

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

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`=w`max-width`-h`max-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

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

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.

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.