Picasa Web Albums Data API

Developer's Guide: PHP

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.

In addition to providing some background on the capabilities of the Picasa Web Albums Data API, this guide provides examples for interacting with the API using the PHP client library. If you're interested in understanding more about the underlying protocol used by the PHP client library to interact with the Picasa Web Albums API, please see the protocol guide.

Contents

Audience

This document is intended for programmers who want to write client applications using the Google Data PHP client library that can interact with Picasa Web Albums.

Getting Started

Picasa Web Albums uses Google Accounts for authentication, so if you have a Google account you are all set. Otherwise, you can create a new account.

To use the PHP client library, you'll need PHP 5.14+. Please see the Getting Started Guide for more information on downloading, installing and configuring the PHP client library.

To run the examples in this document into your own code, you'll need the following statements:

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_Photos');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_AuthSub');

The Zend_Gdata_Photos class represents a client connection to the Picasa Web Albums service. The general procedure for sending a query to a service using the client library consists of the following steps:

  1. If you're sending data to a service (for example, if you're inserting a new entry), then transform the raw data into objects using the client library classes. (This step doesn't apply if you are merely retrieving data.)
  2. Create an authenticated Zend_Http_Client instance using either Zend_Gdata_ClientLogin or Zend_Gdata_AuthSub
  3. Create a new Zend_Gdata_Photos instance, passing the authenticated client object
  4. Call a method to send the request and receive any results.

Authentication

The PHP client library can be used to work with either public or private feeds. Public feeds are read-only, but do not require any authentication. Private feeds require that you authenticate to the Picasa Web Albums servers. This can be done via ClientLogin username/password authentication or AuthSub proxy authentication.

Please see the Google Data APIs authentication documentation for more information on AuthSub and ClientLogin.

Single-user "installed" client authentication

To use ClientLogin (also called "Authentication for Installed Applications"), call Zend_Gdata_ClientLogin::getHttpClient(), specifying the e-mail address and password of the user on whose behalf your client is sending the query. For example:

$serviceName = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
$user = "sample.user@gmail.com";
$pass = "pa$$w0rd";

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $serviceName);

// update the second argument to be CompanyName-ProductName-Version
$gp = new Zend_Gdata_Photos($client, "Google-DevelopersGuide-1.0");

// In version 1.5+, you can enable a debug logging mode to see the
// underlying HTTP requests being made, as long as you're not using
// a proxy server
// $gp->enableRequestDebugLogging('/tmp/gp_requests.log');

Once the credentials have been set, they will be used to authenticate each request made using the $gp object.

For more information about Google's authentication systems, see the Google Account Authentication documentation.

Multiple-user web application client authentication

AuthSub proxy authentication is used by web applications which need to authenticate their users to Google accounts. The operator does not need access to the e-mail address and password for the user - only special AuthSub tokens are required.

When the user first visits your application, they have not yet been authenticated. In this case, you need to print some text and and a link directing the user to Google to authenticate your request for access to their photos. The PHP Google Data APIs client library provides a function to generate this URL. The code below sets up a link to the AuthSubRequest page.

function getAuthSubUrl()
{
    // the $next variable should represent the URL of the PHP script 
    // an example implementation for getCurrentUrl is in the sample code
    $next = getCurrentUrl(); 
    $scope = 'https://picasaweb.google.com/data';
    $secure = false;
    $session = true;
    return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure,
        $session);
}

Notice the parameters sent to the getAuthSubUrl function:

  • next, the URL of the page that Google should redirect the user to after authentication.
  • scope, indicating that the application is requesting access to the feed.
  • secure, indicating that the token returned will not be a secure token.
  • session, indicating this token can be exchanged for a multi-use (session) token.

The URL looks something like this:

https://www.google.com/accounts/AuthSubRequest?scope=https%3A%2F%2Fpicasaweb.google.com%2Fdata&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.php

The user can then follow the link to Google's site and authenticate to their Google account.

After the user authenticates, they will be redirected back to the next URL. The URL will have a single-use token value appended to it as a query parameter. The URL looks something like this:

http://www.example.com/welcome.php?token=14a87fe98219731acd516

Upgrading to a session token

For security, this token is single-use only, so now you need to exchange this single-use token for a session token. This process is described in the AuthSub documentation. The following code snippet shows how to upgrade the token.

session_start();

function getAuthSubHttpClient()
{
    if (!isset($_SESSION['sessionToken']) && !isset($_GET['token']) ){
        echo '<a href="' . getAuthSubUrl() . '">Login!</a>';
        exit;
    } else if (!isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
        $_SESSION['sessionToken'] =
            Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
    }
    $client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);
    return $client;
}

// update the second argument to be CompanyName-ProductName-Version
$gp = new Zend_Gdata_Photos(getAuthSubHttpClient(), "Google-DevelopersGuide-1.0");

// In version 1.5+, you can enable a debug logging mode to see the
// underlying HTTP requests being made, as long as you're not using
// a proxy server
// $gp->enableRequestDebugLogging('/tmp/gp_requests.log');

In this snippet, the token element in the session contains the value from the token query parameter in the URL.

This token value represents a single-use AuthSub token. This token is only eligible for upgrade if $session = true was specified in the getAuthSubUrl method above. The token is upgraded to an AuthSub session token using the getAuthSubSessionToken method, which calls the AuthSubSessionToken service.

Working with Albums

Albums are the way Picasa Web Albums groups photos into useful sets. These albums can be public or unlisted, and have their own properties such as a geographic location, a description, or a date.

You do not have to authenticate to retrieve data about public albums, but in order to create, update, or delete content you must authenticate using one of the methods discussed in the authentication section.

Request a list of albums

You can retrieve all of a user's albums by using the Zend_Gdata_Photos::getUserFeed method.

The string "default" can be used in place of a real username, in which case the server will use the username of the user credentials used to authenticate the request.

$serviceName = Zend_Gdata_Photos::AUTH_SERVICE_NAME;
$client = Zend_Gdata_ClientLogin::getHttpClient($username, $pass, $serviceName);

// update the second argument to be CompanyName-ProductName-Version
$gp = new Zend_Gdata_Photos($client, "Google-DevelopersGuide-1.0");

try {
    $userFeed = $gp->getUserFeed("default");
    foreach ($userFeed as $userEntry) {
        echo $userEntry->title->text . "<br />\n";
    }
} catch (Zend_Gdata_App_HttpException $e) {
    echo "Error: " . $e->getMessage() . "<br />\n";
    if ($e->getResponse() != null) {
        echo "Body: <br />\n" . $e->getResponse()->getBody() . 
             "<br />\n"; 
    }
    // In new versions of Zend Framework, you also have the option
    // to print out the request that was made.  As the request
    // includes Auth credentials, it's not advised to print out
    // this data unless doing debugging
    // echo "Request: <br />\n" . $e->getRequest() . "<br />\n";
} catch (Zend_Gdata_App_Exception $e) {
    echo "Error: " . $e->getMessage() . "<br />\n"; 
}

The above code retrieves all of the user's albums and prints out a list of the titles.

Add an album

Albums can also be created using the API. If you want to create a new album for $username, then you can use the following:

$entry = new Zend_Gdata_Photos_AlbumEntry();
$entry->setTitle($gp->newTitle("New album"));
$entry->setSummary($gp->newSummary("This is an album."));

$createdEntry = $gp->insertAlbumEntry($entry);

This code will create a new album named "New album" with the description of "This is an album." If you want to set the location of the album, see the Update a photo section, as setting the location on album entry is done using the same setGeoRssWhere method as is used for setting the location on a photo.

Modify the properties of an album

Once an entry is retrieved, it can be easily modified using the save method.

$createdEntry->title->text = "Updated album title";
$updatedEntry = $createdEntry->save();

Delete an album

Retrieved entries can also be deleted using the AlbumEntry::delete method.

$updatedEntry->delete();

Working with Photos

When uploading, modifying, or deleting photos, you will have to authenticate using one of the methods discussed in the Authentication section.

Request a list of photos

There are different ways to retrieve photos. The most common is to get a list of all of the photos in an album, but you can also retrieve recent photos from a user, or search photos from the public albums of other users.

List photos in album

This is the basic query to retrieve all of the photos belonging to the authenticated user in the sample.albumname album. The title of each photo is then printed out to the console.

As in this example, the string "default" can be used in place of a real username, in which case the server will use the username of the user credentials used to authenticate the request.

// Creates a Zend_Gdata_Photos_AlbumQuery
$query = $gp->newAlbumQuery();

$query->setUser("default");
$query->setAlbumName("sample.albumname");

$albumFeed = $gp->getAlbumFeed($query);
foreach ($albumFeed as $albumEntry) {
    echo $albumEntry->title->text . "<br />\n";
}

List photos recently uploaded

It is also possible to retrieve the photos associated with a user, but without specifying any particular album. The following example retrieves the last 10 photos uploaded by username and prints their titles.

Although we're looking for a list of photos, we use the UserQuery class, because we're trying to retrieve the list of photos for a particular user. Alternatively, in the example above, we're trying to retrieve a list of photos in an album, so we use the AlbumQuery class.

// Creates a Zend_Gdata_Photos_UserQuery
$query = $gp->newUserQuery();

// indicate the user's feed to retrieve
$query->setUser("default");

// set to only return photos
// the default kind value for a user feed is to include only albums
$query->setKind("photo");

$query->setMaxResults("10");

try {
    // we're passing null for the username, as we want to send
    // additional query parameters generated by the UserQuery class
    $userFeed = $gp->getUserFeed(null, $query);

    // because we specified 'photo' for the kind, only PhotoEntry objects 
    // will be contained in the UserFeed
    foreach ($userFeed as $photoEntry) {
        echo $photoEntry->title->text . "<br />\n";
    }
} catch (Zend_Gdata_App_HttpException $e) {
    echo "Error: " . $e->getMessage() . "<br >\n";
    if ($e->getResponse() != null) {
        echo "Body: <br />\n" . $e->getResponse()->getBody() . 
             "<br />\n"; 
    }
    // In new versions of Zend Framework, you also have the option
    // to print out the request that was made.  As the request
    // includes Auth credentials, it's not advised to print out
    // this data unless doing debugging
    // echo "Request: <br />\n" . $e->getRequest() . "<br />\n";
} catch (Zend_Gdata_App_Exception $e) {
    echo "Error: " . $e->getMessage() . "<br />\n"; 
}

List photos by community search

With the API, you can search photos uploaded by other users, as long as they are in a public album. The following code retrieves 10 photos matching a search for "goldendoodle" and prints out their titles.

// Community search queries aren't currently supported through a separate
// class in the PHP client library.  However, we can use the generic 
// Zend_Gdata_Query class as an alternative

// URL for a community search request
// Creates a Zend_Gdata_Query
$query = $gp->newQuery("https://picasaweb.google.com/data/feed/api/all");

// looking for photos in the response
$query->setParam("kind", "photo");

// full text search
$query->setQuery("goldendoodle");

// maximum of 10 results
$query->setMaxResults("10");

// There isn't a specific class for representing a feed of community
// search results, but the Zend_Gdata_Photos_UserFeed understands
// photo entries, so we'll use that class
$userFeed = $gp->getUserFeed(null, $query);
foreach ($userFeed as $photoEntry) {
    echo $photoEntry->getTitle()->getText() . "<br />\n";
    // The 'alternate' link on a photo represents the link to
    // the image page on Picasa Web Albums
    echo $photoEntry->getLink('alternate')->getHref() . "<br />\n";
    echo "<br />\n";
}

Accessing photo information

In previous examples, only the title of a photo was printed out. However, there is a lot of different data that can be retrieved about a photo such as Exif information, thumbnail URLs, the ID of the album it is a part of, and more.

$camera = "";
$contentUrl = "";
$firstThumbnailUrl = "";

$albumId = $photoEntry->getGphotoAlbumId()->getText();
$photoId = $photoEntry->getGphotoId()->getText();

if ($photoEntry->getExifTags() != null && 
    $photoEntry->getExifTags()->getMake() != null &&
    $photoEntry->getExifTags()->getModel() != null) {

    $camera = $photoEntry->getExifTags()->getMake()->getText() . " " . 
              $photoEntry->getExifTags()->getModel()->getText();
}

if ($photoEntry->getMediaGroup()->getContent() != null) {
  $mediaContentArray = $photoEntry->getMediaGroup()->getContent();
  $contentUrl = $mediaContentArray[0]->getUrl();
}

if ($photoEntry->getMediaGroup()->getThumbnail() != null) {
  $mediaThumbnailArray = $photoEntry->getMediaGroup()->getThumbnail();
  $firstThumbnailUrl = $mediaThumbnailArray[0]->getUrl();
}

echo "AlbumID: " . $albumId . "<br />\n";
echo "PhotoID: " . $photoId . "<br />\n";
echo "Camera: " . $camera . "<br />\n";
echo "Content URL: " . $contentUrl . "<br />\n";
echo "First Thumbnail: " . $firstThumbnailUrl . "<br />\n";

echo "<br />\n"; 

The above example prints out different pieces of information from a PhotoEntry. It also demonstrates how the method PhotoEntry::getMediaGroup() can be used to retrieve elements from the Media RSS namespace. The camera data, if available, is found inside of the Exif namespace.

Post a new photo

You can upload a photo to Picasa Web Albums using the insertPhotoEntry method of the Zend_Gdata_Photos object. The following demonstrates an example with a few assumptions: $username is the name of the user who owns the album and that we have authenticated as, $albumId is the the id of the album to upload the photo to, $file is the path to the file on the local disk, $photoName is the title you would like to assign to the photo, $photoCaption is the caption of the photo, $photoTags is a list of comman-delineated tags to assign to the photos, $gp is an authenticated Zend_Gdata_Photos object, and "image/jpeg" is the valid MIME type of the file to be uploaded.

$username = "default";
$filename = "/tmp/photo.jpg";
$photoName = "My Test Photo";
$photoCaption = "The first photo I uploaded to Picasa Web Albums via PHP.";
$photoTags = "beach, sunshine";

// We use the albumId of 'default' to indicate that we'd like to upload
// this photo into the 'drop box'.  This drop box album is automatically 
// created if it does not already exist.
$albumId = "default";

$fd = $gp->newMediaFileSource($filename);
$fd->setContentType("image/jpeg");

// Create a PhotoEntry
$photoEntry = $gp->newPhotoEntry();

$photoEntry->setMediaSource($fd);
$photoEntry->setTitle($gp->newTitle($photoName));
$photoEntry->setSummary($gp->newSummary($photoCaption));

// add some tags
$keywords = new Zend_Gdata_Media_Extension_MediaKeywords();
$keywords->setText($photoTags);
$photoEntry->mediaGroup = new Zend_Gdata_Media_Extension_MediaGroup();
$photoEntry->mediaGroup->keywords = $keywords;

// We use the AlbumQuery class to generate the URL for the album
$albumQuery = $gp->newAlbumQuery();

$albumQuery->setUser($username);
$albumQuery->setAlbumId($albumId);

// We insert the photo, and the server returns the entry representing
// that photo after it is uploaded
$insertedEntry = $gp->insertPhotoEntry($photoEntry, $albumQuery->getQueryUrl()); 

Update a photo

This example will give the photo a title, a caption, some tags, and geographic location. Notice that we are adding three tags (foo, bar, and baz) all at the same time using the <media:keywords> element.

Zend_Loader::loadClass('Zend_Gdata_Media_Extension_MediaKeywords');
Zend_Loader::loadClass('Zend_Gdata_Geo_Extension_GeoRssWhere');
Zend_Loader::loadClass('Zend_Gdata_Geo_Extension_GmlPos');
Zend_Loader::loadClass('Zend_Gdata_Geo_Extension_GmlPoint');

$insertedEntry->title->text = "New Photo";
$insertedEntry->summary->text = "Photo caption";

$keywords = new Zend_Gdata_Media_Extension_MediaKeywords();
// $foo->text = 'bar' is equivalent to $foo->setText('bar')
$keywords->setText("foo, bar, baz");
$insertedEntry->mediaGroup->keywords = $keywords;
    
$where = new Zend_Gdata_Geo_Extension_GeoRssWhere();
$position = new Zend_Gdata_Geo_Extension_GmlPos('37.0 -122.0');
$where->point = new Zend_Gdata_Geo_Extension_GmlPoint($position);
$insertedEntry->setGeoRssWhere($where); 
    
$updatedEntry = $insertedEntry->save();

Delete a photo

Deleting a photo is done by using the PhotoEntry::delete method.

$photoEntry->delete();

Working with Tags

Tags are a convenient way to label and organize your photos. By associating photos with descriptive strings, it makes searching through large quantities of photos easier.

Retrieving a list of tags

Your program can retrieve a list of tags that are used by a user, in a particular album, or that are associated with a particular photo.

List tags by user

The following code will print out all of the tags that a user has used in photos in their albums.

The string "default" can be used in place of a real username, in which case the server will use the username of the user credentials used to authenticate the request.

// Creates a Zend_Gdata_Photos_UserQuery
$query = $gp->newUserQuery();

$username = "default";

// indicate the user's feed to retrieve
$query->setUser($username);

// set to only return tags
// the default kind value for a user feed is to include only albums
$query->setKind("tag");
$query->setMaxResults("10");

// we're passing null for the username, as we want to send
// additional query parameters generated by the UserQuery class
$userFeed = $gp->getUserFeed(null, $query);

// because we specified 'tag' for the kind, only PhotoEntry objects 
// will be contained in the UserFeed
foreach ($userFeed as $tagEntry) {
    echo $tagEntry->title->text . "<br />\n";
}

List tags by album

The following code will print out all of the tags that $username has tagged photos with in the $albumname album.

$query = new Zend_Gdata_Photos_AlbumQuery();

$username = "default";
$albumname = "sample.albumname";

// indicate the user's feed to retrieve
$query->setUser($username);

$query->setAlbumName($albumname);

// set to only return tags
$query->setKind("tag");
$query->setMaxResults("10");

// we're passing null for the username, as we want to send
// additional query parameters generated by the UserQuery class
$userFeed = $gp->getUserFeed(null, $query);

// because we specified 'tag' for the kind, only PhotoEntry objects 
// will be contained in the UserFeed
foreach ($userFeed as $tagEntry) {
    echo $tagEntry->title->text . "<br />\n";
}

List tags by photo

The following code will print out all of the tags that username has tagged the photo identified by $photoid with in the $albumname album. The Accessing photo information section describes how to retrieve a valid value for $photoid.

// Create a Zend_Gdata_Photos_PhotoQuery();
$query = $gp->newPhotoQuery();

$username = "default";
$photoid = "12345";
$albumname = "sample.albumname";

// indicate the user's feed to retrieve
$query->setUser($username);

$query->setAlbumName($albumname);
$query->setPhotoId($photoid);

// set to only return tags 
$query->setKind("tag");
$query->setMaxResults("10");

// we're passing null for the username, as we want to send
// additional query parameters generated by the UserQuery class
$userFeed = $gp->getUserFeed(null, $query);

// because we specified 'tag' for the kind, only PhotoEntry objects 
// will be contained in the UserFeed
foreach ($userFeed as $tagEntry) {
    echo $tagEntry->title->text . "<br />\n";
}

Note that this same information is available inside of the <media:keywords> element of the photo itself in a comma separated format.

Search photos using tags

The following code uses the tag parameter to search for all photos belonging to $username that are tagged with both "foo" and "bar".

// Creates a Zend_Gdata_Photos_UserQuery
$query = $gp->newUserQuery();

$username = "default";

// indicate the user's feed to retrieve
$query->setUser($username);
$query->setTag("foo,bar");

// set to only return photos
// the default kind value for a user feed is to include only albums
$query->setKind("photo");
$query->setMaxResults("10");

// we're passing null for the username, as we want to send
// additional query parameters generated by the UserQuery class
$userFeed = $gp->getUserFeed(null, $query);

// because we specified 'photo' for the kind, only PhotoEntry objects 
// will be contained in the UserFeed
foreach ($userFeed as $photoEntry) {
    echo $photoEntry->title->text . "\n";
    $mediaContent = $photoEntry->getMediaGroup()->getContent();
    echo $mediaContent[0]->getUrl() . "<br />\n";
}

Note you could search for photos in a particular album by using the AlbumQuery class and adding the album name as an additional parameter.

Adding a tag to a photo

The following code adds the tag "foo" to the photo identified by $photoid, in the $albumname album which is owned by $username.

// Create a Zend_Gdata_Photos_PhotoQuery
$query = $gp->newPhotoQuery();

$username = "default";
$photoid = "12345";
$albumname = "sample.albumname";

// indicate the user's feed to retrieve
$query->setUser($username);

$query->setAlbumName($albumname);
$query->setPhotoId($photoid);

$photoEntry = $gp->getPhotoEntry($query);

$tag = $gp->newTagEntry();
$tag->setTitle($gp->newTitle('foo'));

$createdTag = $gp->insertTagEntry($tag, $photoEntry); 

Note: you can also set multiple tags on a photo at once using a MediaKeywords object. Please see the Update a photo section for more information.

Deleting a tag from a photo

Deleting a tag is done by using the TagEntry::delete method.

$createdTag->delete();

Working with Comments

Comments are short text snippets attached to photos by Picasa Web Albums users.

Retrieving a list of comments

The following example prints out the 10 most recent comments on $username's photos.

The string "default" can be used in place of a real username, in which case the server will use the username of the user credentials used to authenticate the request.

// Creates a Zend_Gdata_Photos_UserQuery
$query = $gp->newUserQuery();

$username = "default";

// indicate the user's feed to retrieve
$query->setUser($username);

// set to only return comments 
// the default kind value for a user feed is to include only albums
$query->setKind("comment");
$query->setMaxResults("10");

// we're passing null for the username, as we want to send
// additional query parameters generated by the UserQuery class
$userFeed = $gp->getUserFeed(null, $query);

// because we specified 'comment' for the kind, only CommentEntry objects 
// will be contained in the UserFeed
foreach ($userFeed as $commentEntry) {
    echo $commentEntry->title->text . " said: " . $commentEntry->content->text . "<br />\n";
}

List comments by photo

You can also retrieve all of the comments associated with a particular photo. The following example prints out all of the comments on the photo identified by $photoid, inside of the $albumname album, owned by the $username user. The Accessing photo information section describes how to retrieve a valid value for $photoid.

// Create a Zend_Gdata_Photos_PhotoQuery
$query = $gp->newPhotoQuery();

$username = "default";
$photoid = "12345";
$albumname = "sample.albumname";

// indicate the user's data to retrieve
$query->setUser($username);
$query->setAlbumName($albumname);
$query->setPhotoId($photoid);

// set to only return comments 
$query->setKind("comment");
$query->setMaxResults("10");

$photoFeed = $gp->getPhotoFeed($query);

// because we specified 'comment' for the kind, only CommentEntry objects 
// will be contained in the UserFeed
foreach ($photoFeed as $commentEntry) {
    echo $commentEntry->title->text . " said: " . $commentEntry->content->text . "<br />\n";
}

Add comments to a photo

The following code adds the comment "great photo!" to the photo identified by $photoid in the $albumname owned by $username.

// Create a Zend_Gdata_Photos_PhotoQuery
$query = $gp->newPhotoQuery();

$username = "default";
$photoid = "12345";
$albumname = "sample.albumname";

// indicate the user's feed to retrieve
$query->setUser($username);

$query->setAlbumName($albumname);
$query->setPhotoId($photoid);

$photoEntry = $gp->getPhotoEntry($query);

$comment = $gp->newCommentEntry();
$comment->setContent($gp->newContent('foo'));

$createdComment = $gp->insertCommentEntry($comment, $photoEntry); 

Delete a comment from a photo

Deleting a comment is done by using the CommentEntry::delete method.

$createdComment->delete();

 

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.