Add enrichments

Enrichments let your application control the structure and presentation of photos within an album in Google Photos. They allow you to present the user with additional context through text or location annotations and order/group images that tell a story together.

Required authorization scope

To add enrichments, at least one of the following scopes is required:

  • photoslibrary.appendonly
  • photoslibrary.library
  • photoslibrary.sharing

For each scope, the enrichAlbum call is restricted to only the albums created by the app.

When using the .sharing scope, enrichAlbum is restricted to circumstances where the developer is acting on behalf of the owner of the shared album.

Enrichment types

Google Photos supports three types of enrichments in albums: text, locations, and maps.

Text enrichments

A text enrichment is a plain text string that can be inserted to annotate the album.

Screenshot of a text enrichment shown in Google Photos

Location enrichments

A location enrichment is a marker and the name of the place that can be inserted to annotate a location.

Screenshot of a location enrichment shown in Google Photos

Map enrichments

A map enrichment is a map with a specified origin and destination that can be inserted in the album.

Screenshot of a map enrichment shown in Google Photos

Positions

To insert media items and album enrichments, specify the position of the album. A position is optional for media items, but must be specified for album enrichment.

A position can only be specified when creating a media item or adding enrichments. Existing media items in an album can't be reorganized, so it's important to set the position of an item when it's being added.

Start of album

A media/enrichment item can be added to the start of the album as absolute positioning.

End of album

A media/enrichment item can be added to the end of the album as absolute positioning.

Relative to media item

A media/enrichment item can be added relative to a media item beginning after its position in the album.

Relative to enrichment item

A media/enrichment item can be added relative to an enrichment item beginning after its position in the album.

Adding enrichments to album

Enrichments are added one at a time and must be added to a position in an album. To add enrichments to an album, call albums.addEnrichment.

If the request is successful, it returns the id of the enrichment item, which can be used to position media items or other enrichments.

REST

Here is a POST request:

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

The request body consists of the enrichment item and its position:

{
  "newEnrichmentItem": {
    enrichment-to-be-added
  },
  "albumPosition": {
    position-of-enrichment
}

Here is a sample response:

{
  "enrichmentItem": {
    "id": "enrichment-item-id",
  }
}

Java

try {
  // Create the enrichment using the NewEnrichmentItemFactory helper
  NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment("");

  // Set the position of the enrichment within the album
  AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

  // To add an enrichment, specify the album, the enrichment item,
  // and the position in the album where the enrichment is to be added
  AddEnrichmentToAlbumResponse response = photosLibraryClient
      .addEnrichmentToAlbum(albumId, newEnrichmentItem, albumPosition);
  // The response contains an EnrichmentItem
  // whose ID can be used to position media items or other enrichments
  EnrichmentItem enrichmentItem = response.getEnrichmentItem();
  String itemId = enrichmentItem.getId();
} catch (ApiException e) {
  // Handle error
}

PHP

// Create the enrichment item using the PhotosLibraryResourceFactory helper
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("");
// ...
// Set the position of the enrichment within the album
$position = new AlbumPosition();
// ...
try {
    // To add an enrichment, specify the album, the enrichment item,
    // and the position in the album where the enrichment is to be added
    $response = $photosLibraryClient->addEnrichmentToAlbum($albumId, $newEnrichmentItem, $position);
    // The response contains an EnrichmentItem
    // whose ID can be used to position media items or other enrichments
    $enrichmentItem = $response->getEnrichmentItem();
    $itemId = $enrichmentItem->getId();

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

Supported enrichments

Text enrichments

Text enrichments contain a single text string (no more than 1000 characters), as shown in the following example:

REST

{
  "text": "Text to be shown"
}

Java

// Use the NewEnrichmentItemFactory helper to create a text enrichment item
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createTextEnrichment("text to be shown");

PHP

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");

Location enrichments

Location enrichments consist of an arbitrary location name and the latitude and longitude position. The locationName is limited to 500 characters.

REST

{
  "location": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a location enrichment
// with the name, latitude, and longitude of the location
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);

PHP

// Create a new location object and set the name, latitude, and longitude of the location
$newLocation = new Location();
$newLocation->setLocationName("Australia");
$newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);

Map enrichments

Map enrichments show two locations, each consisting of a name and the latitude and longitude. Similar to the location enrichment, the locationName within the origin and destination is limited to 500 characters.

REST

{
  "origin": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  },
  "destination": {
    "locationName": "San Francisco",
    "latlng": {
      "latitude": "37.757",
      "longitude": "122.507"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a map enrichment item for
// an origin and a destination location
NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment(
    "Australia", -21.197, 95.821, // origin
    "San Francisco", 37.757, 122.507 // destination
);

PHP

// Create two new location objects to create a map enrichment item
// for an origin and a destination location
$locationAustralia = new Location();
$locationAustralia->setLocationName("Australia");
$locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$locationSanFrancisco = new Location();
$locationSanFrancisco->setLocationName("San Francisco");
$locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507));

$newEnrichmentItem =
  PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);

Supported positioning

Start of album

The position FIRST_IN_ALBUM refers to the start of the album. Items located here are shown to the user first:

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);

End of album

The position LAST_IN_ALBUM refers to the end of the album. Items located here are shown to the user last.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);

Relative to media item

Specifying the position relativeMediaItem refers to a position relative to a media item. The items are added after the specified media item.

REST

{
  "position": "after-media-item",
  "relativeMediaItemId": "media-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);

Relative to enrichment item

Specifying a relativeEnrichmentItemId refers to a position relative to an enrichment item. The items are added after the specified enrichment item.

REST

{
  "position": "after-enrichment-item",
  "relativeEnrichmentItemId": "enrichment-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);

Modifying enrichments

Currently, there is no way to modify enrichments. However, once an enrichment has been created and added to an album, the user can modify the enrichments through the Google Photos app.