Ruby Amazon E-Commerce REST Service API (amazon-ecs)
What is amazon-ecs?
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
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.
Add Your Comment