It’s Only Software

On a side project recently, I decided to try out the Amazon Associated Web Service API, a Java library provided by Amazon which wraps the Amazon Associates Web Service calls with a friendly Java API.

For those who are considering integration with Amazon Associates Web Services (used for things as item search, item detail retrieval, and cart manipulation), this API provides a very deep and rich integration with Amazon, with a relatively shallow learning curve. I’ll provide a simple example here of doing an item lookup by ASIN (Amazon’s unique product IDs), and point you around some of the data structures you’ll encounter when dealing with ASINs.

Getting Started

First things first - you need an Amazon Web Service (AWS) account. You can sign up for one here. This will give you a (public) access key ID, and a (private) secret access key. This will enable you to start making web service calls.

Next, you need to visit the Amazon Web Services developer site and drill down to the Java API download.

Finally, you need an Amazon Associates (aka Affiliates) ID. Sign up for one here.

Get these installed in your environment/IDE and you can move on to the next step of actually making an AWS call. Please note that the AWS Java API requires Java 5 or higher, as it utilizes generics heavily.

Setting up the Client

All the AWS operations are fronted by the AmazonA2SClient class, which is instantiated using your AWS secret key and affiliate ID:

public class AmazonAssociatesDemo {
	private static final String AMAZON_AFFILIATE_ID = "my-id-12";
	private static final String AMAZON_WS_KEY = "my-secret-key";
 
	private static AmazonA2SClient getAmazonClient() {
		return new AmazonA2SClient(AMAZON_WS_KEY,AMAZON_AFFILIATE_ID);
	}
}

Once you have the client object, you can perform all kinds of interesting operations on it, proxied through web service calls. The basic design of the API is that you fill out a request object, send it to the operation, and get back a response object.

Making a Request for Item Information

Although there are facilities to perform item search, for the purpose of this 5 minute guide, we’ll assume we already know the ASIN for an item we’re interested in. Let’s use the ASIN for Super Smash Bros. Brawl. The URL when viewing that item is: http://www.amazon.com/Nintendo-Super-Smash-Bros-Brawl/dp/B000FQ9R4E/, and we can see the ASIN at the end: http://www.amazon.com/Nintendo-Super-Smash-Bros-Brawl/dp/B000FQ9R4E/.

For simplicity purposes, we will restrict our search to find items only sold by Amazon.com. The code to search for the ASIN will then look as follows:

		ItemLookupRequest itemLookup = new ItemLookupRequest();
 
		List<String> itemIds = new ArrayList<String>();
		itemIds.add("B000FQ9R4E"); // the ASIN for the game we are interested in
		itemLookup.setItemId(itemIds);
		itemLookup.setMerchantId("Amazon"); // restricts to Amazon.com as the merchant
 
		List<String> responseGroups = new ArrayList<String>();
		responseGroups.add("Medium");
		itemLookup.setResponseGroup(responseGroups);
 
		// build Amazon Client
		AmazonA2SClient client = getAmazonClient();
		ItemLookupResponse response = client.itemLookup(itemLookup);
		Item result = null;
		for(Items items : response.getItems()) {
			result = items.getItem().get(0);
			break; // we are getting one and only one item, for now...
		}

Now, you can see that we built up the item lookup request object with a variety of basic parameters (there are many more). We make the request, and then return a response object, which we can interrogate for additional information about the item. This results in an Item object. You’ll notice that we reference a “response group” of “Medium” here. Response Group is a key concept related to item information - basically this filters the information returned about an item. Response Groups are documented in the Developer Reference. “Medium” is a middle-of-the-road setting.

From here, we can interrogate the item object to find information like the item title, price, etc. Some of the information is buried because Amazon captures so much data about an object. The easiest way to find what you are looking for is by examining the XML that is returned from the web service call, or looking at the returned object structure in the debugger. Some simple examples:

Item Title

		String title = item.getItemAttributes().getTitle()

Item Price

		Offer offer = getAmazonDotComOffer(item.getOffers());
		String formattedPrice = offer.getOfferListing().get(0).getPrice().getFormattedPrice();

Hopefully this helps gives a simple introduction to the Java Amazon Associates Web Service API. As always, please post comments if you have questions or clarifications.

Related Reading

Amazon Associates Web Services API Documentation offers documentation on the web service objects in quite good detail. These translate pretty closely to the Java objects.