ListSearch

Given a customer name or e-mail 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 e-mail 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:

e-mail
FirstName
LastName
Name

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

FirstName
LastName

You cannot, for example, retrieve a BabyRegistry by specifying an e-mail address or Name.

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

Parameter	Definition	Required
`City`	City in which the list creator lives. Type: String. Use URL-encoded symbols for spaces (%20). Default: None	No
`ContentType`	Specifies the kind of list you are retrieving. Default: None Valid Values: BabyRegistry WeddingRegistry Wishlist	No
`e-mail`	e-mail address of the list creator. This parameter is not supported for the BabyRegistry. Default: None Valid Values: Valid e-mail address. URL-encode the @ sign as %40.	No
`FirstName`	First name of the list creator. ListSearch returns all list owners that have FirstName in their first name. For example, specifying “John,” will return first names of “John,” Johnny,” and “Johnson.” Type:String. Use URL-encoded symbols for spaces (%20). Default: None	No
`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.” Type: String. Use URL-encoded symbols for spaces (%20). Default: None	No
`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. Default: None Valid Values: Integer between 1 and 20.	No
`Name`	Name of the list creator. This parameter is not supported for the BabyRegistry. Type: String. Use URL-encoded symbols for spaces (%20). Default: None	No
`State`	State in which the list creator lives. Type: String. Use URL-encoded symbols for spaces (20). Default: None	No
`ResponseGroup`	Specifies the types of values to return. You can specify multiple response groups in one request by separating them with commas. Default: ListInfo Valid Values: ListMinimum	No

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 Tag	Definition
`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:

The following request returns the WishList IDs for John Smith.

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

The response to this request is shown in, Response to Sample Request, below.

The following request returns the WishList IDs for JohnSmith@ISP.com.

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
AWSAccessKeyId=[Access Key ID]&
Operation=ListSearch&
ListType=WishList&
e-mail=JohnSmith%40ISP.com

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

ListLookup