A generic Amazon E-commerce REST API with configurable default options and method call options. It uses Hpricot to parse the XML output. Use Response and Element wrapper classes for easy access to the XML elements, and it supports ECS 4.0.

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 if you love history, click here.

Links

• GitHub Repository
• Rubyforge Home
• Rdoc Documentation
• Download

Installation

$ gem install amazon-ecs

Example

Initiating a search request:

require 'amazon/ecs'

# default options; will be camelized and converted 
# to REST request parameters.
Amazon::Ecs.options = {:aWS_access_key_id => [your access key]}
res = Amazon::Ecs.item_search('ruby')

# or you can provide additional options
res = Amazon::Ecs.item_search('ruby', :response_group => 'Medium', :sort => 'salesrank')

# to search other Amazon UK
res = Amazon::Ecs.item_search('ruby', :country => :uk)

Retrieving common response values:

# some common response object methods
res.is_valid_request?
res.has_error?
res.error
res.total_pages
res.total_results
res.item_page

Retrieving items, and item attributes:

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

  # or return Amazon::Element instance
  atts = item.search_and_convert('itemattributes')
  
  # get title as a string 
  atts.get('title')

  # get only returns the first element of an array
  atts.get('author')            # 'Author 1'

  # to retrieve an array
  atts.get_array('author')    # ['Author 1', 'Author 2', ...]

  # to retrieve a hash of children text values
  item.get_hash('smallimage') # {:url => ..., :width => ..., :height => ...}

  # '/' returns Hpricot::Elements array object, nil if not found
  reviews = item/'editorialreview'

  # traverse through Hpricot elements
  reviews.each do |review|
    # Getting a 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

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.