$Id: README,v 1.7 2004/01/22 08:13:31 ianmacd Exp $

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

Ruby/Amazon is a simple Ruby library that allows one to retrieve information
from the popular Amazon.com Web site via Amazon Web Services.

This library is still in the early stages of development, but already allows
one to search for products in various ways. Not yet supported are Web Services
for the international Amazon properties 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.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
-----------

The most important method and the only one that really warrants
explanation is Amazon::Search::Request#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:

  search(search, mode='books', heavy=HEAVY, search_type=KEYWORD_SEARCH, page=1)

where:

 - 'search' is the search string you wish to search on. Some search types
   allow multiple words, separated by spaces, whereas others allow multiple
   arguments, separated by commas. See the Amazon Web Services documentation
   for more information.
   
   In cases where 'search' allows for multiple arguments, you may either
   pass them as a single comma-separated String or as an Array.

 - '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 toys universal vhs videogames]

   'mode' is ignored in searches where it makes no sense. The search types
   in question are ASIN_SEARCH, LISTMANIA_SEARCH and SIMILARITY_SEARCH.
   
 - '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.

 - 'search_type' is the type of search being conducted. Currently supported
   types are KEYWORD_SEARCH, NODE_SEARCH, ASIN_SEARCH, UPC_SEARCH,
   AUTHOR_SEARCH, ARTIST_SEARCH, ACTOR_SEARCH, DIRECTOR_SEARCH,
   MANUFACTURER_SEARCH, LISTMANIA_SEARCH, SIMILARITY_SEARCH and POWER_SEARCH.
   All of these 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 for a single search, so the 'page'
   argument can be incremented to retrieve search results for higher multiples
   of ten.

   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#search method returns an Amazon::Search::Response
object in all but one case. That case is when 'page' was set to ALL_PAGES, in
which case an Array of Amazon::Search::Response objects is returned,
corresponding to one per page of products. If the ALL_PAGES search returns a
single page of results, then this will be returned as a single
Amazon::Search::Response, rather than as a one element Array.

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>
