## Required authorization scopes Listing app-created content requires the `photoslibrary.readonly.appcreateddata` scope. For more information on scopes, see [Authorization scopes](https://developers.google.com/photos/overview/authorization). ## 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)](https://developers.google.com/photos/library/guides/apply-filters) when listing to narrow your results > [!NOTE] > **Note:** Filters are not supported when you list items from albums. - Retrieve [`mediaItem`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems) objects with essential details like direct links and metadata. Listing the library and album contents returns a list of media items. [Enrichments](https://developers.google.com/photos/library/guides/add-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](https://developers.google.com/photos/library/guides/access-media-items) and [`mediaItems`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems). > [!CAUTION] > **Caution:** Don't cache user photos and videos. Instead, store the media item `id` and request its details again when you need them. Images may change, and direct access through the `baseUrl` expires after 60 minutes. For more information, see [Access media items](https://developers.google.com/photos/library/guides/access-media-items). ## List app-created albums You can list albums that have been created by your app using [`albums.list`](https://developers.google.com/photos/library/reference/rest/v1/albums/list). ### REST Here is a sample request: ``` GET https://photoslibrary.googleapis.com/v1/albums ``` The request returns the following result: ```restructuredtext { "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](https://developers.google.com/photos/library/guides/list#listing-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](https://developers.google.com/photos/library/reference/rest/v1/mediaItems) 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](https://developers.google.com/photos/library/guides/access-media-items#base-urls). The response also contains a `nextPageToken`. For more information, see [Pagination](https://developers.google.com/photos/library/guides/list#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](https://developers.google.com/photos/library/guides/apply-filters). To list a media items, call [`mediaItems.list`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems/list). ### REST Here is a sample request: ```restructuredtext { "pageSize": "100", } ``` The GET request returns the following response: ```restructuredtext { "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" } ``` The response contains a list of media items, ordered from most to least recent. For more information, see [`mediaItems`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems#MediaItem). It also contains a `nextPageToken`, which is described in more detail in [Pagination](https://developers.google.com/photos/library/guides/list#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](https://developers.google.com/photos/library/guides/list#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](https://developers.google.com/photos/library/guides/performance-tips) and [Best practices](https://developers.google.com/photos/library/guides/best-practices). ### REST Here is a sample request: ```restructuredtext { "pageSize": "100", "albumId": "album-id" } ``` The POST request returns the following response: ```restructuredtext { "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`](https://developers.google.com/photos/library/reference/rest/v1/mediaItems) and [Pagination](https://developers.google.com/photos/library/guides/list#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. > [!NOTE] > **Note:** The `pageSize` parameter is a maximum --- fewer results might be returned than are requested. ### 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. > [!NOTE] > **Note:** The existence of `nextPageToken` is the only indicator of whether or not there are more results to be fetched from the server. Don't count the number of results to determine if you should use your `nextPageToken`. A request may return fewer results than requested in the page size. If a `nextPageToken` is present, you can send a request for more results after your initial request.