Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Amazon Associates API Interface using hpricot
branch: master

This branch is 22 commits behind dpickett:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
.autotest
.gitignore
.project
CHANGELOG
MIT-LICENSE
README
Rakefile
VERSION.yml
amazon_associate.gemspec

README

== amazon-associate

Generic Amazon E-commerce REST API using Hpricot with configurable 
default options and method call options. Uses Response and 
Element wrapper classes for easy access to REST XML output. It supports ECS 4.0.

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

If in the future, there is a change in REST XML output structure, 
no changes will be required on <tt>amazon-ecs</tt> library, 
instead you just need to change the element path.

Version: 0.6.1

== WANTS
 * instance based refactoring (singletons are not ideal here)
 
== INSTALLATION

  $ gem install dpickett-amazon_associate

== EXAMPLE

    require 'amazon_associate'
	
    # set the default options; options will be camelized and converted to REST request parameters.
    AmazonAssociate::Request.options = {:aWS_access_key_id => [your developer token]}

    # options provided on method call will merge with the default options
    res = AmazonAssociate::Request.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 (AmazonAssociate::Element)
    res.items.each do |item|
      # retrieve string value using XML path
      item.get('asin')
      item.get('itemattributes/title')

      # or return AmazonAssociate::Element instance
      atts = item.search_and_convert('itemattributes')
      atts.get('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
        AmazonAssociate::Element.get_hash(review) # [:source => ..., :content ==> ...]
    
        # Or to get unescaped HTML values
        AmazonAssociate::Element.get_unescaped(review, 'source')
        AmazonAssociate::Element.get_unescaped(review, 'content')
        
        # Or this way
        el = AmazonAssociate::Element.new(review)
        el.get_unescaped('source')
        el.get_unescaped('content')
      end
      
      # returns AmazonAssociate::Element instead of string
      item.search_and_convert('itemattributes').
    end

Refer to Amazon Associate's 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

== CACHING

  Filesystem caching is now available.
  
  AmazonAssociate::Request.options = {:aWS_access_key_id => [your developer token], :caching_strategy => :filesystem, 
    :caching_options => {:disk_quota => 200, :cache_path => <path where you want to store requests>, :sweep_frequency => 4}
  }
  
  The above command will cache up to 200MB of requests. It will purge the cache every 4 hours or when the disk quota has been exceeded.
  
  Every request will be stored in the cache path. On every request, AmazonAssociate::Request will check for the presence of the cached file before querying Amazon directly.

== LINKS

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

== LICENSE

(The MIT License)

Copyright (c) 2008 Dan Pickett, Enlight Solutions, Inc.
Something went wrong with that request. Please try again.