Reference Guide

This document provides detailed reference documentation for the Picasa Web Albums Data API. It covers only the protocol; for programming-language-specific reference documentation, see the client libraries page.

Picasa Web Albums feed types

Picasa Web Albums provides a variety of representations of photo- and album-related data. There are three independent axes for specifying what you want when you request data: visibility, projection, and path/kind.

Visibility values let you request data at various levels of sharing. For example, a visibility value of public requests publicly visible data. For a list of values, see Visibility values, below. The default visibility depends on whether the request is authenticated or not, and on whether the requester is the owner or not.

Projection values let you indicate what elements and extensions should appear in the feed you're requesting. For example, a projection value of base indicates that the representation is a basic Atom feed without any extension elements, suitable for display in an Atom reader. For a list of values, see Projection values, below. You must specify a projection value.

Path and kind values let you indicate what type of items you want information about. For example, a path of user/liz and a kind value of tag requests a feed of tags associated with the user whose username is liz. Path and kind values are separate parts of the URI, but they're used together to indicate the item type(s) desired. For a list of path values, see Path values, below; for a list of kind values, see Kind values, below. You must specify a path, but kind is optional; the default kind depends on the path.

To request a particular representation, you specify a visibility value, a projection value, and a path and kind in the URI that you send to Picasa Web Albums.

The URI of a representation of a Picasa Web Albums feed takes the following form:

For example, the following URI is for a feed listing a user's private albums. The projection is api, which requests a full feed with all relevant extension elements, and the visibility is private, which requests only albums that aren't publicly visible:

If you don't specify a visibility value, then the visibility depends on who the requester is. For authenticated requests from the owner, the default is all. For authenticated requests from a non-owner, as well as for unauthenticated requests, the default is visible.

The projection value is required.

As a developer, you'll usually want to use the api projection. You'll normally use only two of the visibility levels: all or visible.

For an authenticated feed, instead of specifying a user ID, you can specify the special value default, which tells Picasa Web Albums to use the user ID and password that you provided during authentication.

Some feed types are read/write (that is, you can post new data to them, and edit or delete existing data), while others are read-only. Read-only feeds don't include a <link rel="http://schemas.google.com/g/2005#post"> element (to tell you where to post new events), and entries in read-only feeds don't include <link rel="edit"> or <link rel="edit-media"> elements.

Visibility values

The following table describes the supported visibility values.

Note that there are three kinds of requests: authenticated requests from the owner; authenticated requests from a non-owner; and unauthenticated requests.

Visibility

Description

Security Notes

all

Shows all data, both public and private.

Requires authentication. Default for the owner, and only the owner can specify this value.

private

Shows only private data.

Requires authentication. Only the owner can specify this value.

public

Shows only public data.

Does not require authentication. Most often used by an authenticated user to see only the publicly visible photos, corresponding to "View My Public Gallery" in the Picasa Web Albums GUI.

visible

Shows all data the user has access to, including both all public photos or albums and any photos or albums that the owner has explicitly given the authenticated user rights to (using ACLs).

Does not require authentication. Default for unauthenticated requests and for non-owners. For unauthenticated requests, this is the same as public. For authenticated non-owners, this returns the data that the owner has given them access to. For authenticated requests from the owner, this is the same as all.

Projection values

Although the examples in this documentation use only the api projection, Picasa Web Albums also supports a base projection for use by feed readers.

Path values

There are three basic types of feeds: user-based, album-based, and photo-based. You indicate which type you want by specifying a path. For each of those types, you can additionally specify which kind or kinds of associated data you want.

Note: Each path includes a user ID, which is an ID associated with a user's Google account. The user ID can be either a username or an email address, so it may or may not include an @ sign and a domain name.

User-based feed

The user-based feed represents data associated with a particular user. A user-based feed can contain either album, or tag, or photo or comment kinds, which you can request using the kind parameter.

To retrieve a user-based feed, you can make a request to the appropriate feed URL:

Featured photos feed

The featured photos feed allows you to retrieve a feed of the currently featured photos on Picasa Web Albums:

https://picasaweb.google.com/data/feed/projection/featured

Kind values

The kind parameter lets you request information about a particular kind of item. The parameter value should be a comma-separated list of requested kinds.

If you omit the kind parameter, Picasa Web Albums chooses a default kind depending on the level of feed you're requesting. For a user-based feed, the default kind is album; for an album-based feed, the default kind is photo; for a photo-based feed, the default kind is comment; for a community search feed, the default kind is photo.

Note: You can't edit comments or tags. Sending a PUT to the edit URI of a comment or tag entry has no effect.

The following table describes the supported kind values:

Kind

Description

Supported Feeds

album

Feed includes some or all of the albums the specified user has in their gallery. Which albums are returned depends on the visibility value specified.

User-based feed

photo

Feed includes the photos in an album (album-based), recent photos uploaded by a user (user-based) or photos uploaded by all users (community search).

Album-based, user-based and community search feeds

comment

Feed includes the comments that have been made on a photo.

Photo-based and user-based feeds

tag

Includes all tags associated with the specified user, album, or photo. For user-based and album-based feeds, the tags include a weight value indicating how often they occurred.

User-based, album-based, and photo-based feeds

user

Feed includes entries representing users.

Contacts-based feed

Picasa Web Albums query parameters reference

Picasa Web Albums supports the following Google Data Protocol query parameters: start-index, max-results, alt, fields, and prettyprint. The user-based and community search feeds support the q full-text search query parameter. Picasa Web Albums does not currently support the other standard parameters.

Searches the title, caption and tags for the specified string value. See the Google Data Protocol query parameter reference. This parameter can only be used with the user-based and community search feeds.

Filters photos in the user-based and album-based feeds by the specified tag.

thumbsize

Thumbnail size parameter

Valid with album or photo kinds; specifies what image size to use for thumbnails. Multiple values may be specified using a comma-delimited list. If multiple values are specified, multiple media:thumbnail elements will be returned in the feed. Refer to the list of valid values below.

The following values are valid for the thumbsize and imgmax query parameters and are embeddable on a webpage. These images are available as both cropped(c) and uncropped(u) sizes by appending c or u to the size. As an example, to retrieve a 72 pixel image that is cropped, you would specify 72c, while to retrieve the uncropped image, you would specify 72u for the thumbsize or imgmax query parameter values.

32, 48, 64, 72, 104, 144, 150, 160

The following values are valid for the thumbsize and imgmax query parameters and are embeddable on a webpage. These images are available as only uncropped(u) sizes by appending u to the size or just passing the size value without appending anything.

There is an additional size d which results in the <media:content> elements referencing the original uploaded photo, including all original Exif data. It is valid only for use with the imgmax query parameter.

These query parameters are used when retrieving the feeds in order to get images of the appropriate sizes. They cannot be used when retrieving the actual images. Example URL using the imgmax parameter:

Using Picasa Web Albums from Flash (crossdomain.xml)

You can retrieve a Picasa Web Albums crossdomain.xml file from the following location:

https://photos.googleapis.com/data/crossdomain.xml

Each of the feeds normally accessible with a base prefix of https://picasaweb.google.com/data are also accessible with the new base URL of https://photos.googleapis.com/data in order to take advantage of the crossdomain.xml file. Because the crossdomain.xml file is not at the root of the host, you must use the loadPolicyFile method to indicate the location:

Note: When logged into Picasa Web Albums through your browser, you can retrieve read-only private feeds through https://picasaweb.google.com/data because of the cookies set in your browser. This is not the case for https://photos.googleapis.com/data, as only AuthSub and ClientLogin authentication is accepted when accessing feeds via this URL.

For information about the standard Google Data API elements, see the Atom specification and the Kinds document.

Media RSS (media namespace) element reference

Picasa Web Albums uses the media (http://search.yahoo.com/mrss/) namespace for elements defined in the Media RSS specification. For information about the media namespace, see the Media RSS specification.

Note: Despite the name "Media RSS," the Picasa Web Albums Data API uses elements from the media namespace in both Atom and RSS feeds.

As usual in the Google Data API documentation, a question mark after an attribute name indicates that the attribute is optional. Almost all of the attributes we list for media elements are required.

media:content

Contains the URL and other information about the full version of the entry's media content.

The <media:content> element appears as a child of a <media:group> element.

There can be multiple <media:content> elements for a given <media:group>. For example, a video may have a <media:content medium="image"> element that specifies a JPEG representation of the video, and a <media:content medium="video"> element that specifies the URL of the video itself.

Attributes

Attribute

Description

url

The URL of the full version of the media for the current entry.

type

The MIME type of the media.

medium

Either image or video. Somewhat redundant, as type contains a more specific MIME type, but medium may be simpler for the client to interpret.

height

The height of the image or video represented by this <media:content> element.

width

The width of the image or video represented by this <media:content> element.

fileSize?

The file size in bytes of the image or video represented by this <media:content> element.

Example

media:credit

Contains the nickname of the user who created the content. This is a user-specified value that should be used when referring to the user by name.

The <media:credit> element appears as a child of a <media:group> element.

<media:credit>Liz Bennet</media:credit>

media:description

Contains a description of the entry's media content. For api projections, the description is in plain text; for base projections, the description is in HTML. This field is limited to 1024 characters. The description can contain UTF-8 characters.

The <media:description> element appears as a child of a <media:group> element.

Attributes

Attribute

Description

type

Either plain or html. Is set to plain for api projections, html for base projections.

Example

<media:description type="plain">A set of photographs I took while
vacationing in Italy. Florence is beautiful!</media:description>

media:group

Container element for all media elements.

The <media:group> element can appear as a child of an album or photo entry.

media:keywords

Lists the tags associated with the entry. Contains a comma-separated list of tags that have been added to the photo, or all tags that have been added to photos in the album. Tags are limited to 128 characters and 100 tags per item. Tags use the UTF-8 character set, so they are not limited to ASCII.

The <media:keywords> element appears as a child of a <media:group> element.

<media:keywords>italy, vacation, sunset</media:keywords>

media:thumbnail

Contains the URL of a thumbnail of a photo or album cover. If the thumbsize parameter is set, this element points to thumbnails of the requested sizes; otherwise the thumbnails are the default thumbnail size.

The <media:thumbnail> element appears as a child of a <media:group> element. There can be multiple <media:content> elements for a given <media:group>; for example, a given item may have multiple thumbnails at different sizes. Photos generally have two thumbnails at different sizes; albums generally have one cropped thumbnail.

Picasa Web Albums also accepts geographic-location data in two other formats: W3C format and plain-GeoRSS (without GML) format. But those formats are beyond the scope of this document. All geo data that appears in feeds generated by Picasa Web Albums uses the GeoRSS-plus-GML format documented here.

As usual in the Google Data API documentation, a question mark after an attribute name indicates that the attribute is optional. Almost all of the attributes we list for these elements are required.

georss:where

Specifies a geographical location or region. (Not to be confused with <gd:where>.) A container element, containing a single <gml:Point> element.

Attributes

Example

gml:Point

Specifies a particular geographical point, by means of a <gml:pos> element.

Appears as a child of a <georss:where> element.

Attributes

None.

Example

<gml:Point>
<gml:pos>35.669998 139.770004</gml:pos>
</gml:Point>

gml:pos

Specifies a latitude and longitude, separated by a space.

Appears as a child of a <gml:Point> element.

Attributes

None.

Example

<gml:pos>35.669998 139.770004</gml:pos>

Exif (exif namespace) element reference

Picasa Web Albums uses the exif (http://schemas.google.com/photos/exif/2007) namespace to represent Exif data encoded in a photo. The schema URL for the exif namespace is http://schemas.google.com/photos/exif/2007.

The exif elements all appear inside the container element called <exif:tags>.

Example

Schema

gphoto:numphotosremaining

The number of remaining photo uploads allowed in this album. This is equivalent to the user's maximum number of photos per album (<gphoto:maxPhotosPerAlbum>) minus the number of photos currently in the album (<gphoto:numphotos>).

The <gphoto:numphotosremaining> element can appear as a child of <atom:entry> or <atom:feed>. The <gphoto:numphotosremaining> element is valid with the album kind.

Note: This element appears only if the authenticated user is the owner of the feed.