Picasa Web Albums Data API

Picasa Web Albums Data API
- Developer's Guide
  - Java
  - .NET
  - PHP
  - Python
- Reference Guide
Google Data Protocol

Developer's Guide: The Protocol

Picasa Web Albums allows client applications to view and update albums, photos, and comments in the form of Google Data API feeds. Your client application can use the Picasa Web Albums Data API to create new albums, upload photos, add comments, edit or delete existing albums, photos, and comments, and query for items that match particular criteria.

Audience
Interacting with Picasa Web Albums: examples
1. Choose a feed type
2. Request a list of albums manually
3. Request a list of photos
4. If you're writing an installed (desktop) client:
  1. Add an album manually
5. If you're writing a web application client:
  1. Add an album manually
6. Post a new photo
7. Send a query
8. Update a photo
9. Delete a photo
10. Insert and delete tags and comments

Audience

This document is intended for programmers who want to write client applications that can interact with Picasa Web Albums.

This document assumes that you understand the general ideas behind the Google Data APIs protocol.

Interacting with Picasa Web Albums: examples

Assume you're creating a client application that needs to communicate with Picasa Web Albums. You want your client to be able to get the feed from an album and add a photo to that album. These examples show you how to do that.

To communicate with Picasa Web Albums, your application needs to be able to do the following, among other things:

Find a feed URL.
Request the feed. If you want to request a feed of albums, for example, you can request a list of albums manually, using the raw Google Data protocol.
Request other feeds as needed. For example, Request a list of photos.
Create a new album. There are two options here, depending on the kind of client you're writing:
- If you're writing an installed (desktop) client: Add an album manually
- If you're writing a web application client: Add an album manually
Post a new photo.
Send a query.
Update a photo.
Delete a photo.
Insert and delete tags and comments.

This guide focuses on operations involving albums and photos, but you can interact with Picasa Web Albums in a variety of other ways as well. For example, you can create, query, and delete albums, tags, and comments, and you can update albums and query users, all using the Google Data protocol.

Note: If you don't already have an account on Picasa Web Albums, you may want to create one for testing purposes.

Choose a feed type

You can request any of several different kinds of feeds from Picasa Web Albums; for more information, see Picasa Web Albums feed types, in the reference document.

For each feed, you can specify what kinds of entries should be returned, using the kind parameter in the URL.

Choose one of the following feed types:

Desired items	Feed type	URL	Valid kinds
Albums or tags associated with a given user	User-based	http://picasaweb.google.com/data/feed/api/user/userID?kind=kinds	album, tag
Photos or tags from a given album	Album-based (by name or ID)	By album name: http://picasaweb.google.com/data/feed/api/user/userID/album/albumName?kind=kinds	photo, tag
Photos or tags from a given album	Album-based (by name or ID)	By album ID: http://picasaweb.google.com/data/feed/api/user/userID/albumid/albumID?kind=kinds	photo, tag
Photos from a community search	Query-based	http://picasaweb.google.com/data/feed/projection/all?kind=kinds&q=searchTerm	photo
Comments or tags associated with a given photo	Photo-based	http://picasaweb.google.com/data/feed/api/user/userID/albumid/albumID/photoid/photoID?kind=kinds	comment, tag
Information on a user's list of contacts (favorite users)	Contacts-based	http://picasaweb.google.com/data/feed/api/user/userID/contacts?kind=kinds	user

To specify which kind or kinds of items you want, you list one or more kinds in the kind query parameter. The kind listed in boldface in the "Valid kinds" column is the default kind for that feed type; if you want the default kind, you can leave out the kind query parameter. In that case, only entries of the default kind will be returned.

Request a list of albums manually

The general idea of how to request a Picasa Web Albums feed is that you determine the feed URL, and then you send an HTTP GET request to that URL. Picasa Web Albums then returns a Google Data feed containing entries of whatever sort you specified in the kind URL parameter. If you don't include a kind parameter, the default kind depends on the feed you requested; for more information, see Kind values in the reference document.

Google provides client libraries for interacting with Google Data API services in a variety of programming languages. If you're using a UNIX system and you want to try this out without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

To get a feed listing all of the albums belonging to user "liz", you send an HTTP request like the following to Picasa Web Albums:

GET http://picasaweb.google.com/data/feed/api/user/liz?kind=album

After you send the GET request, Picasa Web Albums may return a redirect, depending on various factors. If so, send another GET request to the redirect URL.

Picasa Web Albums then returns an HTTP 200 OK status code and a feed containing all the albums for the user. If there's only one entry, then Picasa Web Albums returns something similar to the following feed.

We've slightly edited the following example to make it a little more readable by humans; in particular, a real Picasa Web Albums feed contains actual IDs and URLs.

<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:gphoto='http://schemas.google.com/photos/2007'>
  <id>http://picasaweb.google.com/data/feed/api/user/liz</id>
  <updated>2007-03-06T00:08:51.553Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/photos/2007#user'></category>
  <title type='text'>liz</title>
  <subtitle type='text'></subtitle>
  <icon>http://lh4.google.com/liz/imageKey/s64-c/liz.jpg</icon>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://picasaweb.google.com/data/feed/api/user/liz'>
  </link>
  <link rel='alternate' type='text/html'
    href='http://picasaweb.google.com/liz'></link>
  <link rel='self' type='application/atom+xml'
    href='http://picasaweb.google.com/data/feed/api/user/liz?start-index=1&amp;max-results=10000&amp;kind=album'>
  </link>
  <author>
    <name>Liz</name>
    <uri>http://picasaweb.google.com/liz</uri>
  </author>
  <generator version='1.00' uri='http://picasaweb.google.com/'>Picasaweb</generator>
  <gphoto:user>liz</gphoto:user>
  <gphoto:nickname>Liz</gphoto:nickname>
  <gphoto:thumbnail>http://lh4.google.com/liz/imageKey/s64-c/liz.jpg</gphoto:thumbnail>
  <entry>
    <id>http://picasaweb.google.com/data/entry/api/user/liz/albumid/albumID</id>
    <published>2007-03-01T08:00:00.000Z</published>
    <updated>2007-03-02T02:09:52.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://schemas.google.com/photos/2007#album'></category>
    <title type='text'>Netherfield Park</title>
    <summary type='text'>Photos of my vacation.</summary>
    <rights type='text'>public</rights>
    <link rel='self' type='application/atom+xml'
      href='http://picasaweb.google.com/data/entry/api/user/liz/albumid/albumID'>
    </link>
    <link rel='http://schemas.google.com/g/2005#feed'
      type='application/atom+xml'
      href='http://picasaweb.google.com/data/feed/api/user/liz/albumid/albumID'>
    </link>
    <link rel='alternate' type='text/html'
      href='http://picasaweb.google.com/liz/NetherfieldPark'></link>
    <author>
      <name>Liz</name>
      <uri>http://picasaweb.google.com/liz</uri>
    </author>
    <gphoto:id>albumID</gphoto:id>
    <gphoto:name>NetherfieldPark</gphoto:name>
    <gphoto:location></gphoto:location>
    <gphoto:access>public</gphoto:access>
    <gphoto:timestamp>1172736000000</gphoto:timestamp>
    <gphoto:numphotos>184</gphoto:numphotos>
    <gphoto:numphotosremaining>316</gphoto:numphotosremaining>
    <gphoto:bytesUsed>11060624</gphoto:bytesUsed>
    <gphoto:user>liz</gphoto:user>
    <gphoto:nickname>Liz</gphoto:nickname>
    <gphoto:commentingEnabled>true</gphoto:commentingEnabled>
    <gphoto:commentCount>0</gphoto:commentCount>
    <media:group>
      <media:title type='plain'>Netherfield Park</media:title>
      <media:description type='plain'>Photographs taken on vacation.</media:description>
      <media:keywords></media:keywords>
      <media:content
        url='http://lh3.google.com/liz/RyJe2JbVKRE/AAAAAAAAATc/XcBfqsmmyOs/Netherfield.jpg'
        type='image/jpeg' medium='image'>
      </media:content>
      <media:thumbnail
        url='http://lh3.google.com/liz/RyJe2JbVKRE/AAAAAAAAATc/XcBfqsmmyOs/s160-c/Netherfield.jpg'
        height='160' width='160'>
      </media:thumbnail>
      <media:credit>Liz</media:credit>
    </media:group>
  </entry>
</feed>

For information about what each of those elements means, see the Picasa Web Albums Reference document, the Google Data APIs Protocol Reference document, or the Atom 1.0 specification.

If your request fails for some reason, Picasa Web Albums may return a different status code; for information about the status codes, see the Google Data APIs protocol reference document.

Request a list of photos

You can request any of the other available feeds in much the same way.

For example, to get a feed listing all of the photos in an album named "NetherfieldPark", belonging to user "liz", you send an HTTP request like the following to Picasa Web Albums:

GET http://picasaweb.google.com/data/feed/api/user/liz/album/NetherfieldPark?kind=photo

In this example, we're using the album-by-name URI instead of the album-by-ID URI. In some cases your client may already have the album name; in others, to request an album by name you may have to construct the album-by-name URI using the value of the <gphoto:name> element in the list-of-albums feed from the previous example. If you prefer to request a feed by album ID, you can use the URI given in the <link rel='http://schemas.google.com/g/2005#feed'> element in the list-of-albums feed.

Note: The entries in a feed are ordered based upon the display order on the web site.

In addition to requesting a list of photos for a particular album, you can also request a list of photos recently uploaded by a user. This type of feed is retrieved using a different URL, but the format of the feed is the same. The following URL will retrieve a feed containing the most recent 100 photos uploaded by liz. Photos contained in 'unlisted' albums will not appear in this feed unless you are authenticated as the appropriate user.

GET http://picasaweb.google.com/data/feed/api/user/liz?kind=photo&max-results=100

Add an album manually (desktop client version)

Most Google Data operations require authentication. Google Data uses two different authentication systems, depending on what kind of client you're writing. If your client is a standalone single-user "installed" client (such as a desktop application), then you should use the "ClientLogin" system; if your client is a multi-user web application client, then you should use the "AuthSub" system. (For more information about authentication, see the Google Account Authentication documentation.)

Because the two systems are so different, this document covers them in separate sections. Therefore, if your client is an installed application, read this section. If your client is a web app, skip this section and read Add an album manually (web client version) instead.

Adding an album is a little bit more complicated than getting a feed, because you need to create the XML code or client-library object representing the new album, and because authentication is required.

Here's what you do at the protocol level:

First, create an album. For example, you might create the following XML code:

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:gphoto='http://schemas.google.com/photos/2007'>
  <title type='text'>Trip To Italy</title>
  <summary type='text'>This was the recent trip I took to Italy.</summary>
  <gphoto:location>Italy</gphoto:location>
  <gphoto:access>public</gphoto:access>
  <gphoto:commentingEnabled>true</gphoto:commentingEnabled>
  <gphoto:timestamp>1152255600000</gphoto:timestamp>
  <media:group>
    <media:keywords>italy, vacation</media:keywords>
  </media:group>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/photos/2007#album'></category>
</entry>

Then authenticate the user. To do that, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

Include the relevant parameters in the body of the POST request, as described in the ClientLogin documentation. Use lh2 as the service name.

If the request succeeds, then the response contains an alphanumeric string labeled Auth.

After a successful authentication request, use the Auth value to create an Authorization header for a new POST request:

Authorization: GoogleLogin auth=yourAuthValue

In the body of the new POST request, place the Atom <entry> element you created above, using the application/atom+xml content type.

Now send the POST request to the appropriate Picasa Web Albums URL:

http://picasaweb.google.com/data/feed/api/user/userID

Picasa Web Albums creates a new album using the data you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new album in the form of an <entry> element. The returned entry is similar to the one you sent, but the returned one contains various elements added by Picasa Web Albums, such as an <id> element.

If your request fails for some reason, then Picasa Web Albums may return a different status code; for information about the status codes, see the HTTP status codes section of the Google Data APIs protocol reference document.

Add an album manually (web client version)

This section is for use only with a multi-user web application client. If your client is an installed application, then skip this section and read Add an album manually (desktop client version) instead.

Adding an album is a little bit more complicated than getting a feed, because you need to create the XML code or client-library object representing the album, and authentication is required.

Here's what you do at the protocol level:

First, create an album. For example, you might create the following XML code:

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:gphoto='http://schemas.google.com/photos/2007'>
  <title type='text'>Trip To Italy</title>
  <summary type='text'>This was the recent trip I took to Italy.</summary>
  <gphoto:location>Italy</gphoto:location>
  <gphoto:access>public</gphoto:access>
  <gphoto:commentingEnabled>true</gphoto:commentingEnabled>
  <gphoto:timestamp>1152255600000</gphoto:timestamp>
  <media:group>
    <media:keywords>italy, vacation</media:keywords>
  </media:group>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/photos/2007#album'></category>
</entry>

Then authenticate the user, using the AuthSub authentication system.

To acquire an AuthSub token for a given Picasa Web Albums user, your application must redirect the user to the AuthSubRequest URL, which prompts them to log into their Google account.

After the user logs in, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. Your application then uses that authentication token in subsequent interactions with Picasa Web Albums.

For details, including information on registering your application with Google and on exchanging a one-time token for a session token, see the AuthSub documentation.

Use the authentication token to create an Authorization header for a new POST request:

Authorization: AuthSub token="yourAuthToken"

Note that the values in the Authorization header for AuthSub should be surrounded by quotation marks.

In the body of the new POST request, place the Atom <entry> element you created above, using the application/atom+xml content type.

Now send the POST request to the appropriate Picasa Web Albums URL:

http://picasaweb.google.com/data/feed/api/user/userID

Picasa Web Albums creates a new album using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new album in the form of an <entry> element. The returned entry is similar to the one you sent, but the returned one contains various elements added by Picasa Web Albums, such as an <id> element.

Post a new photo

There are two ways to add a photo to an album using the data API:

Upload the binary image data along with its metadata. To do this, use MIME content type "multipart/related"; send photo metadata in one part of the POST body, and binary-encoded image data in another part. This is the preferred approach.
Upload the binary image data without the metadata.

While all photos appearing on the Picasa Web Albums site are in the JPEG format, photos of any of the following types can be uploaded using the API:

image/bmp
image/gif
image/jpeg
image/png

Post a photo with metadata

To send metadata along with the photo, post to the following URL:

POST http://picasaweb.google.com/data/feed/api/user/liz/album/NetherfieldPark

And use the following format for the body of the POST:

Content-Type: multipart/related; boundary="END_OF_PART"
Content-Length: 24680246
MIME-version: 1.0

Media multipart posting
--END_OF_PART
Content-Type: application/atom+xml

<entry xmlns='http://www.w3.org/2005/Atom'>
  <title>darcy-beach.jpg</title>
  <summary>Darcy on the beach</summary>
  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://schemas.google.com/photos/2007#photo"/>
</entry>
--END_OF_PART
Content-Type: image/jpeg

...binary image data goes here...
--END_OF_PART--

Note that the <title> element contains the filename you want to use for the image.

Post a photo without metadata

To send a photo without its associated metadata, post to the following URL:

POST http://picasaweb.google.com/data/feed/api/user/liz/album/NetherfieldPark

And use the following format for the body of the POST:

Content-Type: image/jpeg
Content-Length: 47899
Slug: darcy-beach.jpg

...binary image data goes here...

The optional Slug: HTTP header specifies a filename for Picasa Web Albums to use for the photo. Not specifying a Slug: causes the server to use a default title for the image.

Note: If you want to post a photo, but don't want the hassle of requiring the user of your app to choose an album, you can post the photo to the 'Drop Box.' This special album will automatically be created the first time it is used to store a photo. To post to the 'Drop Box,' use a an albumid value of 'default': http://picasaweb.google.com/data/feed/api/user/default/albumid/default.

Send a query

Google Data lets you specify various query parameters, such as a limit on the number of entries returned. For more information about the query parameters for Picasa Web Albums queries, see the Reference document. Picasa Web Albums supports the standard Google Data start-index and max-results parameters. It does not currently support the other standard parameters.

Queries can be sent either authenticated or unauthenticated. Unauthenticated queries return only public information; authenticated queries return any data the authenticated user has access to.

To request a feed with a limit on number of entries returned, send an HTTP request like the following to Picasa Web Albums, using the feed URL:

GET http://picasaweb.google.com/data/feed/api/user/liz?kind=album&max-results=10

When you send that GET request, Picasa Web Albums returns an HTTP 200 OK status code and a feed containing up to ten albums.

Update a photo

You can replace the metadata and/or the binary image data for a photo.

Update a photo and its metadata

To replace both the binary data and metadata for the photo that you inserted earlier, use an HTTP request like the following:

PUT http://picasaweb.google.com/data/media/api/user/liz/albumid/albumID/photoid/photoID/versionNumber

The URI is the value of the <link rel="edit-media"> tag that was returned after you did the earlier POST. Note that if you try to update using a version number other than the latest one, you may receive an error; for more information, see Optimistic concurrency (versioning) in the Google Data reference document.

In the body of the PUT, include the updated metadata and image data, in the same multipart format that you used to do the POST with metadata.

Note: As usual with Google Data, you can't do a partial update of an entry; you have to send the full entry data to replace the existing data. The exception is that you can choose to send only the metadata or only the image, as described in the following sections.

You can update any or all of the following metadata properties:

<title>
<description>
<gphoto:checksum>
<gphoto:client>
<gphoto:rotation>
<gphoto:timestamp>
<gphoto:commentingEnabled>

Update only the photo

To replace only the photo's binary data, use the following HTTP request:

PUT http://picasaweb.google.com/data/media/api/user/liz/albumid/albumID/photoid/photoID/versionNumber

In the body of the PUT, include the replacement image data, in the same format that you used to do the POST without metadata.

Update only the metadata

To replace only the photo's metadata (and not the image itself), you follow the steps that you would follow to send an update to a non-media feed.

In particular, send the following HTTP request:

PUT http://picasaweb.google.com/data/entry/api/user/liz/albumid/albumID/photoid/photoID/versionNumber

The URI is the value of the <link rel="edit"> tag that was returned after you did the earlier POST. Note that if you try to update using a version number other than the latest one, you may receive an error; for more information, see Optimistic concurrency (versioning) in the Google Data reference document.

In the body of the PUT, provide the updated metadata, in the form of an <atom:entry> element containing image metadata.

Note: As usual with GData, you can't do a partial update of an entry; you have to send the full entry metadata to replace the existing metadata.

The photo itself is not re-sent to the server.

Delete a photo

To delete a photo and its metadata, send an HTTP DELETE request to either the edit link or the edit-media link. In both cases, the photo and metadata are deleted.

For example, to delete the photo from the previous examples:

DELETE http://picasaweb.google.com/data/entry/api/user/liz/albumid/albumID/photoid/photoID/versionNumber

As with updating, if you try to delete using a version number other than the latest one, you may receive an error; for more information, see Optimistic concurrency (versioning) in the Google Data reference document.

Insert and delete tags and comments

In addition to albums and photos, the Picasa Web Albums Data API lets you interact with two other kinds of data: tags and comments. You can't update tags or comments, but you can insert and delete them.

The process is similar to the process for inserting and deleting albums.

For example, to manually add a tag to a photo, first you create the XML code for the tag, including a <category> element indicating that it's a tag:

<entry xmlns='http://www.w3.org/2005/Atom'>
  <title>AtTheBeach</title>
  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://schemas.google.com/photos/2007#tag"/>
</entry>

Then you send the tag as the body of an authenticated POST request to the photo's POST URI:

POST http://picasaweb.google.com/data/feed/api/user/userID/album/albumName/photoid/photoID

You can also use the albumID instead of the albumName: http://picasaweb.google.com/data/feed/api/user/userID/albumid/albumID/photoid/photoID

To manually add a comment, you follow the same process (using the same POST URI), but use a <content> element for the comment's text, and use a slightly different <category> element to indicate that it's a comment:

<entry xmlns='http://www.w3.org/2005/Atom'>
  <content>This is what all the gentlemen are wearing this season.</content>
  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://schemas.google.com/photos/2007#comment"/>
</entry>

To delete a tag or comment, send an HTTP DELETE request to the tag's or comment's edit URI.


e.g. "ajax apis" or "open source"

Picasa Web Albums Data API