Share media

Albums created by your app can be shared between users, with options to allow those users to comment on, or contribute their own media items to the album.

To share an album through the Google Photos Library API, your app needs to do the following:

  1. Create an album on behalf of a user.
  2. Set that album to shared.

Required authentication scope

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

Sharing an album

Before sharing an album, take the following considerations into account:

  • Your app can only share albums it has created. Albums created by other apps, including Google Photos, can't be shared by your app.
  • When your app shares an album via the Library API, a shareable URL is generated that anyone can use to access the album.
  • For albums shared via the API, the album's owner can turn off link sharing or unshare the album in the Google Photos app, potentially preventing your app from joining new users to it.

To share an album:

  1. Follow the UX guidelines and obtain explicit consent from the user to create a shared album.
  2. Create the album, and record its albumId. If you've already created the album, you can retrieve its albumId by listing the user's albums.
  3. Call albums.share using the relevant albumId, along with the share options you want to set.
  4. Record the shareToken value in the response. The share token is an identifier for a shared album that can be used across different user accounts.
  5. Another user can now authenticate with your app, then join, leave, or retrieve the details of the shared album using its shareToken.

Share options

The following options can be set when sharing an album using the sharedAlbumOptions parameter. If the options aren't 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.

Example request

The following request shares an album by calling albums.share with options. A shareInfo property is returned in the response that describes the album's sharing properties.

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, specify the share options.

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

This request returns the following response:

{
  "shareInfo": {
    "sharedAlbumOptions": {
      "isCollaborative": "true",
      "isCommentable": "true"
    },
    "shareableUrl": "shareable-url",
    "shareToken": "share-token",
    "isJoinable": "true-if-users-can-join-album",
    "isJoined": "true-if-user-is-joined-to-album",
    "isOwned": "true-if-user-owns-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
}

Shared album properties

For albums that have been created and shared by your app, all responses that return an album include an additional property, shareInfo. This property is returned when sharing, listing or retrieving albums.

The following table lists the shareInfo properties:

Properties
sharedAlbumOptions Options that describe whether someone can add media items to or comment on a shared album.
shareableUrl

A link to the shared Google Photos album. Anyone with the link can view the contents of the album, so it should be treated with care.

The shareableUrl field is only returned if the album has link sharing turned on. If a user is already joined to an album that isn't link-shared, they can use the album's productUrl to access it instead.

A shareableUrl is invalidated if the owner turns off link sharing in the Google Photos app, or if the album is unshared.
shareToken

A token that is used to join, leave, or retrieve the details of a shared album on behalf of a user who isn't the owner.

A shareToken is invalidated if the owner turns off link sharing in the Google Photos app, or if the album is unshared.
isJoinable True if the album can be joined by users.
isJoined True if the user is joined to the album. This is always true for the owner of the album.
isOwned True if the user owns the album.

Unsharing an album

To unshare an album your app has previously shared, call albums.unshare using the album's albumId.

In addition to the album no longer being shared, the following things will happen:

  • All non-owners will lose access to the album. This includes people who have had the album specifically shared with them through the Google Photos app.
  • All content added by non-owners will be removed from the album.
  • If a user has previously added the contents of the album to their library, the contents will be retained in their library.
  • The album's share token and shareable URL will be invalidated.

Example request

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 an HTTP success status code. If the request was not successful, it returns an 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
}

Retrieving shared albums and share tokens

A shared album's details, including its share token, are returned when your app shares an album. You can also retrieve those details afterwards in the following ways.

If the user currently connected to your app is the owner, or is joined to the album:

If the user currently connected to your app is not joined to the album, you can retrieve a shared album's details with sharedAlbums.get using a valid share token.

Example request

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 the shared album details.

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
}

Joining a shared album

Your app can join a shared album on behalf of a user with the album's share token. To do so, the following conditions must be true:

  • Your app has created and shared the album.
  • The user you want to join to the album isn't its owner. That is, the isOwned field in the album's shareInfo is false.
  • The share token is valid.
  • The isJoinable field in the album's shareInfo is true.

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 your app joined on behalf of the user.

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
}

Leaving a shared album

Your app can leave a shared album on behalf of a user, using the album's share token. To do so, the following conditions must be true:

  • Your app has created and shared the album.
  • The user is currently joined to the album. That is, the isJoined field in the album's shareInfo is true.
  • The user connected to your app is not the owner of the album. That is, the isOwned field in the album's shareInfo is false.

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 an HTTP success status code. If the request was not successful, it returns an 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
}

Shared media item properties

Media items that belong to albums shared by your app contain an additional property, contributorInfo. This property is only included when listing the contents of a shared album.

The contributorInfo property includes the name of the user who added the media item to the album, and a base URL to their profile image.

Here's an example:

{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}