alandipert-ruby-aaws 0.7.1

data/README.rdoc

@@ -0,0 +1,145 @@
+#--
+# $Id: README.rdoc,v 1.25 2009/06/15 23:51:11 ianmacd Exp $
+#++
+#
+#
+# = Ruby/AWS - A Ruby interface to the Amazon Associates Web Services API.
+# 
+# == Introduction
+# 
+# Ruby/AWS is a Ruby language library that allows programmatic access to
+# the popular Amazon Web sites via the AWS v4 API. It is the successor to the
+# now obsolete Ruby/Amazon.
+#
+# In addition to the original
+# amazon.com[http://www.amazon.com/exec/obidos/redirect-home/calibanorg-20]
+# site, the local sites
+# amazon.co.uk[http://www.amazon.co.uk/exec/obidos/redirect-home/caliban-21],
+# amazon.de[http://www.amazon.de/exec/obidos/redirect-home/calibanorg0a-21],
+# amazon.fr[http://www.amazon.fr/exec/obidos/redirect-home/caliban08-21],
+# amazon.ca[http://www.amazon.ca/exec/obidos/redirect-home/caliban-20] and
+# amazon.co.jp[http://www.amazon.co.jp/exec/obidos/redirect-home/calibanorg-20]
+# are also supported.
+#
+# Although the library is still in development, the AWS v4 API is now more or
+# less fully supported, with only tiny gaps in the functionality of some
+# operations.
+#
+# The following operations are supported:
+#
+#  BrowseNodeLookup
+#  CustomerContentLookup
+#  CustomerContentSearch
+#  Help
+#  ItemLookup
+#  ItemSearch
+#  ListLookup
+#  ListSearch
+#  SellerListingLookup
+#  SellerListingSearch
+#  SellerLookup
+#  SimilarityLookup
+#  TagLookup
+#  TransactionLookup
+#  VehiclePartLookup
+#  VehiclePartSearch
+#  VehicleSearch
+#
+# Remote shopping-carts are also supported. This adds the following operations:
+#
+#  CartCreate
+#  CartAdd
+#  CartModify
+#  CartClear
+#  CartGet
+# 
+# Finally, multiple operations and batch requests are also supported.
+#
+# Ruby/AWS supports request authentication, using your secret key to sign your
+# requests to AWS.
+#
+# Beyond wrapping features readily available in the AWS API, Ruby/AWS also
+# offers advanced features not directly supported by the AWS API, such as the
+# ability to retrieve *all* results pages for a particular search, rather than
+# having to manually deal with multiple AWS responses of 10 results per page.
+#
+# You can also retrieve product images and optionally overlay them with
+# percentage discount icons.
+#
+# Another advanced feature is the ability to cache responses returned by AWS.
+# If the cache is used (as it is by default), the results of each unique
+# search will be cached and used for 24 hours. The cache can be manually
+# flushed of all or just the expired entries.
+#
+# One other useful advanced feature is the ability to determine the
+# appropriate Amazon locale for a given client, based on its IP address or
+# host name. This allows you to perform AWS operations using the correct
+# geographical Amazon site for any given client. German and Austrian clients
+# can be made to interact with amazon.de, British and Irish clients with
+# amazon.co.uk, etc.
+#
+#
+# == Installation
+#
+# Please see the +INSTALL+ file supplied with the software for details of how 
+# to install Ruby/AWS. You can choose between an installation script and a
+# RubyGems[http://www.rubygems.org/] installation.
+#
+# Note, however, if opting for the gem installation, that Ruby/AWS's RubyForge
+# UNIX name is now ruby-aaws. The ruby-aws name was taken by {another
+# project}[http://rubyforge.org/projects/ruby-aws/] and this namespace clash
+# prevented remote installation of the Ruby/AWS gem.
+#
+#
+# == Prerequisites
+#
+# Before you can use this library, you need to obtain an Amazon Web Services
+# {access key
+# ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html].
+#
+# You should also apply for an {Associates
+# account}[http://docs.amazonwebservices.com/AWSECommerceService/2009-03-31/GSG/BecominganAssociate.html],
+# although this isn't strictly necessary. If you do not explicitly provide an
+# Associates tag in the operations you conduct via Ruby/AWS, the tag of the
+# Ruby/AWS author will be used by default.
+#
+# 
+# == See Also
+# 
+# Ultimately, the way to get the most from Ruby/AWS is to read the AWS
+# documentation to get a feel for what is possible, and then experiment with
+# the library to see how the calls to AWS are mapped to the Ruby world. You
+# should also review this library's
+# RDoc[http://www.ruby-doc.org/core/classes/RDoc.html]
+# documentation[http://www.caliban.org/ruby/ruby-aws/] as well as the
+# plain-text +README+ file that came with the archive.
+#
+# Additionally, there's a
+# {mailing-list}[http://www.caliban.org/mailman/listinfo/ruby-aws] available,
+# where you can discuss any Ruby/AWS-related subjects and issues.
+#
+# Please see the AWS Developer Resources {home
+# page}[https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html],
+# the Amazon Web Services API
+# documentation[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=5],
+# and, in particular, the {release
+# notes}[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=17]
+# for definitive information on the capabilities and inner workings of the AWS
+# API.
+#
+#
+# == Download
+#
+# Version 0.7.0
+# === {gzip'ed tar archive}[http://www.caliban.org/files/ruby/ruby-aws-0.7.0.tar.gz]
+# === {Ruby Gem}[http://www.caliban.org/files/ruby/ruby-aaws-0.7.0.gem]
+# === {Fedora 9 RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.7.0-1.fc9.noarch.rpm]
+# === {Fedora 9 doc RPM}[http://www.caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.7.0-1.fc9.noarch.rpm]
+# === {Fedora 9 source RPM}[http://www.caliban.org/files/redhat/SRPMS/ruby-aws-0.7.0-1.fc9.src.rpm]
+# 
+# 
+# ---
+# Author::   Ian Macdonald <mailto:ian@caliban.org>
+# Version::  0.7.0
+# Copyright:: (C) 2008-2009 Ian Macdonald
+# Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]

data/Rakefile

@@ -0,0 +1,35 @@
+# $Id: Rakefile,v 1.15 2009/06/15 12:07:14 ianmacd Exp $
+#
+
+require 'rubygems'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "ruby-aaws"
+    gemspec.summary = "Ruby interface to Amazon Associates Web Services"
+    gemspec.description = "Ruby interface to Amazon Associates Web Services"
+    gemspec.email = "ian@caliban.org"
+    gemspec.homepage = "http://www.caliban.org/ruby/ruby-aws/"
+    gemspec.authors = ["Ian Macdonald", "Jamie Dyer"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+
+desc 'Produce HTML documentation in ./doc'
+task :doc do
+  system( *%w[ rdoc -SUx CVS lib ] )
+
+  # In-place edit to change page of main frame to the one with the most
+  # relevant documentation.
+  #
+  $-i = ''
+  ARGV[0] = 'doc/index.html'
+  ARGF.each_line do |l|
+    l.sub!( Regexp.new( 'files/lib/.+?\.html' ),
+	    'files/lib/amazon/aws_rb.html' )
+    puts l
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.7.1

data/example/batch_operation

@@ -0,0 +1,27 @@
+#!/usr/bin/ruby -w
+#
+# $Id: batch_operation,v 1.2 2009/02/20 00:37:15 ianmacd Exp $
+
+require 'amazon/aws/search'
+ 
+include Amazon::AWS
+include Amazon::AWS::Search
+ 
+rg = ResponseGroup.new( :Small )
+req = Request.new
+req.locale = 'uk'
+req.cache = false
+
+is = ItemSearch.new( 'Books', { 'Title' => 'ruby programming' } )
+is2 = ItemSearch.new( 'Music', { 'Title' => 'stranglers' } )
+#more_is = [ ItemSearch.new( 'Music', { 'Title' => 'stranglers' } ),
+#	    ItemSearch.new( 'DVD', { 'Director' => 'scorsese' } ) ]
+
+more_is = [ ItemSearch.new( 'Music', { 'Artist' => 'stranglers' } ) ]
+
+is.batch( more_is )
+
+batched_response = req.search( is, rg )
+itemsearch = batched_response.item_search_response[0].items
+
+puts itemsearch

data/example/browse_node_lookup1

@@ -0,0 +1,46 @@
+#!/usr/bin/ruby -w
+#
+# $Id: browse_node_lookup1,v 1.3 2008/04/11 19:24:24 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+# This is the node for Social Sciences.
+#
+START_NODE = '11232'
+
+def follow_node(id)
+
+  req ||= Request.new
+  req.locale = 'us'
+
+  bnl = BrowseNodeLookup.new( id, {} )
+  bnl_rg ||= ResponseGroup.new( 'BrowseNodeInfo' )
+  resp = req.search( bnl, bnl_rg )
+
+  #items = resp.browse_node_sets.browse_nodes
+  nodes = resp.browse_node_lookup_response[0].browse_nodes[0].browse_node
+
+  nodes.each do |bn|
+
+    if bn.children
+      puts '%s (%s) has the following children:' % [ bn.name, id ]
+
+      bn.children[0].browse_node.each do |child_node|
+        puts '  %s' % [ child_node.name ]
+      end
+      puts
+
+      bn.children[0].browse_node.each do |child_node|
+        follow_node( child_node.browse_node_id )
+      end
+
+    else
+      puts '%s (%s) has no children.' % [ bn.name, id ]
+    end
+  end
+end
+
+follow_node( START_NODE )

data/example/customer_content_lookup1

@@ -0,0 +1,27 @@
+#!/usr/bin/ruby -w
+#
+# $Id: customer_content_lookup1,v 1.3 2008/04/28 09:59:52 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+ccl = CustomerContentLookup.new( 'AJDWXANG1SYZP' )
+rg = ResponseGroup.new( 'CustomerReviews' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( ccl, rg )
+
+review = resp.customer_content_lookup_response.customers.customer.customer_reviews.review[0]
+
+printf( "Customer's name is %s.\n", review.reviewer.name )
+printf( "Customer's location is %s.\n", review.reviewer.location )
+printf( "Review date is %s.\n", review.date )
+printf( "Review has received %s votes.\n", review.total_votes )
+printf( "Of these, %d deemed the review helpful.\n", review.helpful_votes )
+printf( "Product reviewed has ASIN '%s'.\n", review.asin )
+printf( "Review summary is: %s.\n", review.summary )
+printf( "Review content is:\n%s.\n", review.content )

data/example/customer_content_search1

@@ -0,0 +1,21 @@
+#!/usr/bin/ruby -w
+#
+# $Id: customer_content_search1,v 1.1 2008/04/27 21:58:54 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+ccs = CustomerContentSearch.new( 'ian@caliban.org' )
+rg = ResponseGroup.new( 'CustomerInfo' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( ccs, rg )
+cust = resp.customer_content_search_response.customers.customer
+
+printf( "Customer's ID is %s.\n", cust.customer_id )
+printf( "Customer's nickname is %s.\n", cust.nickname )
+printf( "Customer's location is %s.\n", cust.location.user_defined_location )

data/example/example1

@@ -0,0 +1,87 @@
+#!/usr/bin/ruby -w
+#
+# $Id: example1,v 1.5 2009/06/02 01:09:51 ianmacd Exp $
+
+require 'amazon/aws'
+require 'amazon/aws/search'
+
+# We don't want to have to fully qualify identifiers.
+#
+include Amazon::AWS
+include Amazon::AWS::Search
+
+# If you don't have one of these, don't pass the second argument to
+# Request.new.
+#
+ASSOCIATES_ID = "webservices-20"
+
+# Your access key ID.
+#
+KEY_ID        = "0Y44V8FAFNM119C6PTR2"
+
+request  = Request.new( KEY_ID, ASSOCIATES_ID )
+
+# Create an item search object.
+#
+# is = ItemSearch.new( 'Books', { 'Keywords' => 'ruby programming' } )
+is = ItemSearch.new( 'Books', { 'Title' => 'ruby programming' } )
+
+# Create a response group object. Examples of response groups are 'Small',
+# 'Medium' and 'Large'. 'Large' returns all data about an item.
+#
+rg = ResponseGroup.new( 'Large' )
+
+# Search for the items, passing the result into a block.
+#
+nr_items = 0
+page_nr = 0
+response = request.search( is, rg, :ALL_PAGES ) do |page|
+# page.item_search_response[0].items.each do |item_set|
+#   item_set.item.each do |item|
+#     puts 'Found a product:'
+#     item.instance_variables.each do |iv|
+#      printf( "%s = %s\n", iv, item.instance_variable_get( iv ) )
+#     end
+#   end
+# end
+  printf( "Page %d had unique request ID %s.\n",
+	  page_nr += 1,
+	  page.item_search_response[0].operation_request[0].request_id )
+  printf( "Page %d contained %d result(s).\n",
+	  page_nr,
+	  page.item_search_response[0].items[0].item.size )
+end
+
+# You don't have to access the items through a block.
+#
+nr_items = 0
+response.each do |page|
+  page.item_search_response[0].items.each do |item_set|
+      nr_items += item_set.item.size
+    end
+  end
+printf( "Search returned %d items.\n", nr_items )
+
+# The first item in the list.
+#
+items = response[0].item_search_response[0].items[0].item
+product1 = items[0]
+puts "\nProperties available for the first product returned:",
+  product1.properties.sort
+puts
+
+# There are three ways to retrieve the property of a product:
+#
+
+# Instance variable:
+#
+p product1.asin
+p product1.item_attributes[0].title
+
+# Feels more like a Hash:
+#
+p product1.item_attributes[0]['list_price'][0]['formatted_price']
+
+# A variation on the hash theme:
+#
+p product1.item_attributes[0][:author]

data/example/help1

@@ -0,0 +1,25 @@
+#!/usr/bin/ruby -w
+#
+# $Id: help1,v 1.1 2008/04/27 22:21:52 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+h = Help.new( 'ResponseGroup', 'Large' )
+
+rg = ResponseGroup.new( 'Help' )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( h, rg )
+help = resp.help_response[0].information.response_group_information
+
+printf( "The response group 'Large' was created on %s\n", help.creation_date )
+puts 'It can be used with the following operations:'
+puts help.valid_operations.operation.join( ', ' )
+puts
+puts "and causes the following elements to be returned:\n\n"
+puts help.elements.element

data/example/item_lookup1

@@ -0,0 +1,56 @@
+#!/usr/bin/ruby -w
+#
+# $Id: item_lookup1,v 1.6 2009/02/20 00:13:38 ianmacd Exp $
+
+require 'amazon/aws'
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+# Example of a batch operation.
+#
+# The MerchantId restriction is to ensure that we retrieve only items that
+# are for sale by Amazon. This is important when we later want to retrieve the
+# availability status.
+#
+il = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000AE4QEC',
+			       'MerchantId' => 'Amazon' } )
+il2 = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000051WBE',
+				'MerchantId' => 'Amazon' } )
+il.batch( il2 )
+
+# You can have multiple response groups.
+#
+rg = ResponseGroup.new( 'Medium', 'Offers', 'Reviews' )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( il, rg )
+item_sets = resp.item_lookup_response[0].items
+
+item_sets.each do |item_set|
+  item_set.item.each do |item|
+    attribs = item.item_attributes[0]
+    puts attribs.label
+    if attribs.list_price
+      puts attribs.title, attribs.list_price[0].formatted_price
+    end
+  
+    # Availability has become a cumbersome thing to retrieve in AWSv4.
+    #
+    puts 'Availability: %s' %
+      [ item.offers[0].offer[0].offer_listing[0].availability ]
+    puts 'Average rating: %s' % [ item.customer_reviews[0].average_rating ]
+    puts 'Reviewed by %s customers.' %
+      [ item.customer_reviews[0].total_reviews ]
+  
+    puts 'Customers said:'
+    item.customer_reviews[0].review.each do |review|
+      puts '  %s (%s votes)' % [ review.summary, review.total_votes ]
+    end
+  
+    puts
+  end
+end

data/example/item_lookup2

@@ -0,0 +1,56 @@
+#!/usr/bin/ruby -w
+#
+# $Id: item_lookup2,v 1.4 2009/02/20 00:13:38 ianmacd Exp $
+
+require 'amazon/aws'
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+# Example of a batch operation.
+#
+# The MerchantId restriction is to ensure that we retrieve only items that
+# are for sale by Amazon. This is important when we later want to retrieve the
+# availability status.
+#
+il = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000065RSW',
+			       'MerchantId' => 'Amazon' } )
+il2 = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000A1INIU',
+				'MerchantId' => 'Amazon' } )
+il.batch( il2 )
+
+# You can have multiple response groups.
+#
+rg = ResponseGroup.new( 'Medium', 'Offers', 'Reviews' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( il, rg )
+item_sets = resp.item_lookup_response[0].items
+
+item_sets.each do |item_set|
+  item_set.item.each do |item|
+    attribs = item.item_attributes[0]
+    puts attribs.label
+    if attribs.list_price
+      puts attribs.title, attribs.list_price[0].formatted_price
+    end
+  
+    # Availability has become a cumbersome thing to retrieve in AWSv4.
+    #
+    puts 'Availability: %s' %
+      [ item.offers[0].offer[0].offer_listing[0].availability ]
+    puts 'Average rating: %s' % [ item.customer_reviews[0].average_rating ]
+    puts 'Reviewed by %s customers.' %
+      [ item.customer_reviews[0].total_reviews ]
+  
+    puts 'Customers said:'
+    item.customer_reviews[0].review.each do |review|
+      puts '  %s (%s votes)' % [ review.summary, review.total_votes ]
+    end
+  
+    puts
+  end
+end

data/example/item_search1

@@ -0,0 +1,30 @@
+#!/usr/bin/ruby -w
+#
+# $Id: item_search1,v 1.4 2008/04/11 19:24:24 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+is = ItemSearch.new( 'Books', { 'Title' => 'Ruby' } )
+rg = ResponseGroup.new( 'Large' )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( is, rg )
+
+items = resp.item_search_response[0].items[0].item
+
+# Available properties for first item:
+#
+puts items[0].properties
+
+items.each do |item|
+  attribs = item.item_attributes[0]
+  puts attribs.label
+  if attribs.list_price
+    puts attribs.title, attribs.list_price[0].formatted_price, ''
+  end
+end

data/example/item_search2

@@ -0,0 +1,37 @@
+#!/usr/bin/ruby -w
+#
+# $Id: item_search2,v 1.4 2008/04/28 09:59:39 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+# We can use symbols instead of string.
+#
+is = ItemSearch.new( :Music, { :Artist => 'Stranglers' } )
+rg = ResponseGroup.new( :Medium )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( is, rg, :ALL_PAGES )
+
+# Use of :ALL_PAGES means an array of responses is returned, one per page.
+#
+items = resp.collect { |r| r.item_search_response[0].items[0].item }.flatten
+
+printf( "Search returned %d items.\n", items.size )
+
+items.each do |item|
+  attribs = item.item_attributes[0]
+  puts '%s %s' % [ attribs.title, ( attribs.format ?
+				      "(#{attribs.format})" : '' ) ]
+  puts '%s (%s)' % [ attribs.manufacturer, attribs.binding ]
+  puts 'Release date: %s' % [ attribs.release_date ]
+  puts attribs.list_price[0].formatted_price if attribs.list_price
+  if item.editorial_reviews
+    puts item.editorial_reviews[0].editorial_review[0].content
+  end
+  puts
+end

data/example/item_search3

@@ -0,0 +1,23 @@
+#!/usr/bin/ruby -w
+#
+# $Id: item_search3,v 1.3 2008/04/11 19:24:24 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+is = ItemSearch.new( 'Baby', { 'Keywords' => 'pants',
+		               'MinimumPrice' => '2500',
+			       'MaximumPrice' => '4999' } )
+rg = ResponseGroup.new( 'Small' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( is, rg )
+items = resp.item_search_response[0].items[0].item
+
+printf( "Search returned %d items.\n", items.size )
+
+items.each { |item| puts item, '' }

data/example/list_lookup1

@@ -0,0 +1,29 @@
+#!/usr/bin/ruby -w
+#
+# $Id: list_lookup1,v 1.1 2008/04/27 16:36:14 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+ll = ListLookup.new( '3P722DU4KUPCP', 'Listmania' )
+ll_rg = ResponseGroup.new( 'ListInfo', 'Small' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( ll, ll_rg )
+list = resp.list_lookup_response[0].lists[0].list
+
+puts 'List Title: %s' % [ list.list_name ]
+puts 'List created: %s' % [ list.date_created ]
+puts 'List ID: %s' % [ list.list_id ]
+puts 'URL: %s' % [ list.list_url ]
+puts '%s items on list.' % [ list.total_items ]
+puts
+
+list.list_item.each_with_index do |it, idx|
+  att = it.item.item_attributes
+  printf( "%d. %s (%s)\n", idx + 1, att.title, att.product_group )
+end

data/example/list_search1

@@ -0,0 +1,30 @@
+#!/usr/bin/ruby -w
+#
+# $Id: list_search1,v 1.3 2008/04/11 19:24:24 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+person = 'Peter Duff'
+
+ls = ListSearch.new( 'WishList', { 'Name' => person } )
+ls_rg = ResponseGroup.new( 'ListInfo' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( ls, ls_rg )
+lists = resp.list_search_response[0].lists[0].list
+
+puts '%s returns the following lists:' % [ person ]
+
+lists.each do |list|
+  puts '  %s' % [ list.customer_name ]
+  puts '  List created: %s' % [ list.date_created ]
+  puts '  List ID: %s' % [ list.list_id ]
+  puts '  URL: %s' % [ list.list_url ]
+  puts '  %s items on list.' % [ list.total_items ]
+  puts
+end