The Amazon Module

Kynetx has implemented a KRL layer for the Product Advertising API (think www.amazon.com). Amazon provides a SOAP and a REST api to their e-commerce operations. KRL provides a secure way to produce authenticated, signed requests to the APAAPI without exposing your 'Secure Access Key'.

Supported Amazon Product Advertising API Operations

• ItemSearch
• ItemLookup

Skip Ahead

• Skip to Amazon APAAPI Functions
• Skip to Examples

Getting Started

Set yourself up an Amazon developer account. You will have to agree to Amazon's Licensing Agreement which includes usage guidelines, policies and requirements. You can also earn referral fees from customers that click through and buy products through your applications by becoming an Amazon affiliate. The Amazon Associates program also gives you access to special retail promotions and offers available to affiliates.

• Get your APAAPI developer credentials here

• (Optional) Become an Amazon Associate here

Place your Amazon credentials in the meta section of your application

key amazon {
"token"        : "XXXXXXXXXXXXXXXXXXXXXXXX",
"secret_key"   : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
 "associate_id" :  "latfordin-20"
}

If you have signed up for your Amazon developer account, you can find (or create) your access key here. Your associate_id is found in a separate affiliate account. It is not required to have an associate_id and that line in the meta block is optional.

ItemSearch

There are a multitude of options and variations in the ItemSearch operation. I will try to provide enough information to enable you to take advantage of the interface, but not overwhelm you with all of the various permutations. Full documentation is available from Amazon.

Since Amazon has a database of roughly a bajillion items, they have organized their products into indexes. When you perform an item search, you must specify an index. There is a special index 'All' that will allow you to search across all of the indexes, but each index has it's own set of allowed qualifiers

Search indexes:

Required Parameters (At least one of):

Which one should you use? Well, it depends. As stated previously, each search index has it's own set of allowed parameters (each locale also has it's own set of indices and parameters). The definitive list is here. Luckily before you start to panic, Keywords is a valid required parameter for every index (it is the only parameter allowed for the special index 'All').

Indices and search parameters help you provide targeted search results. This helps you build context for your customers. Each search request can return up to 10 items. Results are divided into pages. If you want to process more than 10 items, you will have to make separate requests and specify the page of data that you require.

Search Parameters

The following table is from the Amazon documentation. Names in bold are parameters modified or specific to the KRL environment.
Click here to see the Search Parameters Table

All of the information that you can find on the Amazon web portal is available through the APAAPI. Information returned by the ItemSearch is specified by one or more Response Groups. For ItemSearch, the allowed Response Groups are designed to give you just enough information to identify the items that you want to explore. The ItemLookup operation is provided to allow you to plumb the depths of the Amazon database for reviews, recommendations, and the wealth of ancillary data available.

ItemSearch Response Groups:

'Small' is the default response group. ItemIds is the smallest of the response groups--returning just ASINs. You can specify multiple response groups. Additional elements are simply added to each item.

ItemLookup

With most of the touchy-feely stuff dealt with in the module introduction and ItemSearch, we don't have to complicate ItemLookup. Here is the short and sweet: use ItemSearch to find the ASIN (Amazon product id) and then use ItemLookup to grab all of the information you need (and then some more).

The secret sauce of the ItemLookup is in the Response Groups. From the Amazon documentation, valid Response Groups are: Click here to see Response Group Table

Anatomy of a Response

ItemIds is the simplest of the response groups:

amazon:item_lookup({"ItemId" : "B00008OE6I",
                "response_group" : "ItemIds" })

{
   "version" : "1.0",
   "ItemLookupResponse" : {
      "Items" : {
         "Item" : {
            "ASIN" : "B00008OE6I"
         },
         "Request" : {
            "IsValid" : "True",
            "ItemLookupRequest" : {
               "OfferPage" : "1",
               "ItemId" : "B00008OE6I",
               "ResponseGroup" : "ItemIds",
               "IdType" : "ASIN",
               "Condition" : "New"
            }
         }
      },
      "OperationRequest" : {
         "RequestProcessingTime" : "0.019597053527832",
         "RequestId" : "0QS36WHRSM6FJ5CT2E6G",
         "Arguments" : {
            "Argument" : [
               {
                  "Value" : "B00008OE6I",
                  "Name" : "ItemId"
               },
               {
                  "Value" : "New",
                  "Name" : "Condition"
               },
               {
                  "Value" : "AWSECommerceService",
                  "Name" : "Service"
               },
               {
                  "Value" : "ItemIds",
                  "Name" : "ResponseGroup"
               },
               {
                  "Value" : "ItemLookup",
                  "Name" : "Operation"
               },
               {
                  "Value" : "1",
                  "Name" : "RelatedItemsPage"
               },
               {
                  "Value" : "ASIN",
                  "Name" : "IdType"
               },
               {
                  "Value" : "2010-02-12T17:27:57.000Z",
                  "Name" : "Timestamp"
               },
               {
                  "Value" : "2009-03-31",
                  "Name" : "Version"
               },
               {
                  "Value" : "90FtmDYFQbOzkKe+UzlMsa78CgV8BamEdUvUxxy4uN0=",
                  "Name" : "Signature"
               },
               {
                  "Value" : "1",
                  "Name" : "OfferPage"
               },
               {
                  "Value" : "AKIXXXXXXXXXXXXXXX",
                  "Name" : "AWSAccessKeyId"
               }
            ]
         },
         "HTTPHeaders" : {
            "Header" : {
               "Value" : "Kynetx Rule Engine/1.0",
               "Name" : "UserAgent"
            }
         }
      }
   },
   "encoding" : "UTF-8"
}

Things to note about the response

Item:

ItemLookup responses will generally build up/add info to the "Item" object so this is where the magic happens

The request tells you what information Amazon received in the request. Notice that KRL provides several defaults for your convenience, but these are all available to you for modification

The OperationRequest object is like the Amazon debug information. Keep an eye on your RequestProcessingTime.

You can add information to your response by adding Response Groups to your request.

amazon:item_lookup({"ItemId" : "B00008OE6I",
                "response_group" : ["ItemIds","OfferSummary" })

...
        "Item" : {
            "OfferSummary" : {
               "LowestUsedPrice" : {
                  "Amount" : "3999",
                  "CurrencyCode" : "USD",
                  "FormattedPrice" : "$39.99"
               },
               "TotalRefurbished" : {},
               "TotalUsed" : "8",
               "TotalCollectible" : {},
               "TotalNew" : {}
            },
            "ASIN" : "B00008OE6I"
         }

Amazon APAAPI Functions:

item_search()

amazon:item_search({"keywords" : "Bacon Salt"})

--Above is an example of the simplest possible Amazon search
request. You must pass the search parameters as a hash of
"name" : value pairs with the pairs separated by commas.

amazon:item_search({"locale" : "us",
   "index" : "electronics",
   "manufacturer" : "sony",
   "keywords" : "1080p",
   "response_group" : ["ItemIds","BrowseNodes","BrowseNodeInfo"],
   "itempage" : 4})

--Search the electronics index of the US database for anything
matching the keyword "1080p" with "sony" as the manufacturer
and return the ASIN of items 31-40 with the corresponding browse
nodes

amazon:item_search({"index" : "automotive",
   "condition" : "Used",
   "state" : "UT"})

--Search the US automotive index for used items in Utah.
Note that this is not specific and will return parts, cars,
electronics and whatever

amazon:item_search({"locale" : "ca",
   "index" : "Kitchen",
   "keywords" :  "davenport ketchup chips"})

--Search the Canadian database for kitchen items that
match davenport, ketchup, and chips

item_lookup()

amazon:item_lookup({"item_id" : "B0017T0X9G"})

--Simplest possible item lookup. Uses the Amazon
ASIN and returns the 'Small' Response Group by default

amazon:item_lookup({"item_id" : "B000V9CUP8",
    "relationshiptype" : "Tracks",
    "response_group" : ["RelatedItems"]})

--Search for any related tracks to the specified item

amazon:item_lookup({"item_id" : ["C2002-WK"],
    "idtype" : "SKU",
    "merchant" : "All",
    "response_group" : ["EditorialReview","Tags"],
    "review_page" : 2,
    "tag_page" : 3})

--Search by SKU (merchant parameter is required when
you search by SKU) and return the 2nd page of reviews
and 3rd page of tags associated with the items found