Amazon E-Commerce Service (ECS) provides access to different types of content that customers create on the Amazon Web sites, including product and restaurant reviews, wish lists, and Listmania lists. Using the CustomerContentLookup, CustomerContentSearch, ListLookup, and ListSearch operations, you can retrieve content from specific Amazon customers.
US only.
The CustomerContentSearch operation searches for customers by name or email address. You must specify either a name or an email address, but not both.
For example, the REST request below would search for customers named "Smith".
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=CustomerContentSearch &Name=Smith
You can specify multiple names by separating them with URL-encoded spaces (%20) as shown in the REST request below which would search for John Smith.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=CustomerContentSearch &Name=Smith%20john
Note that capitalization and word order in the name are not significant.
The REST request below would search for a customer by email address.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=CustomerContentSearch &Email=jsmith@xyz.com
The CustomerContentSearch operation retrieves twenty customers at a time. If your search results in more than twenty customers, you can make multiple requests to retrieve additional blocks of twenty customers (pages). In the case of CustomerContentSearch, you can page through customers with the CustomerPage parameter as shown in the table below.
| Parameter | Default Page Num. | Items Per Page | Valid Values | Description |
|---|---|---|---|---|
| CustomerPage | 1 | 20 | 1..20 | Customers. Up to 20 pages of customers can be returned (20 per page). |
If this parameter is omitted, only the first page is returned. However the data also indicates the number of customers (and the number of pages) so that additional pages can be retrieved if desired.
US only.
The CustomerContentLookup operation returns only information that customers have chosen to make public on Amazon. No credit card, address, email, billing or transaction data is available. All that is available is (as permitted by the customer) their name, location (city/state), wish list ID, customer-written reviews, nickname and birthday.
Customer ID values are returned from customer operations like CustomerContentLookup, CustomerContentSearch, ListLookup and ListSearch as well as ItemSearch, ItemLookup and SimilarityLookup which include customer reviews, SellerListingSearch and SellerListingLookup which include customer feedback.
Amazon does not link a customer ID with any remote shopping carts that your application or Web site has created, and customer IDs cannot be used to search for shopping carts.
To look up a customer, submit a REST request that looks like the one shown below.
| US |
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[ID]
&Operation=CustomerContentLookup
&CustomerId=[ID]
|
By default, this returns basic customer information including location (city/state), name and nickname (as permitted by the customer).
You may request additional information by setting the ResponseGroup parameter. The ResponseGroup parameter for CustomerContentLookup has five allowed values:
For full customer information, you would thus submit a REST request like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=CustomerContentLookup &CustomerId=[ID] &ResponseGroup=Request,CustomerFull
The first ten customer-written reviews will be returned with this request. If Customer/TotalPages indicates the number of pages of reviews available, and if it is larger than one, you can see additional pages of feedback (with ten feedback records per page) by submitting additional REST requests like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=CustomerContentLookup &CustomerId=[ID] &ReviewPage=2
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=CustomerContentLookup &CustomerId=[ID] &ReviewPage=3
You can see up to ten pages (100 total review entries, at ten per page) of reviews.
You can search for wish lists, baby registry lists or wedding registry lists with the ListSearch operation.
| Parameter | Value |
|---|---|
| Operation | ListSearch |
| ListType | WishList, WeddingRegistry or BabyRegistry |
When searching for lists, you can search by the criteria specified by the parameters:
Name
FirstName
LastName
City
State
Your search request for wish lists and wedding registry lists MUST contain one of: Name, FirstName, LastName or Email.
Your search request for baby registry lists MUST contain one of: FirstName, LastName. (Name and Email are ignored when searching for baby registries).
For example, the REST request below would search for baby registry lists for anyone named Smith.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService &SubscriptionId=[ID] &Operation=ListSearch &LastName=Smith &ListType=BabyRegistry
The ListSearch operation retrieves ten lists at a time. If your search results in more than ten lists, you can make multiple requests to retrieve additional blocks of ten lists (pages). In the case of ListSearch, you can page through lists with the ListPage parameter as shown in the table below.
| Parameter | Default Page Number | Items per page | Valid Values | Description |
|---|---|---|---|---|
| ListPage | 1 | 10 | 1..20 | Lists. Up to 20 pages of lists can be returned (10 per page). |
If this parameter is omitted, only the first page is returned. However the data also indicates the number of lists (and the number of pages) so that additional pages can be retrieved if desired.
You can retrieve a wish list or Listmania list through the ListLookup operation. Each operation request looks up a single list and returns a List/ListItem/Item element for each item on the list. The List/ListItem/Item element contains the same elements as an Items/Item or a Variations/Item element and consequently the same response groups are available to this operation as are available to the ItemSearch operation.
ListLookup does not support lookups of baby or wedding registries or So you'd like to lists.
The usual parameters for a ListLookup operation are listed in the table below.
| ListLookup Parameter | Value |
|---|---|
| Operation | ListLookup |
| ListType | Listmania or WishList |
| ListId | List ID |
Since both Listmania lists and wish lists are collections of Amazon products, the data returned is a series of ListItem elements containing customer comments and quantities along with an Item element for the product itself.
For example, if you know the wish list ID for a customer, you can use the REST request below to get a list of the products on the wish list.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ListLookup &ListId=[ID] &ListType=WishList
Lists are returned to you as a list of products, similar to the manner in which products are returned from an ItemSearch. You can thus use some of the ItemSearch parameters to filter the products on the list to only return products that match your criteria, as described below.
Wish lists can be filtered by product group so that only books, music, video, etc. are returned. For example, if you wanted to see only books, you would make a REST request that looked like this:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ListLookup &ListId=[ID] &ListType=WishList
&ProductGroup=books
In addition, wish lists can be returned to you sorted. The Sort parameter takes three values:
| Price | Sorts from high to low, based on list/new price. |
| DateAdded | Default. Sorts from most recent to oldest. |
| LastUpdated | Sorts from most recently updated to oldest. |
For example,
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ListLookup &ListId=[ID] &ListType=WishList
&ResponseGroup=Large,OfferFull &Sort=Price
&MerchantId=All
returns all of the items on the wish list, sorted by price.
For both wish lists and Listmania lists, you can control what offer data is returned for the products on the list. All of the items on the list will be returned, but only offers from specified merchants and for specified product conditions (new, used, etc.) will be returned.
By default, if no MerchantId or Condition parameter is specified, ECS assumes that MerchantId is Amazon and Condition is New. Values for these parameters are shown in the table below.
| Parameter | Default | Valid Values |
|---|---|---|
| MerchantId | Amazon |
US/DE/UK/JP - All or Amazon Additional values for US only - Featured or a merchant ID |
| Condition | New | All, New, Used, Refurbished, or Collectible |
For example, to return only the Amazon product offers for used books, you would use this REST request:
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ListLookup &ListId=[ID] &ListType=WishList
&ProductGroup=Book &Condition=Used &ResponseGroup=Medium,Offers
This request would return no offer data because Amazon does not carry any used books. However since the request specifically requests Amazon (by default, since no merchant ID is specified), you will receive no offers.
This REST request would actually return offers by setting MerchantId to All.
http://webservices.amazon.com/onca/xml?Service=AWSECommerceService
&SubscriptionId=[your subscription ID here]
&Operation=ListLookup &ListId=[ID] &ListType=WishList
&ProductGroup=Book &Condition=Used &ResponseGroup=Medium,Offers
&MerchantId=All
The DeliveryMethod parameter filters offers returned in the product list by delivery method. Valid values for the DeliveryMethod parameter are: Ship and ISPU (in-store pickup). The default value is Ship.
If you specify ISPU, you will get offers returned from any postal code. To get items from specific postal codes, you must make a separate ItemLookup request for the item.
All ECS operations support the ResponseGroup parameter which specifies the data subset to be returned. Since Item elements are returned by ListLookup, the response groups are similar to the response groups for ItemLookup, listed below. If no response groups are specified in a ListLookup operation, the default is Request and ListInfo.
Standard response groups:
Amalgamated response groups:
Small - Global, item-level data (no pricing or availability), including the ASIN, product title, creator (author, artist, composer, directory, manufacturer, etc.), product group, URL, and manufacturer.
Medium - Includes Small, Request, ItemAttributes, OfferSummary, SalesRank, EditorialReview, and Images response groups.
Large - Includes Medium, Tracks, BrowseNodes, Reviews, istmaniaLists, Similarities, Offers, and Accessories response groups.
Offer information (actual prices/availability):
Offers - Includes OfferSummary plus all offer listings specified by the Condition parameter
OfferFull - Includes Offers plus merchant name or seller nickname.
Variations data management:
Variations - Includes VariationMinimum and VariationSummary response groups plus other details
Various product attributes:
Plus the list-based response groups:
The ListLookup operation retrieves ten list entries at a time. If the list you are looking up contains more than ten items, you can make multiple requests to retrieve additional blocks of ten entries (pages). In the case of ListLookup, you can page through products with the ProductPage parameter as shown in the table below.
| Parameter | Default Page Num. | Items per page | Valid Values | Description |
|---|---|---|---|---|
| ProductPage | 1 | 10 | 1..30 | Products. Up to 30 pages of products can be returned (10 per page). |
If this parameter is omitted, only the first page is returned. However the data also indicates the number of products (and the number of pages) so that additional pages can be retrieved if desired.
ListLookup returns data similar to ItemLookup. If you don't get the returned data that you expect, the most common culprit is a response group that does not include the data you require.
If you are attempting to find out if a product can be purchased, you must be sure to include the appropriate response group (Offers, OfferSummary or OfferFull) but you must also set the MerchantId parameter appropriately.
For debugging purposes, no single response group returns all of the data. However for ListLookup, setting the ResponseGroup parameter to include Large, Offers, Variations and ListFull will return all available data. This may result in very a very large response, but for debugging, it's an ideal way to look at all of the available data.