Finding Items on Lists

Customers create lists using "Your Account," which is a tab on www.amazon.com, as shown in the following figure..

Customers can create a variety of lists, including:

Wedding registry—Items the couple would like for their wedding.
Baby registry—Items wanted for a baby shower.
Listmaina—Items wanted that have a customer-specified theme
Wishlists—Items wanted for any occasion, such as a birthday or anniversary

Each list that a customer creates has a list ID, which is a positive integer. List IDs are unique by list type, that is, each Listmania list ID is guaranteed to be unique among all Listmania IDs. A Listmania ID could, for example, have the same value as a WishList ID.

Finding the items on a customer's list is typically a two-step process:

Find the customer's list ID by supplying that customer's name or e-mail address in the ListSearch operations.
Use the list ID you find in the ListLookup operation to find the items on the customer's lists

Topics

Finding the Customer's List ID

Given a customer's e-mail address or name, the ListSearch operation returns, among other things, the list IDs of a customer's public lists. Typically, entering an e-mail address yields more targeted results than entering the customer's name because e-mail addresses are unique. Often, however, a customer's e-mail address is not known so their name is used in the operation.

The following ListSearch request returns the list ID for John Smith.

http://ecs.amazonaws.com/onca/xml?
  Service=AWSECommerceService&
  AWSAccessKeyId=[Access Key ID]&
  Operation=ListSearch&
  ListType=WishList&
  Name=John%20Smith

Notice that the blank space between the first and last names is URL-encoded as %20.

The following is a snippet of the XML response to the sample request.

<List>
  <ListId>BB4444444477</ListId>
  <ListURL>http://www.amazon.com/gp/registry/BB4444444477</ListURL>
  <ListType>WishList</ListType>
  <TotalItems>70</TotalItems>
  <TotalPages>7</TotalPages>
  <DateCreated>1999-10-06</DateCreated>
  <CustomerName>John Smith</CustomerName>
</List>

The response contains the list ID, list type, date the list was created, the URL of the list, as well as the number of items on the list. Notice that the preceding response contains the ListURL element. You can paste this URL in a browser and see the items on the customer's list. The URL for each list type is the same with the exception of the last value, which is the list ID. That means that whenever you have a list ID, you can display it immediately. For more information, see Lists.

To find out more about the items on the list, use the ListId value in ListLookup.