Generic Amazon E-commerce REST API using Hpricot with configurable default options and method call options. Uses Response wrapper classes for easy access to REST XML output. It supports ECS 4.0.


$ gem install amazon-associates


require 'amazon-associates'

# set the default options; options will be camelized and converted to REST request parameters.
Amazon::Ecs.options = {:aws_access_key_id => [your developer token]}

# 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.request.valid?        # 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

  # or return Amazon::Element instance
  atts = item.attributes

  # return first author or a string array of authors
  atts.get('author')          # 'Author 1'
  atts.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 => ...}

  # note that '/' returns Hpricot::Elements array object, 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 =

  # returns Amazon::Element instead of string

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

To get a sample of Amazon REST response XML output, use scratch pad:


(The MIT License)

Copyright © 2008 Dan Pickett, Enlight Solutions; Herryanto Siatono, Pluit Solutions; and Ben Woosley