Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Generic Ruby Amazon Product Advertising API
branch: master

This branch is 35 commits behind jugend:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib/amazon
test
CHANGELOG
MIT-LICENSE
README
Rakefile
amazon-ecs.gemspec

README

== amazon-ecs

Generic Product Advertising Ruby API using Nokogiri. Uses Response and 
Element wrapper classes for easy access to the REST API XML output.

It is generic, so you can easily extend <tt>Amazon::Ecs</tt> to support 
other not implemented REST operations; and it is also generic because it just wraps around
Nokogiri element object, instead of providing one-to-one object/attributes to XML elements map.

The idea is as the API evolves, there is a change in REST XML output structure, 
no updates will be required on <tt>amazon-ecs</tt> gem, 
instead you just need to update the element path. 

For HPricot dependency implementation, please install 1.2.x version or checkout v1.2 branch.

== 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'})
    
    # search amazon uk
    res = Amazon::Ecs.item_search('ruby', :country => 'uk')
    
    # 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 Nokogiri::XML::NodeSet object or nil if not found
      reviews = item/'EditorialReview'
  
      # traverse through Nokogiri elements
      reviews.each do |review|
        # Getting hash value out of Nokogiri 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, opts={})
          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')

Refer to Amazon Product Advertising API documentation for more information 
on other valid operations, request parameters and the XML response output:
https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html

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

== SOURCE CODES

* http://github.com/jugend/amazon-ecs

== CREDITS

Thanks to Dan Milne (http://da.nmilne.com/) for the signed request patch.

Thanks to Bryan Housel (https://github.com/bhousel/amazon-ecs) for the initial Nokogiri patch 

== LICENSE

(The MIT License)

Copyright (c) 2011 Herryanto Siatono, http://www.siatono.com
Something went wrong with that request. Please try again.