Beginners Guide to getting started with Amazon Product Advertising API

This is a beginners guide to consuming the Product Advertising API of Amazon. I will be targeting “ItemLookup” method here. But any other API methods like “ItemSearch”, “BrowseNodeLookup”, “SimilarityLookup”, “CartAdd”, “CartClear”, “CartGet”, “CartModify” should look like a cake walk after this.

Pre-requisites:

• An Amazon AWS (Amazon Web Services) account
  If you do not have one, just go to aws.amazon.com, sign up, provide your credit card info (dont worry you wont be charged until you cross the free quota limit)
• Your AWS Account ID, Access Key ID and Access Secret Key from the “Security Credentials” page
  
  Click on the “Show” to get your Secret Access Key
  The AWS Account ID is the Account ID or the so called Associate Tag
• Identify the Amazon Region which you are going to query. This is basically the region in which you are searching for an amazon product. ex. if you want to search this product in Amazon Italy site, then your region is “webservices.amazon.it“. Below are the list of locales available for you:
  

That’s all. Now you are all set to consume the Amazon Product Advertising API.

Consuming the API is not that straight forward, especially due to the authentication process involved. Which is good in one way. And this is where most us normally tend to get frustrated. I totally agree. I hope this post help you avoid wasting days of investigations on that. I also hope Amazon improves their documentation as well.

Forget all those things for the time being….At the end of the day, all we need get is a simple URL, which you can paste it in your browser and see the results. Let me show you what i meant by this. Then we will proceed on how to construct this URL.

Final Request URL:

http://webservices.amazon.de/onca/xml?AWSAccessKeyId={AccessKeyID}&AssociateTag={AssociateTag}&Availability=Available&IdType=EAN&ItemId=4210201052623
&MerchantId=Amazon&Operation=ItemLookup &ResponseGroup=ItemAttributes%2COffers
&SearchIndex=All&Service=AWSECommerceService&Timestamp=2013-11-20T15:03:00Z
&Version=2009-03-31&Signature=k1DNFOxZeIa0KNVTHLZVPUhVd2%2B6i9rLAPH75h7TCiw%3D

I have removed the Associate Tag and Access Key Id, from the URL, for security purpose.

Final Response on the Browser:

It’s that simple!!

Steps involved in constructing this URL – also called the “Signing the URL”

A small note: I wont be able to explain the signing process involved in detailed here. That would be too lengthy and will get you bored. But if you start getting errors on signing process, you will need to go through them & understand them. Check amazon API documentation for that…sorry…:(

Use Case: Get the details of a product with ASIN ID “B004CRSLUI”, in Amazon France Site.

STEP 1: Construct the Unsigned URL

This is straightforward. Fill the below template with your values from the “Pre-requisites” section:
http://webservices.amazon.fr/onca/xml?Service=AWSECommerceService&Operation=ItemLookup&SubscriptionId={Access Key ID}
&AssociateTag={Associate Tag}&Version=2011-08-01&ItemId=B004CRSLUI
&IdType=ASIN&Condition=All&ResponseGroup=ItemAttributes,OfferFull,Offers

STEP 2: Generate the “Signature” parameter (which you see towards the end of the above url), using your Access Key, Access Security Key and the unsigned URL

This is the tricky part. The signature is generated by using an encoding algorithm. It is a generic algorithm (HMACSHA256) that we have in most of the coding languages C#, Java or PHP. You can get the library for your favorite language from here: http://aws.amazon.com/code/Product-Advertising-API

A sample “Signature” value looks something like this:
zo4wTc7ZIujHz1zAL4sR1%2FHCEiUWg%2Fde2f%2FRO0f31LI%3D

For C# users, there is a helper class called “SignedRequestHelper.cs” available from one of the sample codes in the above link. You can also download that file here SignedRequestHelper.cs.

Once added to your C# project, you need to refer the namespace:

using AmazonProductAdvtApi;

Create a generic method which invokes the SignedRequestHelper class:

public static string GenerateSignedRequestUrl(string skuId)

{
//Initialise the Amazon Signing helper method with the access key and access secret
SignedRequestHelper helper = new SignedRequestHelper(“{AwsAccessKeyId}”, “{AwsSecretKey}”, “webservices.amazon.fr”);

//Setup the request dictionary with the required parameters
IDictionary<string, string> r1 = new Dictionary<string, String>();
r1[“Service”] = “AWSECommerceService”;
r1[“Version”] = “2009-03-31”;

r1[“Operation”] = “ItemLookup”;
r1[“ItemId”] = skuId;//”B004CRSLUI”; //You can even pass comma separated values here
r1[“IdType”] = “ASIN”;

r1[“Availability”] = “Available”;
r1[“SearchIndex”] = “All”;
r1[“AssociateTag”] = “{AwsAssociateTagId}”;
r1[“ResponseGroup”] = “ItemAttributes, Offers”;
r1[“MerchantId”] = “Amazon”;

//Sign the requestUrl using the Helper class
return helper.Sign(r1);
}

STEP 3: In you C# code, make an HttpWebRequest for the above “Signed” Url:

public static XDocument InvokeService(string requestUrl)
{
XDocument responseDocument = null;
try
{
//Convert the Url from string format to Uri format
Uri requestUri = new Uri(requestUrl, UriKind.Absolute);

//Invoke the Web Service Url
WebRequest request = HttpWebRequest.Create(requestUri);

#region Proxy

//Invoke the proxy objects UNCOMMENT ONLY IF YOU GET Remote Server Access Denied Error
//This implies that your local firewall is blocking request to amazon…Ideally you should be fine without this section
//WebProxy proxyObject = new WebProxy(“myproxy.domain.com”, 8080);
//proxyObject.Credentials = new NetworkCredential(“*********”, “***********”);
//request.Proxy = proxyObject;

#endregion

//Set the request timeout to be 20sec
request.Timeout = 20000;

WebResponse response = request.GetResponse();
XmlReader reader = XmlReader.Create(response.GetResponseStream());

//Load the XDocument object with the response
responseDocument = XDocument.Load(reader);
}
catch (Exception ex)
{
throw new Exception(“Error consuming the Web Service at InvokeService(string requestUrl) Method | Message:” + ex.Message);
}

//Return the response XML results
return responseDocument;
}

The responseDocument would be the “ItemLookupResponse” XML, similar to the browser screenshot i showed earlier in this post.

There quite a handful of libraries in different programming languages that are available here, which you can use to sign your URL. Most of them are methods that accept your Access ID Key, Access Secret Key, Associate ID, the unsigned URL as inputs and return the signed URL as the output.

Run the finally constructed Signed URL in your browser to see the product data.

You could even test this using a Scratchpad application which amazon provides. The link to Scratchpad: http://associates-amazon.s3.amazonaws.com/scratchpad/index.html

The screenshot is as shown below:

 

I hope this post gave you a quick start to consuming Amazon Product Advertising API and helped your development efforts.
Feel free to post your queries here.