Using the new Google Photos Picker API in Golang

Like many, I’ve been using the Google Photos Library API to power a custom photo frame—two frames, in fact: one with a raspberry pi and another running Android. In March 2025, Google will stop allowing apps to use the Photos Library API. This will essentially break all apps that use Google Photos for a photo frame. It also breaks all apps that back up your photos to AWS S3 or a NAS, like the popular gphotos-sync which has been archived due to the change in Google’s policy.

What’s changing with the Google Photos API?

Previously, a user could grant access to an app to read media (photos and videos) from their Photos library. I guess Google decided this opens up too much of the user’s content, so they introduced a “photo picker” on Android. Instead of granting access to the whole library, a user explicitly grants access to specific media (and not albums or the whole library). The old API is called the “Library API” and the new one is the “Picker API”.

The way the Picker API works is:

1. The user authenticates with Google and allows your app to request photos from the Google Photos picker UI.
2. Your app sends a request to Google to create a “picker session”.
3. Google responds with the details of the “picker session”, including a Picker URL where the user can pick media to share with your app.
4. You redirect the user to the Picker URL.
5. The user picks which media they want your app to access and then selects “Done”.
6. Your app polls the Picker API for when the user is done.
7. Once the user is done, your app can query the Picker API for details of all the media items selected.

I tried a lot of different workarounds to continue using the Library API. Let me save you some time: none of them work.

Here’s the one that seemed most promising: The Library API will still work if the album or media is created by your app. I tried creating albums and adding media into it, but the app still can’t see it. To see the media via the Library API, the album has to be created by your app and the media has to be created by your app.

Admitting defeat, the Google Photos Picker API is the only way forward.

As a big fan of golang, I looked for a package that could interact with the Picker API for me. Google’s Picker API documentation is clear as mud, and having someone else figure out it out for me would be ideal. For reasons unknown, in 2019, Google stopped generating Golang package stubs from their Google Photos API definitions. The #1 result for google photos golang on Google itself does not support the Picker API.

Introducing gphotos for golang

With nothing else available, I wrote a new golang package for interacting with the Picker API.

There’s essentially two things to solve:

1. Prompting the user to authorize your app so you can create a “picker session.” Without a full blown web app, this is surprisingly complicated to orchestrate.
2. Manage “picker sessions” by sending the user to a URL, letting them pick, then managing the media that the user picked.

A further complexity is the “picker session” usually expires within 24 hours. This means your app only has access to the picked media for a short time.

Based on these limitations, I’ve come to the conclusion that the only logical solution is to copy off the media from Google Photos while the “picker session” is still valid. Then the media can be used after the session is done. AWS S3 is a logical place to store this data so that your apps can fetch the media when they need it. This package includes an optional uploader to s3.

Getting started

Start by reading the README of course or visiting the godocs.

Then fetch the package for your go environment:

go get github.com/polastre/gphotos

There’s two command line (cli) tools.

• auth which performs step 1 above of authenticating the user, authorizing your app, and getting a valid OAuth token.
• picker which handles the flow of picking media and then uploading it to a S3 bucket including the json metadata.

This is, of course, all configurable if you choose to use github.com/polastre/gphotos as a package instead of the command line tools. Feel free to do so!

I hope others find this useful. Any problems, feel free to open a Github Issue.