amazon.rb

Path: lib/amazon.rb
Last Update: Fri Jun 25 09:10:36 CEST 2004

$Id: amazon.rb,v 1.48 2004/06/25 07:10:36 ianmacd Exp $

 $Id: README.rdoc,v 1.13 2004/06/25 07:10:36 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[http://www.amazon.com/exec/obidos/redirect-home/calibanorg-20]
 site, the
 amazon.co.uk[http://www.amazon.co.uk/exec/obidos/redirect-home/caliban-21],
 amazon.de[http://www.amazon.de/] and amazon.co.jp[http://www.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 client, based on its IP address or hostname.
 This allows you to direct AWS operations to be performed within the correct
 geographical Amazon site for the given client. German clients can be made to
 operate within amazon.de, British clients sent to amazon.co.uk, etc.

 More features are planned for future versions, such as Amazon Web Services
 for Sellers. See the TODO file included with the software.

 == 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[https://associates.amazon.com/exec/panama/associates/join/developer/application.html].

 You should also apply for an Associates
 account[https://associates.amazon.com/exec/panama/associates/apply/]. 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[http://www.amazon.com/gp/browse.html/103-8028883-0351026?node=3435361]
 for definitive information on the capabilities and inner workings of the AWS
 API.

 ---
 Author::   Ian Macdonald <mailto:ian@caliban.org>
 Version::  0.8.3
 Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]

Classes and Modules

Module Amazon
  ::Class Amazon::Feedback
  ::Class Amazon::Product
  ::  ::Class Amazon::Product::AttributeError
  ::  ::Class Amazon::Product::Review
  ::  ::Class Amazon::Product::ThirdPartyInfo
  ::Class Amazon::ProductLine
  ::Class Amazon::Seller
Class Fixnum

[Validate]