Share media

Using the Google Photos Library API you can share media via shared albums. Your app can create, share and unshare these albums between users. Media items can also be added by the users who join your shared albums.

Note that your app can:

  • Share media items only when they are in a user's album.
  • Share only the albums created by your app.
  • Join only the albums created and shared by your app in another user's account. You cannot join albums that have been shared by other apps.

Required authentication scope

In order to share content, your app must request the .sharing authorization scope.

Sharing an album

To share an album, first create an album and then call albums.share using an albumId. You receive the albumId when you create an album. For an album you've created earlier, you can retrieve the albumId by listing the albums.

In the call to share an album, you can specify the following options inside sharedAlbumOptions. Note that if the options are not explicitly set, the default values are used.

Property Default value Description
isCollaborative false Sets whether other Google Photos users can add content to the shared album.
isCommentable false Sets whether other Google Photos users can comment on the shared album.

REST

Here is a POST request header to share an album:

POST https://photoslibrary.googleapis.com/v1/albums/ALBUM_ID:share
Content-type: application/json
Authorization: Bearer OAUTH2_TOKEN

In the request body, include the options you want to set for the shared album.

{
  "sharedAlbumOptions": {
    "isCollaborative": "true",
    "isCommentable": "true"
  }
}

The POST request returns the following response:

{
  "shareInfo": {
    "sharedAlbumOptions": {
      "isCollaborative": "true",
      "isCommentable": "true"
    },
    "shareableUrl": "SHAREABLE_URL",
    "shareToken": "SHARE_TOKEN",
    "isJoined": "TRUE_IF_USER_JOINED_THIS_ALBUM"
  }
}

Java

try {

  SharedAlbumOptions options =
          // Set the options for the album you want to share
          SharedAlbumOptions.newBuilder()
          .setIsCollaborative(true)
          .setIsCommentable(true)
          .build();
  ShareAlbumResponse response = photosLibraryClient.shareAlbum(albumId, options);

  // The response contains the shareInfo object, a url, and a token for sharing
  ShareInfo info = response.getShareInfo();
  // Link to the shared album
  String url = info.getShareableUrl();
  String shareToken = info
  // The share token which other users of your app can use to join the album you shared
      .getShareToken();
  SharedAlbumOptions sharedOptions = info
      // The options set when sharing this album
      .getSharedAlbumOptions();

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

PHP

    // Set the options for the album you want to share
    $options = new SharedAlbumOptions();
    $options->setIsCollaborative(true);
    $options->setIsCommentable(true);
    try {
        $response = $photosLibraryClient->shareAlbum($albumId, ['sharedAlbumOptions' => $options]);
        // The response contains the shareInfo object, a url, and a token for sharing
        $shareInfo = $response->getShareInfo();
        // Link to the shared album
        $url = $shareInfo->getShareableUrl();
        // The share token which other users of your app can use to join the album you shared
        $shareToken = $shareInfo->getShareToken();
        // The options set when sharing this album
        $sharedOptions = $shareInfo->getSharedAlbumOptions();
    } catch (\Google\ApiCore\ApiException $e) {
        // Handle error
    }

The response contains the shareInfo property, which is made up of sharedAlbumOptions, shareableUrl, shareToken, and isJoined properties. sharedAlbumOptions specifies the options you set when sharing the album, shareableUrl is the link to the album you shared through the API, and shareToken can be used to join other users to the shared album through the API. After the user joins the shared album, isJoined is true. Note that isJoined is always true for the owner of the album.

Unsharing an album

Once your application has shared an album, you can mark it as private by calling albums.unshare using an albumId. After making this call, the album is no longer shared and all non-owners lose access to the album.

All content added by other users is removed from the album. If a user has previously added the album to their library, the content is retained in their library.

REST

Here is a POST request header to unshare an album:

POST https://photoslibrary.googleapis.com/v1/albums/ALBUM_ID:unshare
Content-type: application/json
Authorization: Bearer OAUTH2_TOKEN

The request body must be empty.

If the request was successful, it returns an empty response with a HTTP success status code. If the request was not successful, it returns a HTTP error status code with an error message.

Java

try {
  // If this call is not successful, an exception is raised
  photosLibraryClient.unshareAlbum(albumId);
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Mark the album as private and no longer shared
    // If this call is not successful, an exception is raised
    $photosLibraryClient->unshareAlbum($albumId);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Joining a shared album

Your app can join a shared album on behalf of the user using a shareToken only if your app has created and shared that album. You can retrieve the shareToken available within the shareInfo object by: retrieving album details, listing albums, or listing shared albums.

REST

Here is a POST request header to join a shared album:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join
Content-type: application/json
Authorization: Bearer OAUTH2_TOKEN

In the request body, specify the shareToken.

{
"shareToken": "SHARE_TOKEN"
}

The POST request returns the shared album you have joined.

Java

try {
  // Join the shared album using the share token obtained when sharing the album
  // If this call is not successful, an exception is raised
  JoinSharedAlbumResponse response = photosLibraryClient.joinSharedAlbum(shareToken);
  Album joinedAlbum = response.getAlbum();
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->joinSharedAlbum($shareToken);
    // Join the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $joinedAlbum = $response->getAlbum();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

To join a shared album, follow these steps:

  1. Your app shares an existing album in User A's account.

    The call returns a shareToken.

  2. Your app should store this shareToken.
  3. User B authenticates in your application and wants to join the shared album.
  4. On behalf of User B, your app makes a sharedAlbums:join request using the shareToken.
  5. User B has now joined the shared album and has access to all the album contents.

Leaving a shared album

Your app can leave a shared album on behalf of a user using a shareToken. You can retrieve the shareToken available within the shareInfo object by: retrieving album details, listing albums, or listing shared albums.

You can leave a shared album only if your app has created the album and the user is not the owner.

REST

Here is a POST request header to leave a shared album:

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave
Content-type: application/json
Authorization: Bearer OAUTH2_TOKEN

In the request body, specify the shareToken.

{
"shareToken": "SHARE_TOKEN"
}

If the request was successful, it returns an empty response with a HTTP success status code. If the request was not successful, it returns a HTTP error status code with an error message.

Java

try {
  // Leave a shared album using its share token
  // If this call is not successful, an exception is raised
  photosLibraryClient.leaveSharedAlbum(shareToken);
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    // Leave the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $photosLibraryClient->leaveSharedAlbum($shareToken);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Retrieving a shared album

You can retrieve an album shared by your app in the following ways:

REST

Here is a request to get an album by its shareToken:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums/SHARE_TOKEN

If the request is successful, it returns an instance of the shared album.

Java

try {
  // Get a shared album from its share token
  Album sharedAlbum = photosLibraryClient.getSharedAlbum(shareToken);

  String id = sharedAlbum.getId();
  String title = sharedAlbum.getTitle();
  // ...

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

PHP

try {
    // Get the album from a share token
    $album = $photosLibraryClient->getSharedAlbum($shareToken);

    // Get some properties of an album
    $productUrl = $album->getProductUrl();
    $title = $album->getTitle();

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

List app created shared albums

To list the shared albums created only by your app, call sharedAlbums.list along with the excludeNonAppCreatedData parameter.

Shared album properties

For albums that have been created and shared by your app, album list calls (such as albums and sharedAlbums) include an additional property, shareInfo.

Shared media item properties

For media items that belong to albums shared by your app, the MediaItem resource contains an additional property, contributorInfo. You can retrieve this property by searching for media items, with an albumId set.

The contributorInfo property includes details of the user who added the media item to the album; the user's name and a URL to the user's profile image.

"contributorInfo": {
  "profilePictureBaseUrl": "PROFILE_PICTURE_BASE_URL-DO_NOT_USE_DIRECTLY",
  "displayName": "NAME_OF_USER"
}