ListSearch

Product Advertising API: 2009-11-01

previous page next page

ListSearch

Description

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] 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:

  • FirstName

  • LastName

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

Name Description Required
City

City in which the list creator lives.

Type: String. Use URL-encoded symbols for spaces (20).

Type: String

Default: None

 No
ContentType

Specifies the kind of list you are retrieving.

Type: String

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.

Type: String

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).

Type: String

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).

Type: String

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.

Type: String

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).

Type: String

Default: None

 No
State

State in which the list creator lives.

Type: String. Use URL-encoded symbols for spaces (20).

Type: String

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.

Type: String

Default: ListInfo

Valid Values: ListMinimum

No

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

Response

Name Description
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

Examples

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=John20Smith

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

The following request returns the WishList IDs for [email protected]. 

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

Sample Response

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

<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 preceding example, the first ListId is BR4444442H77.

[Note] Note

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

Related Operations

previous page start next page