Updates to the Google Photos APIs

Posted September 2024.

This page provides details on specific changes being made to the Google Photos APIs. Review the details on this page to understand how the methods and scopes you use may be affected.

Note: All changes take effect March 2025.

Library API: Impact on common use cases

The following sections detail the impact of the upcoming changes on common use cases.

Uploading media items and creating albums

What's changing: No change. You can continue to upload media items and create albums using the photoslibrary.appendonly scope.

What you can do:

If your app is uploading media items or creating albums, make sure your using the photoslibrary.appendonly scope, and not the photoslibrary scope. The photoslibrary scope is being removed.

Listing, searching, and retrieving media items and albums

What's changing: You can now only list, search, and retrieve albums and media items that were created by your app.

What you can do:

• If your app needs users to select photos or albums from their entire library, use to the new Google Photos Picker API. This provides a secure and user-friendly way for users to grant access to specific content.
• If your app relies on accessing the user's entire library, you may need to re-evaluate your app or consider alternative approaches.

Sharing and shared albums

What's changing: Shared albums and the associated API functions (share, unshare, get, join, leave, and list) will return a 403 PERMISSION_DENIED after March 31, 2025.

What you can do:

Direct users to the Google Photos app to manage sharing themselves. You can provide clear instructions or deep links within your app to guide them.

Managing app-created albums: enrichments and album contents

What's changing: The photoslibrary.edit.appcreatedata is being added to the following three methods for conceptual consistency:

• albums.addEnrichment
• albums.batchAddMediaItems
• albums.batchRemoveMediaItems

What you can do:

• If your app already uses these methods, consider adopting the photoslibrary.edit.appcreatedata scope to simplify your authorization process.

Library API: Affected scopes and methods

As part of our changes to the Google Photos APIs, we have made the following updates.

As shown on the updated Authorization page, the following scopes will be removed from the Library API after March 31, 2025:

• photoslibrary.readonly
• photoslibrary.sharing
• photoslibrary

The following scopes will remain:

• photoslibrary.appendonly
• photoslibrary.readonly.appcreateddata
• photoslibrary.edit.appcreateddata

This tables details the specific Library API methods and scopes affected.

Updates	Methods	Scopes
These methods can now only be used with albums and media items created by your app. This includes media items selected with the Picker API and added to the user's library with the Library API.	albums.create mediaItems.batchCreate	Scopes remaining: photoslibrary.appendonly Scopes removed: photoslibrary photoslibrary.sharing
	albums.get albums.list mediaItems.batchGet mediaItems.get mediaItems.list mediaItems.search	Scopes remaining: photoslibrary.readonly.appcreatedata Scopes removed: photoslibrary photoslibrary.readonly
These methods will no longer be available.	albums.share albums.unshare sharedAlbums.get sharedAlbums.join sharedAlbums.leave sharedAlbums.list	Scopes remaining: None Scopes removed: photoslibrary.sharing Note: sharedAlbums.list is being removed because there will no longer be shared albums created by your app available to list.
These methods will have the photoslibrary.edit.appcreatedata added. These methods can now only be used with albums and media items created by your app. This includes media items selected with the Picker API and added to the user's library with the Library API.	albums.addEnrichment albums.batchAddMediaItems	Scopes remaining: photoslibrary.appendonly photoslibrary.edit.appcreatedata Scopes removed: photoslibrary
	albums.batchRemoveMediaItems	Scopes remaining: photoslibrary.edit.appcreatedata Scopes removed: photoslibrary
These methods will remain unchanged.	albums.patch mediaItems.patch	Scopes remaining: photoslibrary.edit.appcreatedata Scopes removed: None

Updates to Photos API policy

The current Acceptable use policy will be replaced after March 31, 2025 with the new Photos API User Data and Developer Policy. The new policy is available now for preview.

Updates to the Photos API documentation

We've made significant changes to the Photos API documentation to reflect upcoming updates and support your development experience:

• Unified Photos APIs Site: We've consolidated all Photos API resources into a single, convenient location (this site), providing a streamlined experience for developers. Here, you'll find:
  • Centralized Resources: Combined setup instructions and general usage guidance, and combined support and policy information for both the Picker API and the Library API.
  • Dedicated API sites: Individual sites with detailed guides, reference documentation, and code samples for the Picker API and the Library API
• Updated Library API Content: The Library API documentation has been revised to reflect its capabilities after the sunset period. Throughout the updated documentation, you'll find labels highlighting any content changed or removed, with links to the corresponding legacy content for reference during migration.
• Preserved Legacy Documentation: We've retained the original Library API documentation for developers who need to migrate existing integrations. If you're starting a new project, use the updated documentation. If you're updating an existing project, refer to both the legacy and updated documentation as needed during your migration.

Frequently asked questions

What's changing with the Google Photos APIs?

We're introducing the new Google Photos Picker API for secure photo selection and updating the existing Library API to focus on managing photos and videos created by your app.

When will these changes take effect?

These changes will take effect March 31, 2025. We encourage everyone with existing integrations that use the Library API for photo picking to migrate to the Picker API as soon as you can.

How will the Library API be affected?

The photoslibrary.readonly, photoslibrary.sharing, and photoslibrary scopes will be removed. API calls relying only on these scopes will return a 403 PERMISSION_DENIED. Several other calls will be restricted to working only with photos and videos created by your app.

You can review the complete set of changes in the table at the top of this page.

What should I do if my app currently uses the affected scopes or methods?

If your app uses any of the affected scopes or methods, we recommend you take the following steps:

• For photo selection: migrate to the Google Photos Picker API.
• For other functionalities: review the updated Library API documentation to understand the changes and identify features in your app that may no longer be available. You may need to adjust your app's functionality or explore alternative solutions for some use cases.

What is the Google Photos Picker API?

The Picker API is a new, secure way for developers to let users select photos and albums from their Google Photos Library, and seamlessly send them back to your application. The Picker API offers robust photo selection capabilities, including selecting individual items, selecting all items in an album, and searching the Google Photos Library.

Where can I find more information about these changes?

This page you're currently viewing provides an overview and a summary of all the changes.

The rest of the documentation on our site has been updated to reflect the updated APIs.

What if I have further questions or need help migrating my application?

If you have questions on the developer documentation, review our support page for additional details on getting help.