Manage albums

In Google Photos, you can organize photos and other media items using albums. A media item can be associated with one or more albums. To start associating media items with an album, you need to create the album first.

Required authorization scopes

Creating albums requires the photoslibrary.appendonly scope.

Changing the title or cover photo of albums after their creation requires the photoslibrary.edit.appcreateddata scope.

For more information on scopes, see Authorization scopes.

Create a new album

To create an album, call albums.create and include the title. Note that title is restricted to 500 characters.

The call returns an album. Your app can store the album ID from this information and use it for uploading media items to the specific album.

REST

Here is a header for a POST request:

POST https://photoslibrary.googleapis.com/v1/albums
Content-type: application/json
Authorization: Bearer oauth2-token

The request body looks like this:

{
  "album": {
    "title": "new-album-title"
  }
}

If successful, the response returns an album:

{
  "productUrl": "album-product-url",
  "id": "album-id",
  "title": "album-title",
  "isWriteable": "whether-you-can-write-to-this-album"
}

Retrieve album details

To retrieve the details of an existing album created by your app, call albums.get and include the albumId of the album you want to fetch.

The call returns an album.

REST

Here is a header for a GET request:

GET https://photoslibrary.googleapis.com/v1/albums/{albumId}
Content-type: application/json
Authorization: Bearer oauth2-token

The request body looks like this:

{
  "albumId": album-id
}

If successful, the response returns an album:

{
  "id": album-id,
  "title": album-title,
  "productUrl": album-product-url,
  "mediaItemsCount": media-items-count,
  "coverPhotoBaseUrl": cover-photo-base-url,
  "coverPhotoMediaItemId": cover-photo-media-item-id
}

Change album titles and cover photos

To change an album title or cover photo, make an album update call with the identifier of the album, and include the new title or the new cover photo's media item ID in the request. You'll need to use the photoslibrary.edit.appcreateddata authorization scope to make the change.

Album titles can be no more than 500 characters in length. Cover media items must be owned by the album owner, and belong to the album they will be a cover for.

REST

Here's a PATCH request header to update an album's title and coverPhotomediaItemId.

PATCH https://photoslibrary.googleapis.com/v1/albums/album-id?updateMask=title&updateMask=coverPhotoMediaItemId

This request determines what properties are being updated by including a field mask, indicated by the updateMask parameters in the URL. The updateMask parameter needs to be passed for each album property that is being updated.

For each property you are updating, include its details in the body of the request:

{
  "title": "new-album-title",
  "coverPhotoMediaItemId": "new-cover-media-item-id"
}

If successful, the response returns the updated album details:

{
  "id": "album-id",
  "title": "new-album-title",
  "productUrl": "album-product-url",
  "isWriteable": "true-if-user-can-write-to-this-album",
  "mediaItemsCount": "number-of-media-items-in-album",
  "coverPhotoBaseUrl": "cover-photo-base-url_use-only-with-parameters",
  "coverPhotoMediaItemId": "new-cover-media-item-id"
}

Add media items to an album

You can add media items created by your app to albums created by your app by calling albums.batchAddMediaItems. Media items are added to the end of the album in the order given in this call.

The entire request will fail if an invalid media item or album is specified. Partial success is not supported.

Each album can contain up to 20,000 media items. Requests to add more items that would exceed this limit will fail.

To add media items to an album, call albums.batchAddMediaItems with the identifiers of the media items and the album.

REST

Here is a header for a POST request:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchAddMediaItems
Content-type: application/json
Authorization: Bearer oauth2-token

The request body looks like this:

{
   "mediaItemIds": [
     "media-item-id",
     "another-media-item-id",
     ...
   ]
}

If successful, the response returns an empty JSON response and the HTTP Success status.

Remove media items from an album

You can remove media items created by your app to albums created by your app by calling albums.batchRemoveMediaItems.

The entire request will fail if invalid media items are specified. Partial success is not supported.

To remove media items from an album, call albums.batchRemoveMediaItems with the identifiers of the media items and the album.

REST

Here is a header for a POST request:

POST https://photoslibrary.googleapis.com/v1/albums/album-id:batchRemoveMediaItems
Content-type: application/json
Authorization: Bearer oauth2-token

The request body looks like this:

{
   "mediaItemIds": [
     "media-item-id",
     "another-media-item-id",
     ...
   ]
}

If successful, the response returns an empty JSON response and the HTTP Success status.

Java

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

  // ID of the album to remove media items from
  String albumId = "ALBUM_ID";

  // Remove all given media items from the album
  photosLibraryClient.batchRemoveMediaItemsFromAlbum(albumId, mediaItemIds);

} catch (ApiException e) {
  // An exception is thrown if the media items could not be removed
}

PHP

try {

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

    // ID of the album to remove media items from
    $albumId = "ALBUM_ID";

    // Remove all given media items from the album
    $response = $photosLibraryClient->batchRemoveMediaItemsFromAlbum($albumId, $mediaItemIds);

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