# Get started with the Picker API

The Picker API provides a secure way for your users to select photos and videos
from their Google Photos library and share them with your application.

## Before you start

- **Check out the overview:** [Compare the Picker API and the Library API](https://developers.google.com/photos/overview/about) to make sure the Picker API is the right fit for your use case.
- **Configure your app:** Enable the API and set up authentication. See [Configure your app](https://developers.google.com/photos/overview/configure-your-app) for detailed steps.

## The Picker API flow

Here is an overview of the how the Picker API works:

1. **Check for OAuth token:** Before starting the Picker API flow, check for a
   valid OAuth 2.0 access token for the user. If there is no token, [initiate
   the OAuth 2.0 authorization flow](https://developers.google.com/identity/protocols/oauth2) to obtain one.

2. **Create a session:** Initiate the process by making a call to the Picker
   API to [create a new
   session](https://developers.google.com/photos/picker/reference/rest/v1/sessions/create). This call will
   return a unique `pickerUri`.

3. **Direct users to the Google Photos app:** Provide the [`pickerUri`](https://developers.google.com/photos/picker/reference/rest/v1/sessions#PickingSession.FIELDS.picker_uri)
   to your users (either as a clickable link or a QR code). This URL will
   securely open their Google Photos app. For web-based applications, you can
   append `/autoclose` to this URI to automatically close the Google Photos
   window after the user completes their selection.

4. **User selects media items:** Within the Google Photos app, users can browse
   their library and select the photos and videos they want to share with your
   app. Read an overview of the [user's picking experience](https://developers.google.com/photos/picker/guides/picking-experience).

5. **Poll the session:** Your app should periodically [poll the session](https://developers.google.com/photos/picker/reference/rest/v1/sessions/get)
   to check the status. You're looking for the
   [`mediaItemsSet`](https://developers.google.com/photos/picker/reference/rest/v1/sessions#PickingSession.FIELDS.media_items_set)
   property to return true, indicating the user has finished their selection.

   > [!NOTE]
   > **Note:** Every time you poll a session the response contains [recommended
   > intervals and
   > timeouts](https://developers.google.com/photos/picker/reference/rest/v1/sessions#PollingConfig) to configure your polling.

6. **List selected media items:** Once `mediaItemsSet` returns true, you can
   use [the list method](https://developers.google.com/photos/picker/reference/rest/v1/mediaItems/list) to
   get details about the selected media items.

7. **Retrieve and use media items:** Now you have access to the selected media
   items. You can [fetch their
   content](https://developers.google.com/photos/picker/guides/media-items#retrieve-picked-media-items)
   using the
   [`baseUrl`](https://developers.google.com/photos/picker/reference/rest/v1/mediaItems#MediaFile.FIELDS.base_url)
   and utilize them within your application.

## Next steps

- Review the reference docs: Explore the detailed [Picker API reference
  documentation](https://developers.google.com/photos/picker/reference/rest) to learn about all the available methods and parameters.
- Try out the samples: Check out our [sample](https://developers.google.com/photos/picker/samples) to see the Picker API in action and get inspiration for your integration.