amazon-associates

== amazon-associates

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.

== INSTALLATION

$ gem install amazon-associates

== EXAMPLE

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
  item.asin
  item.attributes['Title']

  # or return Amazon::Element instance
  atts = item.attributes
  atts['Title']

  # 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 = Amazon::Element.new(review)
    el.get_unescaped('source')
    el.get_unescaped('content')
  end
  
  # returns Amazon::Element instead of string
  item.search_and_convert('itemattributes').
end

Refer to Amazon ECS documentation for more information on Amazon REST request parameters and XML output: http://docs.amazonwebservices.com/AWSEcommerceService/2006-09-13/

To get a sample of Amazon REST response XML output, use AWSZone.com scratch pad: http://www.awszone.com/scratchpads/aws/ecs.us/index.aws

== LINKS

• http://amazon-ecs.rubyforge.org
• http://www.pluitsolutions.com/amazon-ecs

== LICENSE

(The MIT License)

Copyright (c) 2008 Dan Pickett, Enlight Solutions; Herryanto Siatono, Pluit Solutions; and Ben Woosley