A generic Ruby Amazon Product Advertising API (previously known as E-commerce REST API) using Hpricot. It uses Response and Element wrapper classes for easy access to the REST API XML output.

It is generic, so you can extend Amazon::Ecs to support the other not-implemented operations easily; and the response object just wraps around Hpricot element object, instead of providing one-to-one object/attributes to XML elements map.

With that, if in the future, there is a change in REST XML output structure, no changes will be required on amazon-ecs, instead you just need to change your element path.

And four years after it still works like magic supporting the latest version of the API. As a prove, please read this post.

Links

• GitHub Repository
• Ruby Gems

Installation

$ gem install amazon-ecs

Example

require "amazon/ecs"

# set the default options; options will be camelized and converted to REST request parameters.
Amazon::Ecs.options = {:aWS_access_key_id => "[your access key]"}

# to generate signed requests include your secret key:
Amazon::Ecs.options = {:aWS_access_key_id => "[your developer token]", :aWS_secret_key => "[your secret access key]"}

# alternatively,
Amazon::Ecs.configure do |options|
    options[:aWS_access_key_id] = "[your access key]"
    options[:aWS_secret_key] = "[you secret key]"
end

# options provided on method call will merge with the default options
res = Amazon::Ecs.item_search("ruby", {:response_group => "Medium", :sort => "salesrank"})

# some common response object methods
res.is_valid_request?     # return true if request is valid
res.has_error?            # return true if there is an error
res.error                 # return error message if there is any
res.total_pages           # return total pages
res.total_results         # return total results
res.item_page             # return current page no if :item_page option is provided

# traverse through each item (Amazon::Element)
res.items.each do |item|
  # retrieve string value using XML path
  item.get("asin")
  item.get("itemattributes/title")

  # return Amazon::Element instance
  item_attributes = item.get_element("itemattributes")
  item_attributes.get("title")

  # return first author or a string array of authors
  item_attributes.get("author")          # "Author 1"
  item_attributes.get_array("author")    # ["Author 1", "Author 2", ...]

  # return an hash of children text values with the element names as the keys
  item.get_hash("smallimage") # {:url => ..., :width => ..., :height => ...}

  # return the first matching path as Amazon::Element
  item_height = item.get_element("itemdimensions/height")
  
  # retrieve attributes from Amazon::Element
  item_height.attributes["units"]   # "hundredths-inches"
  
  # return an array of Amazon::Element
  authors = item.get_elements("author")

  # return Hpricot::Elements object or nil if not found
  reviews = item/"editorialreview"

  # traverse through Hpricot elements
  reviews.each do |review|
    # Getting hash value out of Hpricot element
    Amazon::Element.get_hash(review) # [:source => ..., :content ==> ...]

    # Or to get unescaped HTML values
    Amazon::Element.get_unescaped(review, "source")
    Amazon::Element.get_unescaped(review, "content")
    
    # Or this way
    el = Amazon::Element.new(review)
    el.get_unescaped("source")
    el.get_unescaped("content")
  end
end

# Extend Amazon::Ecs, replace 'other_operation' with the appropriate name
module Amazon
  class Ecs
    def self.other_operation(item_id, options)
      opts[:operation] = '[other valid operation supported by Product Advertising API]'
      
      # setting default option value
      opts[:item_id] = item_id
    
      self.send_request(opts)
    end
  end
end

Amazon::Ecs.other_operation("[item_id]", :param1 => "abc", :param2 => "xyz")

Tip

If you are on irb console, this trick helps to print a nicely formatted xml result:

require 'pp'
pp res = Amazon::Ecs.item_search('ruby').doc

More Information

Refer to Amazon ECS documentation for more information on Amazon REST request parameters and XML output structure.

Or you can also get a sample of Amazon REST XML output from AWSZone.com.