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

Adding enrichments to app-created albums requires the `photoslibrary.appendonly`
scope. For more information on scopes, see [Authorization
scopes](https://developers.google.com/photos/overview/authorization).

## 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](https://developers.google.com/static/photos/images/adding-enrichments-text.png)

### 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](https://developers.google.com/static/photos/images/adding-enrichments-location.png)

### 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](https://developers.google.com/static/photos/images/adding-enrichments-map.png)

## 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](https://developers.google.com/photos/library/guides/upload-media#creating-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`](https://developers.google.com/photos/library/reference/rest/v1/albums/addEnrichment.md.txt).

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:

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

Here is a sample response:

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

## Supported enrichments

### Text enrichments

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

### REST

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

### Java

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

### PHP

```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

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

### Java

```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

```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

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

### Java

```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

```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

```restructuredtext
{
  "position": "FIRST_IN_ALBUM",
}
```

### Java

```java
AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();
```

### PHP

```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

```restructuredtext
{
  "position": "LAST_IN_ALBUM",
}
```

### Java

```java
AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();
```

### PHP

```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

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

### Java

```java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);
```

### PHP

```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

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

### Java

```java
AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);
```

### PHP

```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.