Ruby Amazon Product Advertising API
What is amazon-ecs?
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
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.
Add Your Comment