$Id: amazon.rb,v 1.57 2006/08/09 20:07:39 ianmacd Exp $

Ruby/Amazon - a Ruby language interface to the Amazon Web Services API

Introduction

Ruby/Amazon is a Ruby language library that allows programmatic access to the popular Amazon Web site via the REST (XML over HTTP) based Amazon Web Services. In addition to the original amazon.com site, the amazon.co.uk, amazon.de, amazon.fr, amazon.ca and amazon.co.jp properties are also supported.

Although the library is still in development, it already provides support for the vast majority of the AWS v3.1 API. For example, all forms of product search are implemented, along with the transaction details API and the remote shopping-cart API.

Ruby/Amazon also offers advanced features not directly available via the AWS API, such as the ability to retrieve all results pages for a particular search, rather than having to deal with AWS responses of 10 results per page. Ruby/Amazon will even use parallel threads to improve the performance of such multi-page searches.

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 query 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 hostname. This allows you to perform AWS operations using the correct geographical Amazon site for any given client. German clients can be made to operate within amazon.de, British clients within amazon.co.uk, etc.

Installation

Please see the INSTALL file supplied with the software for details of how to install Ruby/Amazon. It’s very simple and involves running just a single script.

Prerequisites

Before you can use this library, you need to obtain an Amazon Web Services developer token.

You should also apply for an Associates account. This isn’t strictly necessary, however. If you do not explicitly provide one, the Associates token belonging to the Ruby/Amazon author will be used.

Examples

Keyword search (just one of many available types of search)

 require 'amazon/search'

 include Amazon::Search  # don't want to have to fully qualify identifiers

 ASSOCIATES_ID = "webservices-20" # if you don't have one of these, don't
                                  # pass the second argument to Request.new

 DEV_TOKEN     = "D23XFCO2UKJY82" # your development token

 # You can grab information straight from one of the Amazon sites
 #
 request  = Request.new(DEV_TOKEN, ASSOCIATES_ID)  # second argument optional
 response = request.keyword_search('ruby programming') do |product|
              printf("Found a product:\n%s---\n", product)
            end
 printf("Search had unique request ID %s\n", response.args['RequestID'])

 products = response.products
 product1 = products[0]
 puts "Properties available for the first product returned:",
   product1.properties

 # Three ways to print a property of a product:
 #
 puts product1.asin           # instance variable
 puts product1['our_price']   # feels more like a Hash
 puts product1[:authors]      # a variation on the Hash theme

 # You can also pull information from a previously saved
 # Amazon::Search::Response (which is not the same thing as using the cache
 # -- cache access is transparent)
 #
 file = File.new('/path/to/my/file.xml')
 Response.new(file) { |product| puts product }

Hopefully, the above usage is pretty much self-explanatory. Much more than this can be done, however. Please see the RDoc documentation for full details of the Ruby/Amazon API.

Remote shopping cart

 require 'amazon/shoppingcart'

 include Amazon

 DEV_TOKEN = "D23XFCO2UKJY82"   # your development token
 sc = ShoppingCart.new(DEV_TOKEN)

 ARGV.each { |asin| sc.add_items(asin, 1) }

 puts sc.purchase_url

The above snippet takes a series of one or more ASINs supplied on the command line and adds them to a remote shopping cart. It finishes by displaying a purchase URL, which can be entered into a browser, causing the contents of the cart to be uploaded to the user’s centralised Amazon shopping cart.

If you’ve read the AWS documentation, you’ll note from the above snippet that there’s no need to track the shopping cart ID or the HMAC security token assigned by the AWS servers. This state information is tracked internally within each shopping-cart object. You, the programmer, need never worry about it.

See Also

Ultimately, the way to get the most from this library is to read the AWS documentation to get a feel for what is possible, and then experiment with this library to see how the AWS calls are mapped into the Ruby world. You should also review this library’s RDoc documentation.

Please see the Amazon Web Services documentation for definitive information on the capabilities and inner workings of the AWS API.