# Get Started with the Ambient API

The Ambient API enables your application to connect ambient devices to a user's
Google Photos account and display their selected photos.

## The Ambient API Flow

Here's a breakdown of how the Ambient API works to connect a device and then
retrieve and display media items:

1. Check for existing device (recommended): Before creating a new device, it's
   recommended to check if a device for the current user already exists. Your
   application should maintain a mapping between your internal user and the
   Google-provided `deviceId` for any devices they create through your app. If
   a `deviceId` is found for the user, you can proceed to refreshing their
   authorization token (if needed).

2. Initiate OAuth 2.0 authorization (and optionally create device): Begin the
   [OAuth 2.0 for TV and Limited Input Devices](https://developers.google.com/photos/ambient/guides/configure-your-app)
   flow by requesting an authorization code.

   > [!NOTE]
   > **Note:** The Ambient API supports the option to include the `state` parameter in your authorization request. This will instruct the Ambient API to also attempt to create a new device upon successful authorization.

3. Create a new device: Your app creates a device in a user's Google Photos
   account by calling `CreateDevice` and providing a valid v4 UUID.

   Upon successful device creation, the API will return an `AmbientDevice`
   object containing a Google-assigned `deviceId`. It is crucial for your
   application to store this `deviceId` and associated it with your users.
4. Display the `settingsUri`: an `AmbientDevice` object includes a
   `settingsUri`. Present this URI to the user, typically as a QR code, which
   the user can scan using their mobile device. This URI directs the user to
   the Google Photos app where they can configure the media sources (e.g.,
   albums) they want to display on their ambient device.

5. Poll for `mediaSourcesSet`: Your application should periodically call the
   `GetDevice` method, providing the `deviceId`, to check the status of the
   ambient device. Monitor the `mediaSourcesSet` field in the `AmbientDevice`
   response. It will initially be false.

   Once the user has successfully selected media sources in the Google Photos
   app, this field will change to true.

   The `AmbientDevice` response includes a `pollingConfig` with a
   `pollInterval` that you should use as a guideline for your polling
   frequency.
6. Retrieve media items: When `mediaSourcesSet` returns true, your application
   can begin fetching the media items selected by the user.

   Call the `ListMediaItems` method, providing the `deviceId`. The API will
   return a `ListMediaItemsResponse` containing a list of `AmbientMediaItem`
   objects. Each `AmbientMediaItem` includes details like an `id`,
   `createTime`, and a `MediaFile` object with additional metadata. The
   `MediaFile` contains a `baseUrl` which you can use to fetch the actual bytes
   of a media item. Review the guide to [List and retrieve media items](https://developers.google.com/photos/ambient/guides/media-items)
   for details on additional `baseUrl` parameters.
7. Display Media Items: Use the `baseUrl` from the `MediaFile` to download and
   display the media content on the ambient device.

## Important Considerations

Device limit and management:

- Device limits: Be aware of the limit of 100 devices per user of your application.
- Device activity and tokens: You'll need to manage the lifecycle of devices and user authorization tokens. Consider how long devices remain active and how you'll handle token refreshes or re-authorization if a device becomes inactive or the token expires.

The guide to [Create and manage devices](https://developers.google.com/photos/ambient/guides/devices) has
additional details.

Working with media items:

- Media item usage: Understand how to properly fetch and handle the media item content using the `baseUrl`, including any necessary authentication or parameters.
- Error handling: Implement robust error handling for API calls, including scenarios like `NOT_FOUND` for devices, `FAILED_PRECONDITION` if media sources are not set, and `RESOURCE_EXHAUSTED` if device limits are reached.

The guide to [List and retrieve media items](https://developers.google.com/photos/ambient/guides/media-items)
has additional details, including information on [content policy and
filtering](https://developers.google.com/photos/ambient/guides/media-items#content-policy).

## Next Steps

- **Configure your application:** Verify you have the necessary credentials and have configured your application for [OAuth 2.0 for TV and Limited Input
  Devices](https://developers.google.com/photos/ambient/guides/configure-your-app).
- **Review the Ambient API Reference Documentation:** Explore the [detailed
  reference documentation](https://developers.google.com/photos/ambient/reference/rest) for all available methods, request and response parameters, and error codes.