Prev Next

ListSearch

Given a customer name or Email address, the ListSearch operation returns the associated list ID(s) but not the list items. To find those, use the list ID returned by ListSearch with ListLookup .

Specifying a full name or just a first or last name in the request typically returns multiple lists belonging to different people. Using Email as the identifier produces more filtered results.

Note:

Make sure to URL-encode the @ sign, as %40, in email addresses. Otherwise, the request will fail

Availability

All locales.

Request Parameters

For Wishlists and WeddingRegistry list types, you must specify one or more of the following parameters:

For the BabyRegistry list type, you must specify one or more of the following parameters:

You cannot, for example, retrieve a BabyRegistry by specifying an Email address or Name.

The following table describes the request parameters for ListSearch. Parameter names are case sensitive.

ParameterDefinitionReq'd?Valid Values
City City in which the list creator lives. No String. Use URL-encoded symbox for spaces (%20).
ContentType Specifies the kind of list you are retrieving. No

BabyRegistry

WeddingRegistry

Wishlist

Email Email address of the list creator. This parameter is not supported for the BabyRegistry. No Valid Email address. URL-encode the @ sign as %40.
FirstName First name of the list creator. ListSearch returns all list owners that have FirstName in thier first name. For example, specifying “John,” will return first names of “John,” Johnny,” and “Johnson.” No String. Use URL-encoded symbols for spaces (%20).
LastName Last name of the list creator. ListSearch returns all list owners that have LastName in their last name. For example, specifying “Ender,” will return the last names of “Ender,” Enders,” and “Enderson.” No String. Use URL-encoded symbols for spaces (%20).
ListPage Retrieve a specific page of list IDs. There are ten list IDs per page. The total number of pages is returned in the TotalPages response tag. The default is to return the first page. No Integer between 1 and 20.
State State in which the list creator lives. No String. Use URL-encoded symbox for spaces (20).
ResponseGroup Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas.No

Request (Default)

ListInfo (Default)

ListMinimum

ListSearch also accepts the parameters that all operations can use. For more information, see, Common Request Parameters

Response Tags

The following table describes the default response tags included in ListSearch responses.

Element TagDefinition
CustomerName Name of the list creator.
DateCreated Date the list was created.
List Container for list tags, including CustomerName, DateCreated, ListId, ListType, ListURL, TotalItems, TotalPages
ListId Alphanumeric token that uniquely identifies a list.
Lists Container for one or more List(s).
ListType The type of list: BabyRegistry, WeddingRegistry, or Wishlist.
ListURL URL of the list.
TotalItems Number of items on a list.
TotalPages Number of pages of lists. There are up to ten lists per page.
TotalResults Number of lists found.

For more information about the parent elements of these tags, see the appropriate response group in Response Groups

Sample Requests

Use ListSearch in the following ways:

Response to Sample Request

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

<TotalResults>2</TotalResults> 
<TotalPages>1</TotalPages>
<List>
  <List>
    <ListId>BR4444442H77</ListId> 
    <ListURL>http://www.amazon.com/gp/registry/BR4444442H77</ListURL> 
    <ListType>WishList</ListType> 
    <TotalItems>70</TotalItems> 
    <TotalPages>7</TotalPages> 
    <DateCreated>1999-10-06</DateCreated> 
    <CustomerName>John Smith</CustomerName> 
  </List>
  <List>
    <ListId>BR6666662H77</ListId> 
    <ListURL>http://www.amazon.com/gp/registry/BR6666662H77</ListURL> 
    <ListType>WishList</ListType> 
    <TotalItems>51</TotalItems> 
    <TotalPages>6</TotalPages> 
    <DateCreated>2002-10-02</DateCreated> 
    <CustomerName>John Smith</CustomerName> 
  </List>
</Lists>

Default responses provide summary information about the lists found. This example shows that John Smith has two Wishlists. The first, whose ListId is BR4444442H77, has 70 items in it. The second, whose ListId is BR6666662H77, has 51 items in it. To return the items on the Wishlists, use the ListLookup operation. with those list IDs.

The response also shows that if you know the ListId, you can look up the list directly using the URL: http://www.amazon.com/gp/registry/ListId. In the example above, the first ListId is BR4444442H77.

Note:

ListLookup cannot access items in a BabyRegistry. Currently, there is no way to display the items in a BabyRegistry.

Related Operations

Prev Copyright Information Next