google-photos: the Library API sample in one Node app

What the Library API does, and what this repository shows

The Google Photos Library API lets you read, write and share photos and videos in Google Photos. That single sentence in the README is the whole scope of the API surface, and it is worth sitting with the three verbs, because they map onto three different kinds of work.

Reading is the easy one, and it is what most integrations need. Writing means creating new media items in a user's library, which is a different class of operation with different consent and quota requirements. Sharing means the album and sharing model on top of the media itself, which is where the API's object graph gets less obvious.

This repository contains a sample for that API, and the description is short and honest about it: samples for the Google Photos Library API. The primary language is JavaScript, the licence is Apache-2.0, and the default branch is `main`.

The framing matters for how you read the code. A sample is not a library. There is nothing here to add to your `package.json` and call, no exported client, no versioned contract. What is here is a working program that somebody wrote to show how the pieces fit together, and reading it is a way of learning the sequence of API interactions without having to derive them from the API reference alone.

That sequence is the actual subject of the repository. The sample shows a complete path through the API, in a domain, with the pieces in the order they have to happen.

The REST/PhotoFrame sample and its express.js shape

There is one sample in the repository, and it lives under `REST/`. The README describes it as showing how to use the REST API in a Node.js web application to build an interactive photo frame that loads photos from a user's Google Photos library, and it is built with express.js.

The choice of a photo frame is a good one for a sample, because it forces the interesting parts of the API to appear. A photo frame has to authenticate the user, obtain a list of media items, and then display them. That means the sample cannot avoid the authorisation dance, and it cannot avoid the listing and the media fetch, and those are exactly the three things a developer starting out with the API has to get right.

Express.js is the web framework. The consequence of building a web app rather than a script is that the sample's shape has a server component, a route or two for serving the frame, and the API access sitting behind them. That is a materially different structure from the command line samples that usually accompany an API launch, and it is the structure most people actually want, because a photo library is a user facing thing.

The repository root is minimal and says something about the scope. The top level entries are `CONTRIBUTING.md`, `LICENSE`, `README.md` and `REST/`. There is no `src/`, no `test/`, no build configuration at the root, and no package manifest at the root. Everything that is code lives under the sample directory, which is the conventional layout for a repository that holds samples rather than a product.

Running it: the README in the sample directory is the guide

There is no install or run command in the top level README, and the project points you elsewhere for it. Under the running the samples heading it says to follow the README for the REST/Photoframe sample for steps on how to get started, and the link goes to `REST/PhotoFrame/README.md`.

That is a deliberate structure for a samples repository. Each sample carries its own instructions, because the prerequisites differ: a REST sample needs a web server, credentials and a project configured in the Google Cloud console, and a different sample might need a mobile toolchain or a device. A single top level quick start would have to be generic enough to be useless.

So the practical tutorial is: open `REST/PhotoFrame/README.md`, and work from there. That document is where the project puts the setup steps, and the top level README's only job is to route you to it.

The one thing the top level README does say about support is worth noting. If you have found an error in this sample, file an issue on the repository. Patches are encouraged, and may be submitted by forking the project and submitting a pull request through GitHub, with CONTRIBUTING.md holding the details.

The repository has no GitHub releases, which is consistent with a samples repository. A sample is not versioned as a distributed artefact, so there is no changelog to track and no upgrade path to follow, because you do not depend on it.

Where a sample stops and a library begins

The honest limitation of this repository is that it is one application, and that application is a demonstration. Three consequences follow, and they are worth spelling out because they are what a reader will run into.

The first is that there is nothing to import. If your plan was to add a Photos client to your project, this repository does not give you one. You read the sample, take the shape of the requests and the object model from it, and write the client you need, in your own code, against your own error handling and your own retry policy. The sample shows the happy path.

The second is that a sample is not tested against the API's edge cases. It does not show what happens when a media item is deleted between listing and fetching, when a quota is exhausted, when a token expires mid-session, or when a user's library is large enough that pagination matters. Those are exactly the cases that decide whether an integration survives contact with real use, and they are the cases a demo leaves out, because a demo that handled them would need to be a library.

The third is maintenance. The last push to the tree was on 2026-04-02, which is more than six months before the date of this writing, and the repository has no GitHub releases and no versioned artefacts. The code is a snapshot of how the API was used at one point, not a maintained client that tracks API changes. Treat the code as a map of the API's shape, and check the current API documentation for anything you intend to rely on.

The alternative: write the client yourself, and what the sample saves you

There are two ways to approach an API like this, and the sample exists to make the second one cheaper.

The first is to start from the API reference and work out the object model, the endpoint shapes, the authorisation flow and the media lifecycle by reading documentation. That is entirely feasible and it produces a client shaped exactly around your needs, with no sample code to unpick. The cost is that the reference tells you what each endpoint does, not what order to call them in, and the order is where most of the friction in a first integration lives.

The second is to read the sample and take the sequence from it. The saving is not the code itself, it is the shape of the flow: which call comes first to establish authorisation, which call lists the library, which call fetches the actual media bytes, and how the pieces are wired together in an express application rather than in a script. That is knowledge the reference does not hand you.

The difference in approach is worth naming precisely, because it decides how much of the sample you keep. A sample is a demonstration, so you keep none of its code: you keep the ordering and the object shapes and you write your own client, with your own session handling and your own error handling. A library is the opposite, you keep the code and discard the ordering, but you inherit the library's assumptions about how the API is used.

For a read-only photo display, writing the client yourself on the back of this sample is a small job. For an integration that writes media and manages sharing, the same exercise is larger, and at that point the sample is a reference to consult rather than a foundation to build on.

Licence, provenance and what the repository signals

The licence is Apache-2.0, and the README carries the full standard text with the copyright line reading Copyright 2018 Google LLC. The repository's own licence field agrees. The Apache 2.0 terms are permissive and include an express patent grant, which is the part most often relevant to a commercial team adopting sample code, and they require that the copyright notice and the licence text are kept in copies of the code you redistribute.

The 2018 copyright date is a small but real signal about the age of the code, and it lines up with the rest of the picture. This is a repository from the period when the API was introduced, with a sample structure, no releases, and a last push to the tree on 2026-04-02.

The `REST/` directory name is worth a second look too. The sample is named for the protocol it uses, which suggests the repository was laid out to hold more than one flavour of sample, with the API's REST surface occupying one slot. Only that one is present in the tree here, so a reader looking for a second approach will not find it.

The topics on the repository are `google-photos` and `sample`, which is the project's own summary of itself. There is no claim of library scope, no support promise beyond the issue tracker, and no paid tier. The whole contribution model is: file an issue for an error in the sample, or fork and send a pull request.

So the sensible way to treat this repository is as documentation that happens to be executable. Read it once, take the flow, and then own your own code.

Editorial conclusion

Use this repository as a reference implementation rather than a dependency, because it is a sample with a single application under `REST/`, no published releases and no library API to import. Do not expect it to become the basis of a production service, since the value it offers is the shape of the API calls and the OAuth flow rather than maintained code. If you are building against the Library API now, the first thing to read is `REST/PhotoFrame/README.md`, which is where the project puts its getting started steps, and the second is to check that the sample still matches the current API version, given that the last push to the tree was on 2026-04-02.

Frequently asked questions

Official sources

1. googlesamples/google-photos on GitHub
2. Issues
3. License: Apache-2.0
4. README