This API is being deprecated and will be turned down in January 2019. Migrate to Google Photos Library API as soon as possible to avoid disruptions to your application.

Migration Guide to Google Photos Library API

Using the Google Photos Library API your app can read, write, and share photos and videos in Google Photos.

The Google Photos Library API is the recommended way to interact with a user's Google Photos library. This document outlines some of the key concepts and considerations when moving your application to the Google Photos Library API.

Library API overview

The Library API is a RESTful API with JSON Payload. The structure of the API is based on the product concepts of Google Photos:

  • Library: media stored in the user's Google Photos account.
  • Albums: media collections which can be shared with other users.
  • Media items: photos, videos, and their metadata.
  • Sharing: feature that enables users to share their media with other users.

Once you are getting ready to grow your application to deliver a consistent and premium experience to your users, you can express interest in the Google Photos partner program. Also see the UX guidelines, API limits and quotas, and the acceptable use policy.

Migration benefits

Compared to the Picasa Web Albums Data API, the Google Photos Library API provides:

  • Integration with Google Photos
  • Modern JSON-based API
  • Support for sharing, including shared albums

Migration limitations

Note that some features of the Picasa Web Albums Data API are not available in the Google Photos Library API.

The following are not supported:

  • Content from other sources, such as Blogger or Google Hangouts. The Google Photos Library API only provides access to Google Photos
  • ETags and If-None-Match headers
  • Location data
  • Access to public data. Once authorized, you can only access a user's Google Photos library, albums, or shared albums
  • Server-to-server requests made through service accounts or anonymous requests. All requests must be authorized by a Google Photos user

Authentication and authorization

Similar to Picasa Web Albums Data API, requests to the Google Photos Library API are also authorized using OAuth 2.0. But note that service accounts or anonymous requests to public data without authorization are not supported in the Library API. All requests must be made on behalf of an authenticated user.

OAuth 2.0 scopes

The Google Photos Library API supports various types of OAuth 2.0 authentication and authorization scopes.

You should always request the most restrictive scope. For example, the scope https://www.googleapis.com/auth/photoslibrary.readonly only grants read access to the library and albums, but not write access.

Visibility and ownership

When making requests, you don't need to specify a userId or use default. This is because all requests are made on behalf of the authenticated user and interact with the user's Google Photos account. It is similar to the private visibility in Picasa Web Albums Data API. The Google Photos Library API does not support public or unauthenticated requests.

Your application can list albums shared on Google Photos with other Google Photos users. This is somewhat similar to the visible visibility in Picasa Web Albums Data API for authenticated users, but only applies to shares within Google Photos.

Using the API

The Picasa Web Albums Data API is SOAP XML-based, while the Google Photos Library API is RESTful with JSON responses.

Albums

You can request a list of albums or request the contents of a specific album. You can also list the albums that have been shared by the user.

In contrast to the Picasa Web Albums Data API, there is no need to specify access visibility, as you are always acting on behalf of an authenticated user.

Note: Identifiers for albums are not compatible across the APIs. That is, an album ID retrieved from the Picasa Web Albums Data API cannot be used with the Google Photos Library API.

Accessing media

The Google Photos Library API supports many different types of media, including photos and videos.

These entries in the Google Photos library are called media items and can be listed from the user's Google Photos library, albums, or from a search.

Similar to a feed entry object in the Picasa Web Albums Data API, each media item object describes an element of the user's library and is identified by a stable and unique identifier.

Note: Identifiers for media items are not compatible. That is, a gphoto:id retrieved from the Picasa Web Albums Data API cannot be used as a mediaItem Id in the Google Photos Library API.

The mediaMetadatacontains properties of the item, for example their size, creation time, and other values extracted from their EXIF properties.

Some properties returned by the Google Photos Library API may differ in their format and representation. Not all properties that are part of the Picasa Web Albums Data API are included in a response from the Google Photos Library API. For example, the edited time, username, filename, or checksum, are not included.

Some properties have different names. For example, the Google Photos Library API returns descriptionthe user has set in Google Photos, not a summary. See the section below for examples.

Accessing images

Another significant difference is the way in which the APIs return URLs to the image bytes.

In Picasa Web Albums Data API, the response for a photo contains multiple thumbnail entries that point to the image in different sizes, included as a media:group. However, the Google Photos Library API returns only one base URLwhich you can use to access the video bytes or access an image at different sizes. This is done by appending parameters to this base URL.

A media item also contains a URL to open the media item in the Google Photos app. This can be useful when handling different media formats that are not supported in your application.

Accessing Videos

The Google Photos Library API does not provide videos in different streaming formats or resolutions. To access a video file, follow the access media items guide for video base urls.

Search

The Google Photos Library API supports searching a user's library based on filters that describe media items, including the content of image, their creation date, and type of media.

Posting a new photo or video

In contrast to the Picasa Web Albums Data API, the upload process in the Google Photos Library API consists of two separate requests.

In the first request, upload the bytes. You can specify an optional filename in this request. Next, create a media itemin the user's Google Photos library. Here you can also specify an optional description and add the item to an album.

The suggested file size for images is less than 50 MB.

Examples

Listing albums

Here is a simplified example that compares how you list albums owned by a user in the Picasa Web Albums Data API and the Google Photos Library API. To illustrate the similarities in the responses, some properties have been omitted for simplicity.

In the Picasa Web Albums Data API, make a GET request to https://picasaweb.google.com/data/feed/api/user/userID with the ID of the user or use the default keyword.

This returns the following response:

<feed>
  <title>ALBUM_TITLE</title>
  <link rel='alternate' type='text/html' href='ALBUM_PRODUCT_URL' />
  <gphoto:id>ALBUM_ID</gphoto:id>
  <gphoto:thumbnail>THUMBNAIL_URL</gphoto:thumbnail>
  <openSearch:totalResults>NUMBER_OF_ITEMS_IN_ALBUM</openSearch:totalResults>
  <openSearch:startIndex>ITEM_INDEX</openSearch:startIndex>
  ...
  <entry>
    ...
  </entry>
</feed>

In the Google Photos Library API, make a GET request to https://photoslibrary.googleapis.com/v1/albums. This returns the following response:

{
  "albums": [
    {
      "id": "ALBUM_ID",
      "title": "ALBUM_TITLE",
      "productUrl": "ALBUM_PRODUCT_URL",
      "coverPhotoBaseUrl" "ALBUM_COVER_BASE_URL-DO_NOT_USE_DIRECTLY",
      "isWriteable": "WHETHER_YOU_CAN_WRITE_TO_THIS_ALBUM",
      "totalMediaItems": "NUMBER_OF_ITEMS_IN_ALBUM"
    },
    ...
  ],
  "nextPageToken": "TOKEN_FOR_PAGINATION"
}

The Picasa Web Albums Data API does not include a property similar to isWriteable to indicate whether the album can be modified. For pagination, the Picasa Web Albums Data API uses the openSearch:startIndexproperty to list albums based on an index, whereas the Library API uses page tokens returned in nextPageToken.

In the Library API, raw media bytes are accessed using base URLs, where you can specify a size or other processing options. The Picasa Web Albums Data API returns URLs that can be loaded directly. See the section on accessing images on how to access the image bytes to load the image or thumbnails.

Listing album contents

Here is a simplified example that shows how to list the contents of an album.

In the Picasa Web Albums Data API, make a GET request to https://picasaweb.google.com/data/feed/api/user/userID/albumid/albumID, specifying the id of a user (or default) and the id of the album.

This returns the following response for an image, where each item in the album is returned as an entryobject:

<feed>
  <title>ALBUM_TITLE</title>
  <link rel='alternate' type='text/html' href='ALBUM_PRODUCT_URL' />
  <gphoto:id>ALBUM_ID</gphoto:id>
  <gphoto:thumbnail>THUMBNAIL_URL</gphoto:thumbnail>
  <openSearch:totalResults>NUMBER_OF_ITEMS_IN_ALBUM</openSearch:totalResults>
  <openSearch:startIndex>ITEM_INDEX</openSearch:startIndex>
  ...
  <entry>
    <id>ITEM_ID</id>
    <summary type='text'>ITEM_DESCRIPTION</summary>
    <updated>ITEM_UPDATED_TIMESTAMP</updated>
    <title>ITEM_TITLE</title>
    <link rel='alternate' type='text/html'  href='ITEM_PRODUCT_URL' />
    <gphoto:id>ITEM_ID</gphoto:id>
    <gphoto:width>IMAGE_WIDTH</gphoto:width>
    <gphoto:height>IMAGE_HEIGHT</gphoto:height>
    <media:group>
      <media:content url='IMAGE_URL'
        height='IMAGE_HEIGHT' width='IMAGE_WIDTH'
        type='IMAGE_MIMETYPE' medium='image' />
      <media:thumbnail url='IMAGE_THUMBNAIL_URL'
        height='IMAGE_THUMBNAIL_HEIGHT' width='IMAGE_THUMBNAIL_WIDTH' />
      ...
    </media:group>
    ...
  </entry>
  ...
</feed>

In the Library API, make a POST request to https://photoslibrary.googleapis.com/v1/mediaItems:search, specifying the id of the album in the body:

{
  "pageSize":"PAGE_SIZE",
  "albumId": "ALBUM_ID"
}

This returns the following response for an image, where each item in the album is returned in a list of mediaItems:

{
  "mediaItems": [
    {
      "id": "ITEM_ID",
      "description": "ITEM_DESCRIPTION",
      "productUrl": "ITEM_PRODUCT_URL'",
      "baseUrl": "ITEM_BASE_URL-DO_NOT_USE_DIRECTLY",
      "mimeType": "'IMAGE_MIMETYPE'",
      "mediaMetadata": {
        "height": "IMAGE_HEIGHT"
        "width": "IMAGE_WIDTH",
        "creationTime": "ITEM_CREATED_TIMESTAMP",
        "photo": { ... }
      }
    },
    ...
  ],
  "nextPageToken": "TOKEN_FOR_PAGINATION"
}

In the Library API, an item only has a description, not the title and summary. Some metadata is exposed in the response as well, such as the original size, creation time and other EXIF data.

See the section on accessing images on how to access the image bytes to load the image or thumbnails.

Back to top