$Id: README,v 1.10 2004/01/31 23:57:42 ianmacd Exp $

INTRODUCTION
------------

Ruby/Amazon is a Ruby language library that allows one to retrieve information
from the popular Amazon Web site via Amazon Web Services. As of version 0.3.0,
support for not only the original American amazon.com site is included, but
also the amazon.co.uk, amazon.de and amazon.co.jp properties. This version
also has preliminary support for Amazon Marketplace.

This library is still in development, but already allows one to search for
and retrieve product information in various ways. Not yet supported are many of
the searches added in Amazon Web Services v3 and XSLT formatted responses.

More features are planned for future versions.


INSTALLATION
------------

Please see the INSTALL file for details of how to install Ruby/Amazon.


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. This isn't strictly
necessary, but may be needed in the future to exploit new functionality:

  https://associates.amazon.com/exec/panama/associates/apply/


EXAMPLE
-------

require 'amazon'

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

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

DEV_TOKEN     = "D23XFCO2UKJY82"    # your development token

# either grab information straight from amazon.com:
#
request  = Request.new(DEV_TOKEN, ASSOCIATES_ID)  # second argument optional
response = request.keyword_search('ruby programming')
products = response.parse
p products

# or, pull it from a previously saved Amazon::Search::Response:
#
file     = File.new('/path/to/my/file.xml')
response = Response.new(file)
products = response.parse
p products


EXPLANATION
-----------

Please see the RDoc documentation for information on how this library works.
The software is in a state of flux at the moment, so I'm holding off on
writing exhaustive documentation until things have firmed up a little more.

However, to get you started, the most obviously useful method is
Amazon::Search::Request#keyword_search. In the example above, it was used in
its simplest form, with many of its arguments assuming their default values.
However, many of these values can be changed.

The full form of the method is as follows:

  keyword_search(term, mode='books', heavy=HEAVY, page=1, price=nil)   

where:

 - 'term' is the search string you wish to search on. This can consist of
   multiple words, separated by spaces.
   
 - 'mode' is the mode of the search, which relates to the category of product
   to be searched. Valid modes are returned by the module method
   Amazon::Search.modes, which currently returns the following Array:
   
   %w[baby books classical dvd electronics garden kitchen magazines music
      pc-hardware photo software tools toys universal vhs videogames]

 - 'heavy' denotes the heaviness of the search. A value of HEAVY results in
   all product details being returned, whereas a value of LITE (or LIGHT) will
   ensure a much smaller data set is returned. HEAVY, LITE and LIGHT are
   constants within Amazon::Search.

 - 'page' is the results page number to retrieve. Currently, the Web Services
   API will return no more than 10 products per search, so the 'page' argument
   can be incremented to retrieve subsequent multiples of ten search results.

   An alternative is to use the special 'page' value of ALL_PAGES, which
   returns results for all pages pertaining to a search. Note that such
   searches may be slow to return, as the request for each page is limited to
   one per second to remain in compliance with the Web Services licence.


The Amazon::Search::Request#keyword_search method returns an
Amazon::Search::Response object, except when 'page' was set to ALL_PAGES, in
which case an Array of Amazon::Search::Response objects is returned, one per
page of products.

An Amazon::Search::Response object by itself isn't of much use, unless you
want to look at the XML returned by Amazon. Once you've got such an object,
you'll probably want to invoke the Amazon::Search::Response#parse method,
which will return an Array of Amazon::Product objects.

The relevant information pertaining to each product is contained in that
object's instance variables. These differ by category of product, but you can
easily find out what they are. In the search example above, 'products' is an
Array of Amazon::Products. To obtain the list of properties pertaining to the
first product found, you would do this:

  p products[0].instance_variables

This might return the following Array:

  ["@isbn", "@manufacturer", "@thirdpartynewprice", "@productname", "@url",
  "@reviews", "@imageurllarge", "@nummedia", "@browselist", "@releasedate",
  "@usedprice", "@asin", "@imageurlmedium", "@media", "@authors", "@ourprice",
  "@availability", "@imageurlsmall", "@salesrank", "@catalog", "@listprice"]

With this knowledge, you can print out the data by calling the relevant
attribute reader method:

  puts products[0].productname, products[0].ourprice

  The Ruby Way
  $27.99

Hopefully, you get the picture.

Most of the attributes will be simple Strings, but some -- such as @actors,
@authors and @directors -- are Array objects. @reviews is a little special, as
it is an Array of Amazon::Product::Review objects. Each of these contains the
attributes @rating, @summary and @comment.


SEE ALSO
--------

Please see the Amazon Web Services documentation for information on
the various types of searches that can be performed:

  http://www.amazon.com/gp/browse.html/103-8028883-0351026?node=3435361


LICENCE
-------

This software is offered under the GNU GENERAL PUBLIC LICENSE, a copy of which
is included.

-- 
Ian Macdonald
<ian@caliban.org>
