gphotos

README

Google Photos API client for Go

This package provides a client for using the Google Photos API. Uses the original Google Photos package, that was provided by Google, and removed some time ago. On top of the old package has been extended some other features like uploads, including resumable uploads.

This project will maintain compatibility with the last two Go major versions published. Currently Go 1.12 and Go 1.13.

Quick start

Construct a new Google Photos client, then use the various services on the client to access different parts of the Google Photos API. For example:

import (
	"errors"
	"net/http"
	gphotos "github.com/gphotosuploader/google-photos-api-client-go/v2"

)

func main() error {
	httpClient := http.DefaultClient
	ctx := context.Background()

	// httpClient is an authenticated http.Client. See Authentication below.
	client, err := NewClient(httpClient)
	if err != nil {
		return err
	}

	// get or create a Photos Album with the specified name.
	title := "my-album"
	album, err := client.FindAlbum(ctx, title)
	if err != nil {
		if errors.Is(err, ErrAlbumNotFound) {
			album, err = client.CreateAlbum(ctx, title)
			if err != nil {
				return err
			}
		} else {
			return err
		}
	}

	// upload an specified file to the previous album.
	item := FileUploadItem("/my-folder/my-picture.jpg")
	_, err = client.AddMediaToAlbum(ctx, item, album.Id)

	return err
}

Authentication

The gphotos library does not directly handle authentication. Instead, when creating a new client, pass an http.Client that can handle authentication for you. The easiest and recommended way to do this is using the golang.org/x/oauth2 library, but you can always use any other library that provides an http.Client.

Access to the API requires OAuth client credentials from a Google developers project. This project must have the Library API enabled as described here.

	import (
        "golang.org/x/oauth2"
        "github.com/gphotosuploader/google-photos-api-client-go/lib-gphotos"
    )
	func main() {
		ctx := context.Background()
		oc := oauth2Config := oauth2.Config{
			ClientID:     "... your application Client ID ...",
			ClientSecret: "... your application Client Secret ...",
			Endpoint:     photos.Endpoint,
			Scopes:       photos.Scopes,
		}
		tc := oc.Client(ctx, "... your user Oauth Token ...")
		client := gphotos.NewClient(tc)
	}

Note that when using an authenticated Client, all calls made by the client will include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users. See the oauth2 docs for complete instructions on using that library.

Limitations

Rate Limiting

Google Photos imposes a rate limit on all API clients. The quota limit for requests to the Library API is 10,000 requests per project per day. The quota limit for requests to access media bytes (by loading a photo or video from a base URL) is 75,000 requests per project per day.

Photo storage and quality

All media items uploaded to Google Photos using the API are stored in full resolution at original quality. They count toward the user’s storage.

Documentation

Overview

Package gphotos provides a client for using the Google Photos API. Wraps the Google Photos package provided originally by Google, and now maintained in: https://github.com/gphotosuploader/googlemirror.

Usage:

import gphotos "github.com/gphotosuploader/google-photos-api-client-go/v2"

Construct a new Google Photos client, then use the various services on the client to access different parts of the Google Photos API. For example:

    func main() error {
	    httpClient := http.DefaultClient
	    ctx := context.Background()

	    // httpClient is an authenticated http.Client. See Authentication below.
	    client, err := NewClient(httpClient)
	    if err != nil {
		    return err
	    }

	    // get or create a Photos Album with the specified name.
	    title := "my-album"
	    album, err := client.FindAlbum(ctx, title)
	    if err != nil {
		    if errors.Is(err, ErrAlbumNotFound) {
			   album, err = client.CreateAlbum(ctx, title)
			   if err != nil {
				   return err
			   }
		    } else {
			   return err
		    }
	    }

	    // upload an specified file to the previous album.
	    item := FileUploadItem("/my-folder/my-picture.jpg")
	    _, err = client.AddMediaToAlbum(ctx, item, album.Id)

	    return err
    }

Authentication The gphotos library does not directly handle authentication. Instead, when creating a new client, pass an http.Client that can handle authentication for you. The easiest and recommended way to do this is using the golang.org/x/oauth2 library, but you can always use any other library that provides an http.Client. Access to the API requires OAuth client credentials from a Google developers project. This project must have the Library API enabled as described in https://developers.google.com/photos/library/guides/get-started.

import "golang.org/x/oauth2"
func main() {
	ctx := context.Background()
	oc := oauth2Config := oauth2.Config{
		ClientID:     "... your application Client ID ...",
		ClientSecret: "... your application Client Secret ...",
		Endpoint:     photos.Endpoint,
		Scopes:       photos.Scopes,
	}
	tc := oc.Client(ctx, "... your user Oauth Token ...")
	client := gphotos.NewClient(tc)
}

Note that when using an authenticated Client, all calls made by the client will include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users. See the oauth2 docs for complete instructions on using that library.

Rate Limiting Google Photos imposes a rate limit on all API clients. The quota limit for requests to the Library API is 10,000 requests per project per day. The quota limit for requests to access media bytes (by loading a photo or video from a base URL) is 75,000 requests per project per day.

Photo storage and quality All media items uploaded to Google Photos using the API are stored in full resolution at original quality (https://support.google.com/photos/answer/6220791). They count toward the user’s storage.

Index

• Variables
• type Client
  • func NewClient(httpClient *http.Client, options ...Option) (*Client, error)
  • func (c *Client) AddMediaToAlbum(ctx context.Context, item UploadItem, albumID string) (*photoslibrary.MediaItem, error)
  • func (c *Client) AddMediaToLibrary(ctx context.Context, item UploadItem) (*photoslibrary.MediaItem, error)
  • func (c *Client) CreateAlbum(ctx context.Context, title string) (*photoslibrary.Album, error)
  • func (c *Client) FindAlbum(ctx context.Context, title string) (*photoslibrary.Album, error)
  • func (c *Client) ListAlbums(ctx context.Context) ([]*photoslibrary.Album, error)
  • func (c *Client) ListAlbumsWithCallback(ctx context.Context, callback ListAlbumsFunc) error
• type FileUploadItem
  • func (m FileUploadItem) Name() string
  • func (m FileUploadItem) Open() (io.ReadSeeker, int64, error)
  • func (m FileUploadItem) Size() int64
  • func (m FileUploadItem) String() string
• type ListAlbumsFunc
• type Option
  • func WithCacher(c cache.Cache) Option
  • func WithLogger(l log.Logger) Option
  • func WithPhotoService(s photoservice.Service) Option
  • func WithSessionStorer(s uploader.SessionStorer) Option
  • func WithUploader(u uploader.Uploader) Option
• type UploadItem

Variables

var (
	// ErrAlbumNotFound represents a failure to find the album.
	ErrAlbumNotFound = errors.New("album was not found")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for uploading a media. photoslibrary does not provide `/v1/uploads` API so we implement here.

func NewClient

func NewClient(httpClient *http.Client, options ...Option) (*Client, error)

NewClient constructs a new gphotos.Client from the provided HTTP client and the given options. The client is an HTTP client used for calling Google Photos. It needs the proper authentication in place.

Use WithLogger(), WithCacher(), WithUploader() to customize it.

func (*Client) AddMediaToAlbum

func (c *Client) AddMediaToAlbum(ctx context.Context, item UploadItem, albumID string) (*photoslibrary.MediaItem, error)

AddMediaToAlbum returns MediaItem created after uploading the item and adding it to an`albumID`.

func (*Client) AddMediaToLibrary

func (c *Client) AddMediaToLibrary(ctx context.Context, item UploadItem) (*photoslibrary.MediaItem, error)

AddMediaToAlbum returns MediaItem created after uploading the item to Google Photos library.

func (*Client) CreateAlbum

func (c *Client) CreateAlbum(ctx context.Context, title string) (*photoslibrary.Album, error)

CreateAlbum creates an Album in Google Photos library and returns the created object. If the Album was already on the library, it will return the Album. It's ensuring that Albums are unique (for this app) on Google Photos.

func (*Client) FindAlbum

func (c *Client) FindAlbum(ctx context.Context, title string) (*photoslibrary.Album, error)

FindAlbum search the Album with the specified title in Google Photos library and returns it. If the Album is not found, it will return ErrAlbumNotFound.

func (*Client) ListAlbums

func (c *Client) ListAlbums(ctx context.Context) ([]*photoslibrary.Album, error)

func (*Client) ListAlbumsWithCallback

func (c *Client) ListAlbumsWithCallback(ctx context.Context, callback ListAlbumsFunc) error

type FileUploadItem

type FileUploadItem string

FileUploadItem represents a local file.

func (FileUploadItem) Name

func (m FileUploadItem) Name() string

Name returns the filename.

func (FileUploadItem) Open

func (m FileUploadItem) Open() (io.ReadSeeker, int64, error)

Open returns a stream. Caller should close it finally.

func (FileUploadItem) Size

func (m FileUploadItem) Size() int64

func (FileUploadItem) String

func (m FileUploadItem) String() string

type ListAlbumsFunc

type ListAlbumsFunc func(albums []*photoslibrary.Album, stop func())

ListAlbumsFunc is called for each response of 50 albumGallery. If this calls stop, ListAlbums stops the loop.

type Option

type Option interface {
	Name() string
	Value() interface{}
}

func WithCacher

func WithCacher(c cache.Cache) Option

func WithLogger

func WithLogger(l log.Logger) Option

func WithPhotoService

func WithPhotoService(s photoservice.Service) Option

func WithSessionStorer

func WithSessionStorer(s uploader.SessionStorer) Option

func WithUploader

func WithUploader(u uploader.Uploader) Option

type UploadItem

type UploadItem interface {
	uploader.UploadItem
}

UploadItem represents an uploadable item.