List app-created media items and albums

Required authorization scopes

Listing app-created content requires the photoslibrary.readonly.appcreateddata scope. For more information on scopes, see Authorization scopes.

Overview

The Library API lets you to list and access media items that your application has created.

Some key features of listing media items include the following:

  • List media items from specific app-created albums or the entire app-created library

  • Apply filters (date, content category, media type) when listing to narrow your results

  • Retrieve mediaItem objects with essential details like direct links and metadata.

Listing the library and album contents returns a list of media items. Enrichments that are part of an album aren't included. Media items describe a photo, video, or other media. A mediaItem includes a direct link to the item, a link to the item in Google Photos, and other relevant metadata. For more information, see Access media items and mediaItems.

List app-created albums

You can list albums that have been created by your app using albums.list.

REST

Here is a sample request:

GET https://photoslibrary.googleapis.com/v1/albums

The request returns the following result:

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Each returned album has an ID that can be used to retrieve the contents of the album as shown in List album contents. It also includes the title and the number of media items it contains.

The productUrl points to the album in Google Photos that can be a opened by the user.

The coverPhotoMediaItemId contains the media item ID that represents the cover photo of this album. To the access this cover image, use coverPhotoBaseUrl. You shouldn't use the coverPhotoBaseUrl directly without specifying additional parameters.

The response also contains a nextPageToken. For more information, see Pagination.

The response for empty albums varies in that, mediaItemsCount and coverPhotoMediaItemId are set to 0 by default and are omitted from the REST response. Also note that coverPhotoBaseUrl points to a default placeholder image.

List app-created library contents

You can list all the media items from the user's Google Photos library that were created by your app.. This excludes archived and deleted items. You can list media items based on their content, date, and other properties by applying filters.

To list a media items, call mediaItems.list.

REST

Here is a sample request:

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

The GET request returns the following response:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

The response contains a list of media items, ordered from most to least recent. For more information, see mediaItems. It also contains a nextPageToken, which is described in more detail in Pagination.

List album contents

To list all of the media items in an album, add the albumId field to your search request. For more information about albumId, see Listing albums. If the albumId is invalid, a Bad Request error is returned. If the ID is valid, but the album doesn't exist for the authenticated user, a Not Found error is returned. For more details regarding error handling,see Performance tips and Best practices.

REST

Here is a sample request:

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

The POST request returns the following response:

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

The response contains a nextPageToken and the list of media items. Unlike when listing library contents, the media items are returned by their order in the album. For more details, see mediaItems and Pagination. The user can edit the order in the Google Photos interface.

If the albumId is set, you can't apply a filter when listing album contents. Doing so results in a Bad Request error.

Pagination for REST

To improve performance, methods that return a large number of results (such as list methods) may paginate the response. The maximum number of results in each page is given by the pageSize parameter.

For calls to mediaItems.search and mediaItems.list, the default page size is 25 items. We recommend this page size because it strikes a balance between the size of the response and the fill rate. The maximum page size for media item search and list requests is 100 items.

The default and recommended page size when listing albums is 20 albums, with a maximum of 50 albums.

When the number of available results is greater than the page size, the response includes a nextPageToken, which indicates to your application that there are more results to be fetched from the server.

Example

You must append the nextPageToken to subsequent requests in the parameter pageToken, as shown in the following example. Specify the pageToken together with other parameters required for the operation, either in the body of the request, or as a query parameter.

Request #1

{
  "pageSize": "5",
  "filters": { … }
}

Response #1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Request #2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Response #2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Continue this pattern until there are no more nextPageToken objects.

The nextPageToken is only valid for the same request. If any parameters are changed, a previously used nextPageToken shouldn't be used in the same request.