com.amazonaws.a2s
Class AmazonA2SClient

java.lang.Object
  extended by com.amazonaws.a2s.AmazonA2SClient
All Implemented Interfaces:
AmazonA2S

public class AmazonA2SClient
extends java.lang.Object
implements AmazonA2S

Amazon Associates Web Service (A2S) is the best way to make money on the Internet. Amazon has spent ten years and hundreds of millions of dollars developing a world-class web service that millions of customers use every day. As a developer, you can build A2S applications that leverage this robust, scalable, and reliable technology. You get access to much of the data that is used by Amazon, including the items for sale, customer reviews, seller reviews, as well as most of the functionality that you see on www.amazon.com, such as finding items, finding similar items, displaying customer reviews, and product promotions. In short, A2S operations open the doors to Amazon's databases so that you can take advantage of Amazon's sophisticated E-commerce data and functionality. Build your own web store to sell Amazon items or your own items.

Best of all, A2S is free. By signing up to become a A2S developer, you join the tens of thousands of developers who are already realizing financial gains by creating A2S-driven applications and web stores. In 2006, A2S developers sold well over $600 million worth of items. Would you like a percentage of that revenue?

E-commerce is the practice of conducting business over the Internet. This guide explains in detail how you can use A2S operations to create storefronts in which you enable Internet customers to search for your items, see pictures of them, find related items, get customer reviews, and purchase items.

With e-commerce, the barrier of distance between the shopper and the store goes away: the local video store must compete with stores across the country. E-commerce levels the playing field: the web site of an individual seller can appear as sophisticated and intoxicating as that of a major retailer. A2S is your opportunity to enter the world market where patronage is not limited by the size of your storefront, foot traffic or locality. Welcome to the world of A2S E-commerce. AmazonA2SClient is the implementation of AmazonA2S based on the Apache HttpClient.


Constructor Summary
AmazonA2SClient(java.lang.String awsAccessKeyId, java.lang.String associateTag)
          Constructs AmazonA2SClient with AWS Access Key ID and Accociate Tag
AmazonA2SClient(java.lang.String awsAccessKeyId, java.lang.String associateTag, AmazonA2SLocale locale)
          Constructs AmazonA2SClient with AWS Access Key ID, Associate Tag and specific service locale
 
Method Summary
 BrowseNodeLookupResponse browseNodeLookup(BrowseNodeLookupRequest... request)
          Browse Node Lookup Request

Given a browse node ID, BrowseNodeLookup returns the specified browse node's name, children, and ancestors.
 CartAddResponse cartAdd(CartAddRequest... request)
          Cart Add Request

The CartAdd operation enables you to add items to an existing remote shopping cart.
 CartClearResponse cartClear(CartClearRequest... request)
          Cart Clear Request

The CartClear operation enables you to remove all of the items in a remote shopping cart, including SavedForLater items.
 CartCreateResponse cartCreate(CartCreateRequest... request)
          Cart Create Request

The CartCreate operation enables you to create a remote shopping cart.
 CartGetResponse cartGet(CartGetRequest... request)
          Cart Get Request

The CartGet operation enables you to retrieve the IDs, quantities, and prices of all of the items, including SavedForLater items in a remote shopping cart.
 CartModifyResponse cartModify(CartModifyRequest... request)
          Cart Modify Request

The CartModify operation enables you to:

Change the quantity of items that are already in a remote shopping cart. Move items from the active area of a cart to the SaveForLater area or the reverse Change the MergeCart setting.
 CustomerContentLookupResponse customerContentLookup(CustomerContentLookupRequest... request)
          Customer Content Lookup Request

For a given customer ID, the CustomerContentLookup operation retrieves all of the information a customer has made public about themselves on Amazon.
 CustomerContentSearchResponse customerContentSearch(CustomerContentSearchRequest... request)
          Customer Content Search Request

For a given customer Email address or name, the CustomerContentSearch operation returns matching customer IDs, names, nicknames, and residence information (city, state, and country).
 HelpResponse help(HelpRequest... request)
          Help Request

The Help operation provides information about A2S operations and response groups.
 ItemLookupResponse itemLookup(ItemLookupRequest... request)
          Item Lookup Request

Given an Item identifier, the ItemLookup operation returns some or all of the item attributes, depending on the response group specified in the request.
 ItemSearchResponse itemSearch(ItemSearchRequest... request)
          Item Search Request

The ItemSearch operation returns items that satisfy the search criteria, including one or more search indices

ItemSearch returns up to ten search results at a time.
 ListLookupResponse listLookup(ListLookupRequest... request)
          List Lookup Request

The ListLookup operation returns, by default, summary information about a list that you specify in the request.
 ListSearchResponse listSearch(ListSearchRequest... request)
          List Search Request

Given a customer name or Email address, the ListSearch operation returns the associated list ID(s) but not the list items.
 SellerListingLookupResponse sellerListingLookup(SellerListingLookupRequest... request)
          Seller Listing Lookup Request

The SellerListingLookup operation enables you to return information about a seller's listings, including product descriptions, availability, condition, and quantity available.
 SellerListingSearchResponse sellerListingSearch(SellerListingSearchRequest... request)
          Seller Listing Search Request

The SellerListingSearch operation enables you to search for items offered by specific sellers.
 SellerLookupResponse sellerLookup(SellerLookupRequest... request)
          Seller Lookup Request

The SellerLookup operation returns detailed information about sellers and, in the US locale, merchants.
 SimilarityLookupResponse similarityLookup(SimilarityLookupRequest... request)
          Similarity Lookup Request

The SimilarityLookup operation returns up to ten products per page that are similar to one or more items specified in the request.
 TagLookupResponse tagLookup(TagLookupRequest... request)
          Tag Lookup Request

The TagLookup operation returns entities based on specifying one to five tags.
 TransactionLookupResponse transactionLookup(TransactionLookupRequest... request)
          Transaction Lookup Request

The TransactionLookup operation returns information about up to ten purchases that have already taken place.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AmazonA2SClient

public AmazonA2SClient(java.lang.String awsAccessKeyId,
                       java.lang.String associateTag)
Constructs AmazonA2SClient with AWS Access Key ID and Accociate Tag

Parameters:
awsAccessKeyId - AWS Access Key ID
associateTag - Associate Tag

AmazonA2SClient

public AmazonA2SClient(java.lang.String awsAccessKeyId,
                       java.lang.String associateTag,
                       AmazonA2SLocale locale)
Constructs AmazonA2SClient with AWS Access Key ID, Associate Tag and specific service locale

Parameters:
awsAccessKeyId - AWS Access Key ID
associateTag - Associate Tag
locale - Locale you wish to invoke the service call at. Supported Locales are: US, UK, DE, FR, CA, JP. Note, not all operations supported by all locales. Please refer to Amazon A2S documentation for more information
Method Detail

help

public HelpResponse help(HelpRequest... request)
                  throws AmazonA2SException
Help Request

The Help operation provides information about A2S operations and response groups. For operations, Help lists required and optional request parameters, as well as default and optional response groups the operation can use. For response groups, Help lists the operations that can use the response group as well as the response tags returned by the response group in the XML response.

The Help operation is not often used in customer applications. It can, however, be used to help the developer in the following ways:



Available Response Groups:

Specified by:
help in interface AmazonA2S
Parameters:
request - Help Request
Returns:
Help Response from the service
Throws:
AmazonA2SException

itemSearch

public ItemSearchResponse itemSearch(ItemSearchRequest... request)
                              throws AmazonA2SException
Item Search Request

The ItemSearch operation returns items that satisfy the search criteria, including one or more search indices

ItemSearch returns up to ten search results at a time. When condition equals "All," ItemSearch returns up to three offers per condition (if they exist), for example, three new, three used, three refurbished, and three collectible items. Or, for example, if there are no collectible or refurbished offers, ItemSearch returns three new and three used offers.

Because there are thousands of items in each search index, ItemSearch requires that you specify the value for at least one parameter in addition to a search index. The additional parameter value must reference items within the specified search index. For example, you might specify a browse node (BrowseNode is an ItemSearch parameter), Harry Potter Books, within the Books product category. You would not get results, for example, if you specified the search index to be Automotive and the browse node to be Harry Potter Books. In this case, the parameter value is not associated with the search index value.

The ItemPage parameter enables you to return a specified page of results. The maximum ItemPage number that can be returned is 400. An error is returned if you try to access higher numbered pages. If you do not include ItemPage in your request, the first page will be returned by default. There can be up to ten items per page.

ItemSearch is the operation that is used most often in requests. In general, when trying to find an item for sale, you use this operation.

Available Response Groups:

Specified by:
itemSearch in interface AmazonA2S
Parameters:
request - ItemSearch Request
Returns:
ItemSearch Response from the service
Throws:
AmazonA2SException

itemLookup

public ItemLookupResponse itemLookup(ItemLookupRequest... request)
                              throws AmazonA2SException
Item Lookup Request

Given an Item identifier, the ItemLookup operation returns some or all of the item attributes, depending on the response group specified in the request. By default, ItemLookup returns an item's ASIN, DetailPageURL, Manufacturer, ProductGroup, and Title of the item.

ItemLookup supports many response groups, so you can retrieve many different kinds of product information, called item attributes, including product reviews, variations, similar products, pricing, availability, images of products, accessories, and other information.

To look up more than one item at a time, separate the item identifiers by commas.

Available Response Groups:

Specified by:
itemLookup in interface AmazonA2S
Parameters:
request - ItemLookup Request
Returns:
ItemLookup Response from the service
Throws:
AmazonA2SException

browseNodeLookup

public BrowseNodeLookupResponse browseNodeLookup(BrowseNodeLookupRequest... request)
                                          throws AmazonA2SException
Browse Node Lookup Request

Given a browse node ID, BrowseNodeLookup returns the specified browse node's name, children, and ancestors. The names and browse node IDs of the children and ancestor browse nodes are also returned. BrowseNodeLookup enables you to traverse the browse node hierarchy to find a browse node. As you traverse down the hierarchy, you refine your search and limit the number of items returned. For example, you might traverse the following hierarchy: DVD Used DVDs Kids and Family, to select out of all the DVDs offered by Amazon only those that are appropriate for family viewing. Returning the items associated with Kids and Family produces a much more targeted result than a search based at the level of Used DVDs.

Alternatively, by traversing up the browse node tree, you can determine the root category of an item. You might do that, for example, to return the top seller of the root product category using the TopSeller response group in an ItemSearch request.

You can use BrowseNodeLookup iteratively to navigate through the browse node hierarchy to reach the node that most appropriately suits your search. Then you can use the browse node ID in an ItemSearch request. This response would be far more targeted than, for example, searching through all of the browse nodes in a search index.

Available Response Groups:

Specified by:
browseNodeLookup in interface AmazonA2S
Parameters:
request - BrowseNodeLookup Request
Returns:
BrowseNodeLookup Response from the service
Throws:
AmazonA2SException

listSearch

public ListSearchResponse listSearch(ListSearchRequest... request)
                              throws AmazonA2SException
List Search Request

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.

Available Response Groups:

Specified by:
listSearch in interface AmazonA2S
Parameters:
request - ListSearch Request
Returns:
ListSearch Response from the service
Throws:
AmazonA2SException

listLookup

public ListLookupResponse listLookup(ListLookupRequest... request)
                              throws AmazonA2SException
List Lookup Request

The ListLookup operation returns, by default, summary information about a list that you specify in the request. The summary information includes the:



The operation returns up to ten sets of summary information per page.

Lists are specified by list type and list ID, which can be found using ListSearch.

You cannot lookup more than one list at a time in a single request. You can, however, make a batch request to look for more than one list simultaneously.

Available Response Groups:

Specified by:
listLookup in interface AmazonA2S
Parameters:
request - ListLookup Request
Returns:
ListLookup Response from the service
Throws:
AmazonA2SException

customerContentSearch

public CustomerContentSearchResponse customerContentSearch(CustomerContentSearchRequest... request)
                                                    throws AmazonA2SException
Customer Content Search Request

For a given customer Email address or name, the CustomerContentSearch operation returns matching customer IDs, names, nicknames, and residence information (city, state, and country). In general, supplying an Email address returns unique results whereas supplying a name more often returns multiple results.

Often you use CustomerContentSearch to find a customer ID that you can use in the CustomerContentLookup operation, which returns more extensive customer information.

Available Response Groups:

Specified by:
customerContentSearch in interface AmazonA2S
Parameters:
request - CustomerContentSearch Request
Returns:
CustomerContentSearch Response from the service
Throws:
AmazonA2SException

customerContentLookup

public CustomerContentLookupResponse customerContentLookup(CustomerContentLookupRequest... request)
                                                    throws AmazonA2SException
Customer Content Lookup Request

For a given customer ID, the CustomerContentLookup operation retrieves all of the information a customer has made public about themselves on Amazon. Such information includes some or all of the following:



To find a customer ID, use the CustomerContentSearch operation.

Available Response Groups:

Specified by:
customerContentLookup in interface AmazonA2S
Parameters:
request - CustomerContentLookup Request
Returns:
CustomerContentLookup Response from the service
Throws:
AmazonA2SException

similarityLookup

public SimilarityLookupResponse similarityLookup(SimilarityLookupRequest... request)
                                          throws AmazonA2SException
Similarity Lookup Request

The SimilarityLookup operation returns up to ten products per page that are similar to one or more items specified in the request. This operation is typically used to pique a customer's interest in buying something similar to what they've already ordered.

If you specify more than one item, SimilarityLookup returns the intersection of similar items each item would return separately. Alternatively, you can use the SimilarityType parameter to return the union of items that are similar to any of the specified items. A maximum of ten similar items are returned; the operation does not return additional pages of similar items. if there are more than ten similar items, running the same request can result in different answers because the ten that are included in the response are picked randomly.

Available Response Groups:

Specified by:
similarityLookup in interface AmazonA2S
Parameters:
request - SimilarityLookup Request
Returns:
SimilarityLookup Response from the service
Throws:
AmazonA2SException

sellerLookup

public SellerLookupResponse sellerLookup(SellerLookupRequest... request)
                                  throws AmazonA2SException
Seller Lookup Request

The SellerLookup operation returns detailed information about sellers and, in the US locale, merchants. To lookup a seller, you must use their seller ID. The information returned includes the seller's name, location, average rating by customers, and the first five customer feedback entries. SellerLookup will not, however, return the seller's Email or business addresses.

Available Response Groups:

Specified by:
sellerLookup in interface AmazonA2S
Parameters:
request - SellerLookup Request
Returns:
SellerLookup Response from the service
Throws:
AmazonA2SException

cartGet

public CartGetResponse cartGet(CartGetRequest... request)
                        throws AmazonA2SException
Cart Get Request

The CartGet operation enables you to retrieve the IDs, quantities, and prices of all of the items, including SavedForLater items in a remote shopping cart.

Because the contents of a cart can change for different reasons, such as availability, you should not keep a copy of a cart locally. Instead, use CartGet to retrieve the items in a remote shopping cart.

To retrieve the items in a cart, you must specify the cart using the CartId and HMAC values, which are returned in the CartCreate operation. A value similar to HMAC, URLEncodedHMAC, is also returned. This value is the URL encoded version of the HMAC. This encoding is necessary because some characters, such as + and /, cannot be included in a URL. Rather than encoding the HMAC yourself, use the URLEncodedHMAC value for the HMAC parameter.

CartGet does not work after the customer has used the PurchaseURL to either purchase the items or merge them with the items in their Amazon cart.

If the associated CartCreate request specified an AssociateTag, all CartGet requests must also include a value for AssociateTag otherwise the request will fail.

Available Response Groups:

Specified by:
cartGet in interface AmazonA2S
Parameters:
request - CartGet Request
Returns:
CartGet Response from the service
Throws:
AmazonA2SException

cartAdd

public CartAddResponse cartAdd(CartAddRequest... request)
                        throws AmazonA2SException
Cart Add Request

The CartAdd operation enables you to add items to an existing remote shopping cart. CartAdd can only be used to place a new item in a shopping cart. It cannot be used to increase the quantity of an item already in the cart. If you would like to increase the quantity of an item that is already in the cart, you must use the CartModify operation.

You add an item to a cart by specifying the item's OfferListingId, or ASIN and ListItemId. Once in a cart, an item can only be identified by its CartItemId. That is, an item in a cart cannot be accessed by its ASIN or OfferListingId. CartItemId is returned by CartCreate, CartGet, and CartAdd.

To add items to a cart, you must specify the cart using the CartId and HMAC values, which are returned by the CartCreate operation.

If the associated CartCreate request specified an AssociateTag, all CartAdd requests must also include a value for Associate Tag otherwise the request will fail.

Available Response Groups:

Specified by:
cartAdd in interface AmazonA2S
Parameters:
request - CartAdd Request
Returns:
CartAdd Response from the service
Throws:
AmazonA2SException

cartCreate

public CartCreateResponse cartCreate(CartCreateRequest... request)
                              throws AmazonA2SException
Cart Create Request

The CartCreate operation enables you to create a remote shopping cart. A shopping cart is the metaphor used by most e-commerce solutions. It is a temporary data storage structure that resides on Amazon servers. The structure contains the items a customer wants to buy. In A2S, the shopping cart is considered remote because it is hosted by Amazon servers. In this way, the cart is remote to the vendor's web site where the customer views and selects the items they want to purchase.

Once you add an item to a cart by specifying the item's ListItemId and ASIN, or OfferListing ID, the item is assigned a CartItemId and accessible only by that value. That is, in subsequent requests, an item in a cart cannot be accessed by its ListItemId and ASIN, or OfferListingId. CartItemId is returned by CartCreate , CartGet , and CartAdd .

Because the contents of a cart can change for different reasons, such as item availability, you should not keep a copy of a cart locally. Instead, use the other cart operations to modify the cart contents. For example, to retrieve contents of the cart, which are represented by CartItemIds, use CartGet .

Available products are added as cart items. Unavailable items, for example, items out of stock, discontinued, or future releases, are added as SaveForLaterItems. No error is generated. The Amazon database changes regularly. You may find a product with an offer listing ID but by the time the item is added to the cart the product is no longer available. The checkout page in the Order Pipeline clearly lists items that are available and those that are SaveForLaterItems.

It is impossible to create an empty shopping cart. You have to add at least one item to a shopping cart using a single CartCreate request. You can add specific quantities (up to 999) of each item.

CartCreate can be used only once in the life cycle of a cart. To modify the contents of the cart, use one of the other cart operations.

Carts cannot be deleted. They expire automatically after being unused for 7 days. The lifespan of a cart restarts, however, every time a cart is modified. In this way, a cart can last for more than 7 days. If, for example, on day 6, the customer modifies a cart, the 7 day countdown starts over.

Available Response Groups:

Specified by:
cartCreate in interface AmazonA2S
Parameters:
request - CartCreate Request
Returns:
CartCreate Response from the service
Throws:
AmazonA2SException

cartModify

public CartModifyResponse cartModify(CartModifyRequest... request)
                              throws AmazonA2SException
Cart Modify Request

The CartModify operation enables you to:



To modify the number of items in a cart, you must specify the cart using the CartId and HMAC values that are returned in the CartCreate operation. A value similar to HMAC, URLEncodedHMAC, is also returned. This value is the URL encoded version of the HMAC. This encoding is necessary because some characters, such as + and /, cannot be included in a URL. Rather than encoding the HMAC yourself, use the URLEncodedHMAC value for the HMAC parameter.

You can use CartModify to modify the number of items in a remote shopping cart by setting the value of the Quantity parameter appropriately. You can eliminate an item from a cart by setting the value of the Quantity parameter to zero. Or, you can double the number of a particular item in the cart by doubling its Quantity . You cannot, however, use CartModify to add new items to a cart.

If the associated CartCreate request specified an AssociateTag, all CartModify requests must also include a value for Associate Tag otherwise the request will fail.

Available Response Groups:

Specified by:
cartModify in interface AmazonA2S
Parameters:
request - CartModify Request
Returns:
CartModify Response from the service
Throws:
AmazonA2SException

cartClear

public CartClearResponse cartClear(CartClearRequest... request)
                            throws AmazonA2SException
Cart Clear Request

The CartClear operation enables you to remove all of the items in a remote shopping cart, including SavedForLater items. To remove only some of the items in a cart or to reduce the quantity of one or more items, use CartModify .

To delete all of the items from a remote shopping cart, you must specify the cart using the CartId and HMAC values, which are returned by the CartCreate operation. A value similar to the HMAC, URLEncodedHMAC, is also returned. This value is the URL encoded version of the HMAC. This encoding is necessary because some characters, such as + and /, cannot be included in a URL. Rather than encoding the HMAC yourself, use the URLEncodedHMAC value for the HMAC parameter.

CartClear does not work after the customer has used the PurchaseURL to either purchase the items or merge them with the items in their Amazon cart.

Carts exist even though they have been emptied. The lifespan of a cart is 7 days since the last time it was acted upon. For example, if a cart created 6 days ago is modified, the cart lifespan is reset to 7 days.

Available Response Groups:

Specified by:
cartClear in interface AmazonA2S
Parameters:
request - CartClear Request
Returns:
CartClear Response from the service
Throws:
AmazonA2SException

transactionLookup

public TransactionLookupResponse transactionLookup(TransactionLookupRequest... request)
                                            throws AmazonA2SException
Transaction Lookup Request

The TransactionLookup operation returns information about up to ten purchases that have already taken place. Transaction IDs are created whenever a purchase request is made by a customer.

For a specified transaction ID, TransactionLookup returns:

For privacy reasons, this operation does not return information about the customer who purchased the items.

Available Response Groups:

Specified by:
transactionLookup in interface AmazonA2S
Parameters:
request - TransactionLookup Request
Returns:
TransactionLookup Response from the service
Throws:
AmazonA2SException

sellerListingSearch

public SellerListingSearchResponse sellerListingSearch(SellerListingSearchRequest... request)
                                                throws AmazonA2SException
Seller Listing Search Request

The SellerListingSearch operation enables you to search for items offered by specific sellers. You cannot use SellerListingSearch to look up items sold by merchants. To look up an item sold by a merchant, use ItemLookup or ItemSearch along with the MerchantId parameter.

SellerListingSearch returns the listing ID or exchange ID of an item. Typically, you use those values with SellerListingLookup to find out more about those items.

Each SellerListingSearch request returns up to ten items. By default, the first ten items are returned. You can use the ListingPage parameter to retrieve additional pages of (up to) ten listings.

To use A2S, sellers must have less than 100,000 items for sale. Sellers that have more items for sale should use, instead of A2S, other seller APIs, including the Amazon Inventory Management System, and the Merchant@ API.

Available Response Groups:

Specified by:
sellerListingSearch in interface AmazonA2S
Parameters:
request - SellerListingSearch Request
Returns:
SellerListingSearch Response from the service
Throws:
AmazonA2SException

sellerListingLookup

public SellerListingLookupResponse sellerListingLookup(SellerListingLookupRequest... request)
                                                throws AmazonA2SException
Seller Listing Lookup Request

The SellerListingLookup operation enables you to return information about a seller's listings, including product descriptions, availability, condition, and quantity available. The response also includes the seller's nickname. Each request requires a seller ID.

You can also find a seller's items using ItemLookup. There are, however, some reasons why it is better to use SellerListingLookup:



This operation only works with sellers who have less than 100,000 items for sale. Sellers that have more items for sale should use, instead of A2S, other APIs, including the Amazon Inventory Management System, and the Merchant@ API.

Available Response Groups:

Specified by:
sellerListingLookup in interface AmazonA2S
Parameters:
request - SellerListingLookup Request
Returns:
SellerListingLookup Response from the service
Throws:
AmazonA2SException

tagLookup

public TagLookupResponse tagLookup(TagLookupRequest... request)
                            throws AmazonA2SException
Tag Lookup Request

The TagLookup operation returns entities based on specifying one to five tags. A tag is a descriptive word that a customer uses to label entities on Amazon's retail website. Entities can be items for sale, Listmania lists, guides, and so forth. For example, a customer might tag a given entity with the phrase, "BestCookbook." For more information, see Tags.

In the tag-related response groups, Tags and TagSummary specify the amount of informtion returned. The other tag-related response groups, TaggedGuides, TaggedItems, and Tagged listmaniaLists, specify the kind of entity tagged.

Available Response Groups:

Specified by:
tagLookup in interface AmazonA2S
Parameters:
request - TagLookup Request
Returns:
TagLookup Response from the service
Throws:
AmazonA2SException