AOL Pictures JSON API

Revised: July 31st, 2006

getAlbumList

Retrieves a list of all public albums for a given screenname.

Parameters

owner - A string specifying the album owner's screenname. The call will return a list of all public albums for this screenname. This parameter is required.
category - Limit results to the named category of albums. Valid categories are: "myAlbums", "aimPages", "blogs", and "memberProfile". This parameter is optional.
maxResults - An integer that specifies the maximum number of albums to return. This parameter is optional.

Sample call

http://api.pictures.aol.com/gv1/json/getAlbumList.do?owner=winterWoohoo

Sample Response

{ 
  "albums": [
    {
      "title": "Travels",
      "category": "aimPages",
      "creationDate": "Mon, 19 Jun 2006 12:57:54 -0800",
      "id": "aeVRhXusOtL1P2a9U6kbKJDqmBf4L92GMzxDvzOGjCK/jFCnkV3ciA==",
      "pictureCount": 4
    },
    { 
      "title": "Barbeque Party",
      "category": "aimPages",
      "creationDate": "Mon, 19 Jun 2006 12:56:51 -0800",
      "id": "aeVRhXusOtKPs7/i20yPNpDqmBf4L92GnR1KtrPRF62/jFCnkV3ciA==",
      "pictureCount": 5
    }
  ]
}

Decoding the Response

getAlbumList returns an array of albums. Each album has the following properties:

title - the user-created album title.
category - the category the album belongs to.
creationDate - the date on which the album was created. The date is formatted an an RFC 822 date string. This string can be used to instantiate a JavaScript or ActionScript Date object.
id - the server ID of the album. This id can be passed to the getAlbum call to retrieve pictures for the album.
pictureCount - the number of pictures in the album.

getAlbum

Retrieves picture data and album metadata for one AOL Pictures album.

Parameters

id - the id of the album to be returned. The album id contains characters that need to be URL-escaped before sending to the server. For example, in JavaScript, users must call encodeURIComponent() on the id that is returned by getAlbumList when using getAlbum.

Sample call

http://api.pictures.aol.com/gv1/json/getAlbum.do?id=mFQYMXJcDsVX%2BKJF5a9ZLdpkLUSEf2dWgsz9yokfTk%2BJJdNX5w59hg%3D%3D

Sample Response

{
  "title": "Endless Winter",
  "creationDate": "Mon, 17 Jul 2006 12:51:33 -0500",
  "id": "mFQYMXJcDsVX+KJF5a9ZLdpkLUSEf2dWgsz9yokfTk+JJdNX5w59hg==",
  "pictureCount": 3,
  "pictures": [
    {
      "creationDate": "Mon, 17 Jul 2006 12:51:33 -0500",
      "caption": "",
      "permalink": "http://links.pictures.aol.com/pic?id=5a70kV4KOAVzNQ-wVCHXSMZhPlUYuX7B-kZMv4xQp5Fd3Ig=",
      "id": "5a70kV4KOAVzNQ-wVCHXSMZhPlUYuX7B-kZMv4xQp5Fd3Ig=",
      "sizes": [
        {
          "width": 96,
          "height": 72,
          "url": "http://shutter04.pictures.aol.com:80/data/pictures/06/008/75/B4/85/F7/Y8is+DPsKG-JxKyEPadZdrKER4zlep320060.jpg"
        },
        {
          "width": 160,
          "height": 120,
          "url": "http://shutter04.pictures.aol.com:80/data/pictures/06/008/75/B4/85/F7/Y8is+DPsKG-JxKyEPadZdrKER4zlep3200A0.jpg"
        },
        {
          "width": 384,
          "height": 288,
          "url": "http://shutter04.pictures.aol.com:80/data/pictures/06/008/75/B4/85/F7/Y8is+DPsKG-JxKyEPadZdrKER4zlep320180.jpg"
        },
        {
          "width": 768,
          "height": 576,
          "url": "http://shutter04.pictures.aol.com:80/data/pictures/06/008/75/B4/85/F7/Y8is+DPsKG-JxKyEPadZdrKER4zlep320300.jpg"
        },
        {
          "width": 1600,
          "height": 1200,
          "url": "http://shutter04.pictures.aol.com:80/data/pictures/06/008/75/B4/85/F7/Y8is+DPsKG-JxKyEPadZdrKER4zlep320640.jpg"
        }
      ]
    },
    {
      "creationDate": "Mon, 17 Jul 2006 12:51:33 -0500",
      "caption": "",
      "permalink": "http://links.pictures.aol.com/pic?id=5a70kV4KOAVzNQ-wVCHXSMZhPm2OY4BqJwmjv4xQp5Fd3Ig=",
      "id": "5a70kV4KOAVzNQ-wVCHXSMZhPm2OY4BqJwmjv4xQp5Fd3Ig=",
      "sizes": [
        {
          "width": 96,
          "height": 72,
          "url": "http://shutter10.pictures.aol.com:80/data/pictures/05/004/56/1F/83/C9/KpZdbh5RgGiUYRQrq8UWq-aDu1k64w-90060.jpg"
        },
        {
          "width": 160,
          "height": 120,
          "url": "http://shutter10.pictures.aol.com:80/data/pictures/05/004/56/1F/83/C9/KpZdbh5RgGiUYRQrq8UWq-aDu1k64w-900A0.jpg"
        },
        {
          "width": 384,
          "height": 288,
          "url": "http://shutter10.pictures.aol.com:80/data/pictures/05/004/56/1F/83/C9/KpZdbh5RgGiUYRQrq8UWq-aDu1k64w-90180.jpg"
        },
        {
          "width": 768,
          "height": 576,
          "url": "http://shutter10.pictures.aol.com:80/data/pictures/05/004/56/1F/83/C9/KpZdbh5RgGiUYRQrq8UWq-aDu1k64w-90300.jpg"
        },
        {
          "width": 800,
          "height": 600,
          "url": "http://shutter10.pictures.aol.com:80/data/pictures/05/004/56/1F/83/C9/KpZdbh5RgGiUYRQrq8UWq-aDu1k64w-90320.jpg"
        }
      ]
    },
    {
      "creationDate": "Mon, 17 Jul 2006 12:51:33 -0500",
      "caption": "",
      "permalink": "http://links.pictures.aol.com/pic?id=5a70kV4KOAVzNQ-wVCHXSMZhPoNdBES7dyxBv4xQp5Fd3Ig=",
      "id": "5a70kV4KOAVzNQ-wVCHXSMZhPoNdBES7dyxBv4xQp5Fd3Ig=",	
      "sizes": [
        {
          "width": 72,
          "height": 96,
          "url": "http://shutter06.pictures.aol.com:80/data/pictures/05/006/7F/6A/91/0C/mVt3mdhKLlZGNcdS1PaNcnF+dgQUuByT0060.jpg"
        },
        {
          "width": 120,
          "height": 160,
          "url": "http://shutter06.pictures.aol.com:80/data/pictures/05/006/7F/6A/91/0C/mVt3mdhKLlZGNcdS1PaNcnF+dgQUuByT00A0.jpg"
        },
        {
          "width": 250,
          "height": 332,
          "url": "http://shutter06.pictures.aol.com:80/data/pictures/05/006/7F/6A/91/0C/mVt3mdhKLlZGNcdS1PaNcnF+dgQUuByT014C.jpg"
        },
        {
          "width": 250,
          "height": 332,
          "url": "http://shutter06.pictures.aol.com:80/data/pictures/05/006/7F/6A/91/0C/mVt3mdhKLlZGNcdS1PaNcnF+dgQUuByT014C.jpg"
        },
        {
          "width": 250,
          "height": 332,
          "url": "http://shutter06.pictures.aol.com:80/data/pictures/05/006/7F/6A/91/0C/mVt3mdhKLlZGNcdS1PaNcnF+dgQUuByT014C.jpg"
        }
      ]
    }
  ]
}

Decoding the Response

getAlbum returns metadata for one album, and an array of the album's pictures.

title - the user-created album title
creationDate - the date on which the album was created. The date is formatted an an RFC 822 date string.
id - the album ID. It contains characters that need to be URL-escaped before sending to the server.
editable - this parameter has been deprecated and should be ignored.
pictureCount - the number of pictures in the album.
pictures - an array of all pictures in the album.

Each picture in the pictures array has the following properties:

creationDate - the date the picture was created. The date is formatted an an RFC 822 date string.
caption - a user-created caption for the picture, or an empty string ("") if no caption has been entered.
id - the album ID. It contains characters that need to be URL-escaped before sending to the server.
sizes - an array of the image sizes that are available for the picture, in the order smallest to largest. AOL stores each picture at several different resolutions, based on the length of the longest edge in pixels. For each size, the array provides the height and width of the image in pixels, and the URL to retrieve that image size.

These image sizes are available for each picture, measured in pixels on the longest edge: 96, 160, 364, 768, and full size (the original picture resolution when it was uploaded to AOL Pictures). If the full-sized picture is small, the largest available size will be duplicated for larger sizes; refer to the last photo in the same response above for an example.
permalink - URL's that are returned in the sizes array refer directly to their storage location, using URL's that start with "shutterXX" (e.g. "http://shutter04.pictures.aol.com/...") These URL's are transient, and may change over time. They should only be used for the duration of an application session, and should not be stored or exposed to the end user.

Instead, the permalink provides a permanent link to the picture, i.e. an URL that is guaranteed not to change in the future. In order to make a permalink to a particular image size, you must append a "size" parameter to the URL with one of the following values (NB: The value must be lowercase):
- "s" (small, 96 px)
- "t" (thumbnail, 160px)
- "m" (medium, 364px)
- "l" (large, 768px)
- "f" (full-size image, original resolution)
The final permalink URL should look like this:
http://links.pictures.aol.com/pic?id=5a70kV4KOAVzNQ-wVCHXSMZhPuLaA8VzTr6gv4xQp5Fd3Ig=&size=m

About Us | Employment Opportunities | Webmaster.Info | Contact Us