papercavalier-ruby-aaws 0.8.1

data/README.rdoc

@@ -0,0 +1,140 @@
+= 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-11-01/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://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://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.8.1
+=== {gzip'ed tar archive}[http://caliban.org/files/ruby/ruby-aws-0.8.1.tar.gz]
+=== {Ruby Gem}[http://caliban.org/files/ruby/ruby-aaws-0.8.1.gem]
+=== {Fedora 12 RPM}[http://caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.8.1-1.fc12.noarch.rpm]
+=== {Fedora 12 doc RPM}[http://caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.8.1-1.fc12.noarch.rpm]
+=== {Fedora 12 source RPM}[http://caliban.org/files/redhat/SRPMS/ruby-aws-0.8.1-1.fc12.src.rpm]
+
+
+---
+Author::   Ian Macdonald <mailto:ian@caliban.org>
+Version::  0.8.1
+Copyright:: (C) 2008-2010 Ian Macdonald
+Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'papercavalier-ruby-aaws'
+    gemspec.summary = 'Ruby/AWS is a Ruby wrapper to the Amazon Product Advertising API.'
+    gemspec.email = 'code@papercavalier.com'
+    gemspec.homepage = 'http://github.com/papercavalier/ruby-aaws'
+    gemspec.description = 'Ruby/AWS is a Ruby wrapper to the Amazon Product Advertising API.'
+    gemspec.authors = ['Ian Macdonald']
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts 'Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler'
+end

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:patch: 1
+:major: 0
+:minor: 8
+:build: 

data/example/batch_operation

@@ -0,0 +1,28 @@
+#!/usr/bin/ruby -w
+#
+# $Id: batch_operation,v 1.3 2010/02/20 16:49:11 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 )
+is.response_group = rg
+
+batched_response = req.search( is )
+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.4 2010/02/20 16:49:11 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.response_group ||= ResponseGroup.new( 'BrowseNodeInfo' )
+  resp = req.search( bnl )
+
+  #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.4 2010/02/20 16:49:12 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+ccl = CustomerContentLookup.new( 'AJDWXANG1SYZP' )
+ccl.response_group = ResponseGroup.new( 'CustomerReviews' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( ccl )
+
+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.2 2010/02/20 16:49:12 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+ccs = CustomerContentSearch.new( 'ian@caliban.org' )
+ccs.response_group = ResponseGroup.new( 'CustomerInfo' )
+
+req = Request.new
+req.locale = 'us'
+
+resp = req.search( ccs )
+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,78 @@
+#!/usr/bin/ruby -w
+#
+# $Id: example1,v 1.6 2010/02/20 16:49:12 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', { 'Title' => 'ruby programming' } )
+
+# Create a response group object. Examples of response groups are 'Small',
+# 'Medium' and 'Large'. 'Large' returns all data about an item.
+#
+is.response_group = ResponseGroup.new( 'Large' )
+
+# Search for the items, passing the result into a block.
+#
+nr_items = 0
+page_nr = 0
+response = request.search( is, :ALL_PAGES ) do |page|
+  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,24 @@
+#!/usr/bin/ruby -w
+#
+# $Id: help1,v 1.2 2010/02/20 16:49:12 ianmacd Exp $
+
+require 'amazon/aws/search'
+
+include Amazon::AWS
+include Amazon::AWS::Search
+
+h = Help.new( 'ResponseGroup', 'Large' )
+h.response_group = ResponseGroup.new( 'Help' )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( h )
+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.7 2010/02/20 16:49:12 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.
+#
+il.response_group = ResponseGroup.new( 'Medium', 'Offers', 'Reviews' )
+
+req = Request.new
+req.locale = 'uk'
+
+resp = req.search( il )
+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