Introduction to the AOL Pictures JSON API

by Kevin Farnham
September 14, 2007

Introduction

The AOL Pictures API provides programmable access to pictures stored by users at the AOL Pictures site. AOL Pictures actually has two APIs: a JSON API and an ATOM feed API. In this article, I'll introduce both APIs, but the focus will be on the AOL Pictures JSON API.

The introduction to the AOL Pictures API documentation describes the API as follows:

The AOL Pictures open API is a free service that allows you to retrieve public data (photos, captions, and more) stored on AOL Pictures. Photos are meant to be shared. With this open API, we want to enable everyone to share public photos in new, creative, and innovative ways. Experimentation is the key to innovation, and we highly encourage you to experiment and create your own web application, widget, or tool.

The APIs indeed give developers the power to integrate pictures, and picture albums, that people want to share into your own application. I experimented with several of the AOL Pictures JSON API components, and found that I was readily able to come up with some neat little applications that I could run on my Windows desktop in an Internet Explorer browser. I'll describe two of these applications in detail in this article.

Registering to Use the AOL Pictures API? No!

Developers who use APIs are accustomed to having to register to gain access to the APIs. However, the AOL Pictures API doesn't require any sign up or registration procedure whatsoever. The API is freely available to anyone who'd like to use it, without restriction. The AOL Pictures team really means it when they say "we want to enable everyone to share public photos." Talk about open!

AOL Pictures ATOM Feed API Overview

The AOL Pictures Atom Feed lets you subscribe to a an individual's AOL Pictures gallery, and receive notification when they've added a new picture. In addition, there are tag and comment feeds.

The tag feed is very useful if you'd like to see the latest images uploaded that have been tagged with a specific tag, or if you'd like to be notified when new images are tagged using the tag of interest. For example, let's say I want to see images that are tagged "nascar." The feed statement for gathering those pictures is:

http://pictures.aol.com/galleries/tags/nascar/atom.xml

If you point your browser at pictures.aol.com/galleries/tags/nascar/atom.xml, you'll see a page of NASCAR-related photos, namely the photos on AOL Pictures that were tagged "nascar."

AOL Pictures JSON API Overview

The AOL Pictures JSON API consists of six calls to the http://api.pictures.aol.com site:

• getAlbumList: Retrieves a list of all public albums for a screen name; you can optionally specify retrieving myAlbums, aimPages, blogs, or memberProfile; and you can specify the maximum number of results to return.
• getPicturesByAlbumID: Retrieves the picture and album data for a single album; you can specify a maximum number of pictures to return and a sort field (sequence, creationDate, modificationDate).
• getPublicGallery: Retrieves the picture and album data for a single public gallery album; the pictures are returned and sorted by creation date, with the most recently created pictures returned first.
• getPublicTagsByUser: Retrieves the list of tags for an album owner's public photos, sorted by how many times each tag was used (in descending order).
• getTaggedPublicPhotos: Gets the picture data for a tag or list of tags; you can specify the maximum number of pictures to return.
• getTaggedPublicPhotosByUser: Retrieves a specific user's picture and album data for pictures the user has tagged; you can specify multiple tags, and the maximum number of pictures to be returned.

JSON Examples Coding Platform

Most of the remainder of this article is devoted to demonstrating how to use two of the functions in the AOL Pictures JSON API:

• getAlbumList
• getTaggedPublicPhotos

Since this article's focus is on the AOL Pictures API, I'm not going to delve into issues such as browser differences, cross-domain restrictions, and whether the code is hosted locally or on a web server. These matters are standard complications for Ajax web developers, and detailed discussion of the issues is readily available elsewhere.

For this article, my testing was done with locally hosted code using Internet Explorer 6. If you download the code, put it into a directory on your Windows system, and load it into IE6 (or later), you should see the same results I present here.

Also, the code assumes that the standard json.js script is located in the same directory where the HTML file is located. The json.js file that was used for the applications documented in this article is included in the downloadable code file included in the Resources section of this article.

AOL Pictures JSON API Example: getAlbumList

To test the AOL Pictures getAlbumList JSON API function, I made a very simple web page that looks like this:

Figure 1. AOL Pictures JSON API getAlbumList demo application

The application consists of the following components:

• A form into which you enter the name of an AOL Pictures user whose album list you'd like to retrieve.
• A Status label followed by a <div> element, where status information is displayed as the application runs.
• A JSON label followed by a <div> element, where the JSON returned by the API is displayed.
• A "The Album List" label followed by a <div> element, where the list of the user's albums is displayed.

Here's the <body> section of the HTML code:

<body>

<h2>Get an AOL Pictures Album List</h2>

<form id="getAlbumListForm" action="javascript:doGetAlbumList();">
<strong>Enter AOL Pictures User Name</strong><br/>
<input type="text" name="userName" id ="userName"/><br/>
<input type="submit" value="getAlbumList"/>
</form>

<p>
<strong>Status: </strong>
<div id="statusDiv"></div>
</p>

<h3>The JSON</h3>

<div id="jsonDiv"></div>

<h3>The Album List</h3>

<div id="albumListDiv"></div>

</body>

Rather simple--but of course, all the really interesting stuff happens in the JavaScript located in the <head> section of the HTML file.

The user comes to this page, and types an AOL Pictures user name into the input box. Then the user clicks the "getAlbumList" button. Now what happens?

Well, clearly the JavaScript function doGetAlbumList() is called when the "getAlbumList" button is pressed. Let's take a look at this function:

function doGetAlbumList() {
  var statusDiv = document.getElementById("statusDiv");
  statusDiv.innerHTML += "doGetAlbumList<br/>";

  userName = getAlbumListForm.userName.value;
  if (userName == "") {
    alert("you didn't enter a user!!");
    return;
  }
  
  var url = "http://api.pictures.aol.com/gv1/json/getAlbumList.do?owner=" + userName;

  myReq = createXMLHttpRequest();

  statusDiv.innerHTML += "send request: " + url + "<br/>";
  myReq.open("get", url, true);

  statusDiv.innerHTML += "check Ready State Changes<br/>";
  myReq.onreadystatechange = handleResponse; 

  myReq.send(null); 
}

The lines involving statusDiv are for debug/logging. They add diagnostic information to the page in the Status section. The first important step is extracting the userName that was entered into the form. If no characters were entered into the form, an alert is displayed and the function is exited.

If a user name was entered into the form, the variable url is created. This variable contains the AOL Pictures URL for the getAlbumList JSON API function. As you can see, the URL is quite simple: just the base URL appended with an owner= clause.

Next, createXMLHttpRequest() is called to create the XMLHttpRequest object. This function contains code that is present in one form or another in virtually every Ajax application:

// standard AJAX XMLHttpRequest creation
function createXMLHttpRequest() {
  var xmlHttpReq;

  var statusDiv = document.getElementById("statusDiv");
  statusDiv.innerHTML = "";
  
  if (window.ActiveXObject) {
    // IE 5+
    statusDiv.innerHTML += "using microsoft.xmlhttp<br/>";
    xmlHttpReq = new ActiveXObject("Microsoft.XMLHTTP");
  } else if (window.XMLHttpRequest) {
    // Firefox, Opera, Safari
    statusDiv.innerHTML += "using XMLHttpRequest<br/>";
    xmlHttpReq = new XMLHttpRequest();
  } else {
    // older or non-supported browser
    statusDiv.innerHTML += 
      "Problem: this browser does not support XMLHttpRequest!!!<br/>";
    alert("Problem: this browser does not support XMLHttpRequest!!!");
    xmlHttpReq = null;
  }
  return xmlHttpReq;
}

Once the XMLHttpRequest has been created, it is opened using the getAlbumList URL, and handleResponse() is called to await receipt of the returned JSON data.

handleResponse() is another piece of code that will be familiar to most AJAX programmers:

function handleResponse() {
  var statusDiv = document.getElementById("statusDiv");
  statusDiv.innerHTML += "new state: " + myReq.readyState + "<br/>";
  if (myReq.readyState == 4) {
    if (myReq.status != 200) {
      statusDiv.innerHTML += "server responded, but with HTTP status "
         + myReq.status + "[" + myReq.responseText + "]<br/>";
    } else {
      statusDiv.innerHTML += "received JSON response<br/>";
      jsonObj = eval( "(" + myReq.responseText + ")" );
      getAlbumListJsonHandler(jsonObj);
    }
  }
}

Once again, the statusDiv is used to provide diagnostic logging as the processing progresses. The primary work of the handleResponse() function is to check the XMLHttpRequest's readyState property, waiting until it has a value of 4 (indicating that the full response from the server has been received). Then the status parameter for the response is checked; if it's 200 (indicating success), then the received data can be processed using the function getAlbumListJsonHandler():

function getAlbumListJsonHandler(jsonObj) {
  var albumText;
  var statusDiv = document.getElementById("statusDiv");
  statusDiv.innerHTML += "getAlbumListJsonHandler<br/>";
  
  var jsonString = jsonObj.toJSONString();

  var jsonDiv = document.getElementById("jsonDiv");
  jsonDiv.innerHTML = "<code>" + jsonString + "</code>";

  var nAlbum = jsonObj.albums.length;
  statusDiv.innerHTML += "processing " + jsonObj.albums.length + 
     " albums<br/>";
  albumText = "<p>" + jsonObj.albums.length + 
     " albums: </p><ol>";

  for (var i=0; i<nAlbum; i++) {
    albumText += "<li>" + jsonObj.albums[i].title + "</li>";
  }
  albumText += "</ol>";

  var albumListDiv = document.getElementById("albumListDiv");
  albumListDiv.innerHTML = albumText;

  statusDiv.innerHTML += "done!<br/>";
}

The function getAlbumListJsonHandler() converts the received response into a JSON string using the toJSONString() method, and then parses the JSON data. Diagnostics are written to the statusDiv; the received JSON data is written to the jsonDiv; and a summary of the album list identified in the JSON data is written to the albumListDiv.

Here's what the web page looks like when I enter my own AOL Pictures user name (kevinfarnham1) into the form:

 (click image to view larger image)
Figure 2. getAlbumList result for AOL Pictures user kevinfarnham1

The Status section shows the accumulated diagnostic logging for the entire request/response sequence. The "The Album List" section shows that I have two albums and displays their names. The JSON section is a bit difficult to decipher in its as-received state. Here's a better formatted version of the JSON that was returned:

{
  "albums":[
    {
      "title":"My AIM Pages Pictures",
      "category":"aimPages",
      "creationDate":"Mon, 11 Dec 2006 20:47:51 -0500",
      "id":"1uXYxRKKm4Tfq9SNIKjG82b+e45Kbt2j3dKYufng6UKJJdNX5w59hg==",
      "pictureCount":1
    },
    {
      "title":"My Public Album",
      "category":"myAlbums",
      "creationDate":"Fri, 03 Aug 2007 01:35:43 -0500",
      "id":"1uXYxRKKm4QyY2Sb5FqZGgpa4KB+TYX4nKdGR+9XabuJJdNX5w59hg==",
      "pictureCount":5
    }
  ]
}

AOL Pictures JSON API Example: getTaggedPublicPhotos

The code for the getAlbumList example can be used as a starting point for trying out the AOL Pictures JSON API getTaggedPublicPhotos function. The code that performs the standard XMLHttpRequest processing is little changed. We need only to replace code that is specific to getAlbumList with the corresponding code for getTaggedPublicPhotos.

The getTaggedPublicPhotos API call returns lists of public photos that have been tagged using a specified tag. So, for the new application, the user must enter the tag to search for, rather than the user name. Here's how the application looks initially:

Figure 3. AOL Pictures JSON API getTaggedPublicPhotos demo application

As you can see, this is the same design used for the getAlbumList application, except for different labels. Here's the <body> section of the HTML:

<body>

<h2>Get an AOL Pictures Tagged Public Photo</h2>

<form id="getTaggedPublicPhotosForm" 
      action="javascript:doGetTaggedPublicPhotos();">
<strong>Enter AOL Pictures Tag</strong><br/>
<input type="text" name="picTag" id ="picTag"/><br/>
<input type="submit" value="getTaggedPublicPhotos"/>
</form>

<p>
<strong>Status: </strong>
<div id="statusDiv"></div>
</p>

<h3>The JSON</h3>

<div id="jsonDiv"></div>

<h3>The Tagged Photo</h3>

<div id="taggedPhotoDiv"></div>

</body>

Submitting the form launches the doGetTaggedPublicPhotos() function. This function is almost identical to the doGetAlbumList() function in the first application. The major difference, of course, is the call to the AOL Pictures JSON API function. In the new application, the XMLHttpRequest is launched using this URL assignment:

  var url = "http://api.pictures.aol.com/gv1/pictures/" +
            "getTaggedPublicPhotos?f=json&devId=tbd&" +
	    "h=host&locale=en_US&max=1&tag=" + picTag;

where:

• f=json defines that the response should be returned in JSON format.
• devId=tbd defines your developer ID (this parameter is a placeholder at present, since right now no registration is required for using the AOL Pictures API).
• h=host defines host, a human-readable name for the caller.
• locale=en_US defines the locale, in this case US English.
• max=1 defines that a maximum of one photo should be returned.
• picTag is the tag entered by the user on the form.

The return of a maximum of one photo was selected to keep the demo application simple.

The handleResponse() function for the new application differs from the earlier version only in that it calls the new function getTaggedPublicPhotosJsonHandler() when a valid response is received from the server. Here's getTaggedPublicPhotosJsonHandler():

function getTaggedPublicPhotosJsonHandler(jsonObj) {
  var picHtml;
  var statusDiv = document.getElementById("statusDiv");
  statusDiv.innerHTML += "getTaggedPublicPhotosJsonHandler<br/>";
  
  var jsonString = jsonObj.toJSONString();

  var jsonDiv = document.getElementById("jsonDiv");
  jsonDiv.innerHTML = "<code>" + jsonString + "</code>";

  var nPic = jsonObj.response.data.pictureCount;

  picHtml = "<p>Number of returned pictures: " + nPic + "</p>";

  if (nPic > 0) {
    picHtml += "<p>AOL Pictures User: " + 
        jsonObj.response.data.pictures[0].loginId + "<br/>" +
	"Caption: [" + 
	jsonObj.response.data.pictures[0].caption + "]</p>";
	
    // display the medium size version of the photo
    var picUrl = jsonObj.response.data.pictures[0].permalink + "&size=m";
    picHtml += "<img src=\"" + picUrl + "\"/>";
  }
  
  var TaggedPhotoDiv = document.getElementById("taggedPhotoDiv");
  TaggedPhotoDiv.innerHTML = picHtml;

  statusDiv.innerHTML += "done!<br/>";
}

The start of the function is similar to the start of getAlbumListJsonHandler(). The pictureCount parameter is checked to determine if any pictures that matched the specified tag were returned. If pictures were returned, the AOL Pictures user name (loginId) and caption for the first returned picture are extracted and copied into an HTML string for display in the taggedPhotoDiv <div> section of the web page.

Next, the URL of the medium-sized version of the photo is created, by concatenating the permalink parameter with &size=m. This URL is spliced into an HTML <img> element. The picHtml string is then inserted as the innerHTML data for the taggedPhotoDiv <div> element, and we're done!

Here are the top and bottom parts of the page that resulted when I entered "beagle" as my tag and clicked the submit button:

Figure 4. getPublicTaggedPhotos result for AOL Pictures tag "beagle"

Again, the unformatted JSON is difficult to read. See the AOL Pictures sample code for getTaggedPublicPhotos for a typical getTaggedPublicPhotos JSON result that has been formatted for human readability.

Conclusion

These applications were written to demonstrate simple methods for using the AOL Pictures JSON API getAlbumList and getTaggedPublicPhotos calls. Of course, there is much more that can be done using the AOL Pictures JSON API!

The developed applications can be used as templates for building new applications that apply the getPicturesByAlbumId, getPublicGallery, getPublicTagsByUser, and getTaggedPublicPhotosByUser JSON API calls. More complex applications that apply several of the JSON API functions could easily be built.

With the AOL Pictures APIs, AOL has provided developers with convenient capability for searching and accessing all public photos in the AOL Pictures archive.

Resources

The source code for the demo applications presented in this article are available for download in the file aolPictures1Code.zip.

References

• The AOL Pictures API home page
• AOL Pictures JSON API documentation
• AOL Pictures ATOM Feed API documentation
• AOL Pictures blog
• AOL Pictures forum
• AOL Pictures support forum