$Id: README,v 1.4 2004/01/18 09:34:26 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 = "webservices-20"    # use this if you have no Associates
				    # account of your own

DEV_TOKEN     = "D23XFCO2UKJY82"    # your development token

# either grab information straight from amazon.com:
#
request  = Request.new(ASSOCIATES_ID, DEV_TOKEN)
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=true, 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.

 - '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 'true' results
   in all product details being returned, whereas a value of 'false' will
   ensure a much smaller data set is returned.

 - 'search_type' is the type of search being conducted. Currently valid
   types are KEYWORD_SEARCH, NODE_SEARCH, ASIN_SEARCH, UPC_SEARCH,
   AUTHOR_SEARCH, ARTIST_SEARCH, ACTOR_SEARCH, DIRECTOR_SEARCH,
   MANUFACTURER_SEARCH, LISTMANIA_SEARCH and SIMILARITY_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.

The Amazon::Search::Request#search method returns 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 list them for any product. In the example above, 'products'
is an Array of Amazon::Products relating to a search. To obtain the list
of properties pertaining to the first product found, you could 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 of class Array. @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

-- 
Ian Macdonald
<ian@caliban.org>
