On Apache
Under GNU General Public License
2012-05-24 20:00 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
Net::Amazon(3pm) User Contributed Perl Documentation Net::Amazon(3pm)
NAME
Net::Amazon - Framework for accessing amazon.com via REST
SYNOPSIS
use Net::Amazon;
my $ua = Net::Amazon->new(token => 'YOUR_AMZN_TOKEN');
# Get a request object
my $response = $ua->search(asin => '0201360683');
if($response->is_success()) {
print $response->as_string(), "\n";
} else {
print "Error: ", $response->message(), "\n";
}
ABSTRACT
Net::Amazon provides an object-oriented interface to amazon.com's
REST interface. This way it's possible to create applications
using Amazon's vast amount of data via a functional interface, without
having to worry about the underlying communication mechanism.
DESCRIPTION
"Net::Amazon" works very much like "LWP": First you define a useragent like
my $ua = Net::Amazon->new(
token => 'YOUR_AMZN_TOKEN',
max_pages => 3,
);
which you pass your personal amazon developer's token (can be obtained from <http://ama-
zon.com/soap>) and (optionally) the maximum number of result pages the agent is going to
request from Amazon in case all results don't fit on a single page (typically holding 20
items). Note that each new page requires a minimum delay of 1 second to comply with Ama-
zon's one-query-per-second policy.
According to the different search methods on Amazon, there's a bunch of different request
types in "Net::Amazon". The user agent's convenience method "search()" triggers different
request objects, depending on which parameters you pass to it:
"$ua->search(asin => "0201360683")"
The "asin" parameter has Net::Amazon search for an item with the specified ASIN. If
the specified value is an arrayref instead of a single scalar, like in
$ua->search(asin => ["0201360683", "0596005083"])
then a search for multiple ASINs is performed, returning a list of results.
"$ua->search(actor => "Adam Sandler")"
The "actor" parameter has the user agent search for items created by the specified
actor. Can return many results.
"$ua->search(artist => "Rolling Stones")"
The "artist" parameter has the user agent search for items created by the specified
artist. Can return many results.
"$ua->search(author => "Robert Jordan")"
The "author" parameter has the user agent search for items created by the specified
author. Can return many results.
"$ua->search(browsenode=>"4025", mode=>"books" [, keywords=>"perl"])"
Returns a list of items by category ID (node). For example node "4025" is the CGI
books category. You can add a keywords parameter to filter the results by that
keyword.
"$ua->search(exchange => 'Y04Y3424291Y2398445')"
Returns an item offered by a third-party seller. The item is referenced by the so-
called exchange ID.
"$ua->search(keyword => "perl xml", mode => "books")"
Search by keyword, mandatory parameters "keyword" and "mode". Can return many
results.
"$ua->search(wishlist => "1XL5DWOUFMFVJ")"
Search for all items in a specified wishlist. Can return many results.
"$ua->search(upc => "075596278324", mode => "music")"
Music search by UPC (product barcode), mandatory parameter "upc". "mode" has to be
set to "music". Returns at most one result.
"$ua->search(isbn => "0439784549")"
Book search by ISBN (International Standard Book Number), mandatory parameter "isbn".
Returns at most one result. When searching non-US locales use the 13-digit ISBN.
"$ua->search(similar => "0201360683")"
Search for all items similar to the one represented by the ASIN provided. Can return
many results.
"$ua->search(power => "subject: perl and author: schwartz", mode => "books")"
Initiate a power search for all books matching the power query. Can return many
results. See Net::Amazon::Request::Power for details.
"$ua->search(manufacturer => "Disney")"
Initiate a search for all items made by a given manufacturrer. Can return many
results. See Net::Amazon::Request::Manufacturer for details.
"$ua->search(musiclabel => "Arista")"
Initiate a search for all items made by a given music label. Can return many results.
See Net::Amazon::Request::MusicLabel for details.
"$ua->search(publisher => "o'reilly")"
Initiate a search for all items made by a given publisher. Can return many results.
See Net::Amazon::Request::Publisher for details.
"$ua->search(blended => "Perl")"
Initiate a search for items in all categories.
"$ua->search(seller => "A2GXAGU54VOP7")"
Start a search on items sold by a specific third-party seller, referenced by its ID
(not seller name).
"$ua->search(textstream => "Blah blah Rolling Stones blah blah")"
Find items related to keywords within a text stream.
The user agent's "search" method returns a response object, which can be checked for suc-
cess or failure:
if($resp->is_success()) {
print $resp->as_string();
} else {
print "Error: ", $resp->message(), "\n";
}
In case the request for an item search succeeds, the response contains one or more Amazon
'properties', as it calls the products found. All matches can be retrieved from the
Response object using it's "properties()" method.
In case the request fails, the response contains one or more error messages. The response
object's "message()" method will return it (or them) as a single string, while "mes-
sages()" (notice the plural) will return a reference to an array of message strings.
Response objects always have the methods "is_success()", "is_error()", "message()",
"total_results()", "as_string()" and "properties()" available.
"total_results()" returns the total number of results the search yielded. "properties()"
returns one or more "Net::Amazon::Property" objects of type "Net::Amazon::Property" (or
one of its subclasses like "Net::Amazon::Property::Book", "Net::Amazon::Property::Music"
or Net::Amazon::Property::DVD), each of which features accessors named after the
attributes of the product found in Amazon's database:
for ($resp->properties) {
print $_->Asin(), " ",
$_->OurPrice(), "\n";
}
In scalar context, "properties()" just returns the first "Net::Amazon::Property" object
found. Commonly available accessors to "Net::Amazon::Property" objects are "OurPrice()",
"ImageUrlLarge()", "ImageUrlMedium()", "ImageUrlSmall()", "ReleaseDate()", "Catalog()",
"Asin()", "url()", "Manufacturer()", "UsedPrice()", "ListPrice()", "ProductName()",
"Availability()", "SalesRank()", "CollectiblePrice()", "CollectibleCount()", "NumberOfOf-
ferings()", "UsedCount()", "ThirdPartyNewPrice()", "ThirdPartyNewCount()", "simi-
lar_asins()". For details, check Net::Amazon::Property.
Also, the specialized classes "Net::Amazon::Property::Book" and "Net::Amazon::Prop-
erty::Music" feature convenience methods like "authors()" (returning the list of authors
of a book) or "album()" for CDs, returning the album title.
Customer reviews: Every property features a "review_set()" method which returns a
"Net::Amazon::Attribute::ReviewSet" object, which in turn offers a list of "Net::Ama-
zon::Attribute::Review" objects. Check the respective man pages for details on what's
available.
Requests behind the scenes
"Net::Amazon"'s "search()" method is just a convenient way to create different kinds of
request objects behind the scenes and trigger them to send requests to Amazon.
Depending on the parameters fed to the "search" method, "Net::Amazon" will determine the
kind of search requested and create one of the following request objects:
Net::Amazon::Request::ASIN
Search by ASIN, mandatory parameter "asin". Returns at most one result.
Net::Amazon::Request::Actor
Music search by Actor, mandatory parameter "actor". Can return many results.
Net::Amazon::Request::Artist
Music search by Artist, mandatory parameter "artist". Can return many results.
Net::Amazon::Request::Author
Music search by Author, mandatory parameter "author". Can return many results.
Net::Amazon::Request::BrowseNode
Returns category (node) listing. Mandatory parameters "browsenode" (must be numeric)
and "mode". Can return many results.
Net::Amazon::Request::Keyword
Keyword search, mandatory parameters "keyword" and "mode". Can return many results.
Net::Amazon::Request::UPC
Music search by UPC (product barcode), mandatory parameter "upc". "mode" has to be
set to "music". Returns at most one result.
Net::Amazon::Request::Blended
'Blended' search on a keyword, resulting in matches across the board. No 'mode'
parameter is allowed. According to Amazon's developer's kit, this will result in up to
three matches per category and can yield a total of 45 matches.
Net::Amazon::Request::Power
Understands power search strings. See Net::Amazon::Request::Power for details. Manda-
tory parameter "power".
Net::Amazon::Request::Manufacturer
Searches for all items made by a given manufacturer. Mandatory parameter "manufac-
turer". With the change to AWS4, manufacturer is no longer used to search for pub-
lishers. To search via publisher use Net::Amazon::Request::Publisher.
Net::Amazon::Request::Publisher
Searches for all items made by a given manufacturer. Mandatory parameter "publisher".
Net::Amazon::Request::Similar
Finds items similar to a given one.
Net::Amazon::Request::Wishlist
Find item on someone's wish list.
Net::Amazon::Request::Seller
Searches for a third-party seller on Amazon by seller ID. This search is different
than the previous ones, since it doesn't return Amazon items, but a single seller
record. Don't use the "properties()" method on the response, use "result()" instead,
which returns a Net::Amazon::Result::Seller object. Check the manpage for details.
Net::Amazon::Request::Exchange
Searches for items offered by third-party sellers. Items are referenced by their so-
called Exchange ID. Similar to Net::Amazon::Request::Seller, this request doesn't
return a list of Amazon properties, so please use "result()" instead, which will
return a single Net::Amazon::Result::Seller::Listing item. Check the manpage for
details on what attributes are available there.
Check the respective man pages for details on these request objects. Request objects are
typically created like this (with a Keyword query as an example):
my $req = Net::Amazon::Request::Keyword->new(
keyword => 'perl',
mode => 'books',
);
and are handed over to the user agent like that:
# Response is of type Net::Amazon::Response::ASIN
my $resp = $ua->request($req);
The convenient "search()" method just does these two steps in one.
METHODS
$ua = Net::Amazon->new(token => $token, ...)
Create a new Net::Amazon useragent. $token is the value of the mandatory Amazon devel-
oper's token, which can be obtained from <http://amazon.com/soap>.
Additional optional parameters:
"max_pages => $max_pages"
Sets how many result pages the module is supposed to fetch back from Amazon, which
only sends back 10 results per page. Since each page requires a new query to Ama-
zon, at most one query per second will be made in "strict" mode to comply with
Amazon's terms of service. This will impact performance if you perform a search
returning many pages of results.
"strict => 1"
Makes sure that "Net::Amazon" complies with Amazon's terms of service by limiting
the number of outgoing requests to 1 per second. Defaults to 1, enabling rate lim-
iting as defined via "rate_limit".
"rate_limit => $reqs_per_sec"
Sets the rate limit to $reqs_per_sec requests per second if rate limiting has been
enabled with "strict" (see above). Defaults to 1, limiting the number of outgoing
requests to 1 per second.
"$resp = $ua->request($request)"
Sends a request to the Amazon web service. $request is of a "Net::Ama-
zon::Request::*" type and $response will be of the corresponding
"Net::Amazon::Response::*" type.
Modes
Every search method takes a mode parameter. The mode parameter is used to narrow the
search to a specific field. For example, when searching by actor you can search by
DVD, DigitalMusic, Merchants, VHS, and Video. By default DVD is used when searching
by actor. The modes available are dependent upon the type of search, and locale the
search is conducted in.
Determining the modes available to a search type are auto-generated from data pub-
lished by Amazon on their web site. A man page is available for each type of search.
The man page lists the default value if a mode is not specified. A list of mode val-
ues is also provided. The man page's name is of the form Net::Amazon::Validate::Item-
Search::<locale>::<type>.
<locale> is one of any ca, de, fr, jp, uk, or us.
<type> is one of Actor, Artist, Author, BrowseNode, Director, Keywords, Manufacturer,
MusicLabel, Power, Publisher, TextStream, or UPC.
Accessing foreign Amazon Catalogs
As of this writing (01/2007), Amazon also offers its web service for the UK, Germany,
Canada, France, and Japan. Just pass in
locale => 'ca'
locale => 'de'
locale => 'fr'
locale => 'jp'
locale => 'uk'
locale => 'us'
respectively to "Net::Amazon"'s constructor "new()" and instead of returning results
sent by the US mothership, it will query the particular country's catalog and show
prices in (gack!) local currencies.
EXAMPLE
Here's a full-fledged example doing a artist search:
use Net::Amazon;
use Net::Amazon::Request::Artist;
use Data::Dumper;
die "usage: $0 artist\n(use Zwan as an example)\n"
unless defined $ARGV[0];
my $ua = Net::Amazon->new(
token => 'YOUR_AMZN_TOKEN',
);
my $req = Net::Amazon::Request::Artist->new(
artist => $ARGV[0],
);
# Response is of type Net::Amazon::Artist::Response
my $resp = $ua->request($req);
if($resp->is_success()) {
print $resp->as_string, "\n";
} else {
print $resp->message(), "\n";
}
And here's one displaying someone's wishlist:
use Net::Amazon;
use Net::Amazon::Request::Wishlist;
die "usage: $0 wishlist_id\n" .
"(use 1XL5DWOUFMFVJ as an example)\n" unless $ARGV[0];
my $ua = Net::Amazon->new(
token => 'YOUR_AMZN_TOKEN',
);
my $req = Net::Amazon::Request::Wishlist->new(
id => $ARGV[0]
);
# Response is of type Net::Amazon::ASIN::Response
my $resp = $ua->request($req);
if($resp->is_success()) {
print $resp->as_string, "\n";
} else {
print $resp->message(), "\n";
}
DETAILS
Net::Amazon is based on Amazon Web Services version 4, and uses
WSDL version 2007-01-17.
CACHING
Responses returned by Amazon's web service can be cached locally. "Net::Amazon"'s "new"
method accepts a reference to a "Cache" object. "Cache" (or one of its companions like
"Cache::Memory", "Cache::File", etc.) can be downloaded from CPAN, please check their doc-
umentation for details. In fact, any other type of cache implementation will do as well,
see the requirements below.
Here's an example utilizing a file cache which causes "Net::Amazon" to cache responses for
30 minutes:
use Cache::File;
my $cache = Cache::File->new(
cache_root => '/tmp/mycache',
default_expires => '30 min',
);
my $ua = Net::Amazon->new(
token => 'YOUR_AMZN_TOKEN',
cache => $cache,
);
"Net::Amazon" uses positive caching only, errors won't be cached. Erroneous requests will
be sent to Amazon every time. Positive cache entries are keyed by the full URL used inter-
nally by requests submitted to Amazon.
Caching isn't limited to the "Cache" class. Any cache object which adheres to the follow-
ing interface can be used:
# Set a cache value
$cache->set($key, $value);
# Return a cached value, 'undef' if it doesn't exist
$cache->get($key);
PROXY SETTINGS
"Net::Amazon" uses "LWP::UserAgent" under the hood to send web requests to Amazon's web
site. If you're in an environment where all Web traffic goes through a proxy, there's two
ways to configure that.
First, "Net::Amazon" picks up proxy settings from environment variables:
export http_proxy=http://proxy.my.place:8080
in the surrounding shell or setting
$ENV{http_proxy} = "http://proxy.my.place:8080";
in your Perl script will route all requests through the specified proxy.
Secondly, you can pass a user agent instance to Net::Amazon's constructor:
use Net::Amazon;
use LWP::UserAgent;
my $ua = LWP::UserAgent->new();
my $na = Net::Amazon->new(ua => $ua, token => 'YOUR_AMZN_TOKEN');
# ...
This way, you can configure $ua up front before Net::Amazon will use it.
DEBUGGING
If something's going wrong and you want more verbosity, just bump up "Net::Amazon"'s log-
ging level. "Net::Amazon" comes with "Log::Log4perl" statements embedded, which are dis-
abled by default. However, if you initialize "Log::Log4perl", e.g. like
use Net::Amazon;
use Log::Log4perl qw(:easy);
Log::Log4perl->easy_init($DEBUG);
my Net::Amazon->new();
# ...
you'll see what's going on behind the scenes, what URLs the module is requesting from Ama-
zon and so forth. Log::Log4perl allows all kinds of fancy stuff, like writing to a file or
enabling verbosity in certain parts only -- check http://log4perl.sourceforge.net for
details.
LIVE TESTING
Results returned by Amazon can be incomplete or simply wrong at times, due to their "best
effort" design of the service. This is why the test suite that comes with this module has
been changed to perform its test cases against canned data. If you want to perform the
tests against the live Amazon servers instead, just set the environment variable
NET_AMAZON_LIVE_TESTS=1
WHY ISN'T THERE SUPPORT FOR METHOD XYZ?
Because nobody wrote it yet. If Net::Amazon doesn't yet support a method advertised on
Amazon's web service, you could help us out. Net::Amazon has been designed to be expanded
over time, usually it only takes a couple of lines to support a new method, the rest is
done via inheritance within Net::Amazon.
Here's the basic plot:
* Get Net::Amazon from CVS. Use
# (Just hit enter when prompted for a password)
cvs -d:pserver:anonymous AT cvs.net:/cvsroot/net-amazon login
cvs -z3 -d:pserver:anonymous AT cvs.net:/cvsroot/net-amazon co Net-Amazon
If this doesn't work, just use the latest distribution from net-amazon.source-
forge.net.
* Write a new Net::Amazon::Request::XYZ package, start with this template
######################################
package Net::Amazon::Request::XYZ;
######################################
use base qw(Net::Amazon::Request);
######################################
sub new {
######################################
my($class, %options) = @_;
if(!exists $options{XYZ_option}) {
die "Mandatory parameter 'XYZ_option' not defined";
}
my $self = $class->SUPER::new(%options);
bless $self, $class; # reconsecrate
}
and add documentation. Then, create a new Net::Amazon::Response::XYZ module:
##############################
package Net::Amazon::Response;
##############################
use base qw(Net::Amazon::Response);
use Net::Amazon::Property;
##############################
sub new {
##############################
my($class, %options) = @_;
my $self = $class->SUPER::new(%options);
bless $self, $class; # reconsecrate
}
and also add documentation to it. Then, add the line
use Net::Amazon::Request::XYZ;
to Net/Amazon.pm.
And that's it! Again, don't forget the add documentation part. Modules without docu-
mentation are of no use to anybody but yourself.
Check out the different Net::Amazon::Request::* and Net::Amazon::Response modules in
the distribution if you need to adapt your new module to fulfil any special needs,
like a different Amazon URL or a different way to handle the as_string() method. Also,
post and problems you might encounter to the mailing list, we're gonna help you out.
If possible, provide a test case for your extension. When finished, send a patch to
the mailing list at
net-amazon-devel AT lists.net
and if it works, I'll accept it and will work it into the main distribution. Your
name will show up in the contributor's list below (unless you tell me otherwise).
SAMPLE SCRIPTS
There's a number of useful scripts in the distribution's eg/ directory. Take "power"
for example, written by Martin Streicher <martin.streicher AT apress.com>: I lets you
perform a power search using Amazon's query language. To search for all books written
by Randal Schwartz about Perl, call this from the command line:
power 'author: schwartz subject: perl'
Note that you need to quote the query string to pass it as one argument to "power". If
a power search returns more results than you want to process at a time, just limit the
number of pages, telling "power" which page to start at ("-s") and which one to finish
with ("-f"). Here's a search for all books on the subject "computer", limited to the
first 10 pages:
power -s 1 -f 10 'subject: computer'
Check out the script "power" in eg/ for more options.
HOW TO SEND ME PATCHES
If you want me to include your modification or enhancement in the distribution of
Net::Amazon, please do the following:
* Work off the latest CVS version. Here's the steps to get it:
CVSROOT=:pserver:anonymous AT cvs.net:/cvsroot/net-amazon
export CVSROOT
cvs login (just hit Enter)
cvs co Net-Amazon
This will create a new "Net-Amazon" directory with the latest development version
of "Net::Amazon" on your local machine.
* Apply your changes to this development tree.
* Run a diff between the tree and your changes it in this way:
cd Net-Amazon
cvs diff -Nau >patch_to_christopher.txt
* Email me "patch_to_christopher.txt". If your patch works (and you've included test
cases and documentation), I'll apply it on the spot.
INSTALLATION
"Net::Amazon" depends on Log::Log4perl, which can be pulled from CPAN by simply saying
perl -MCPAN -eshell 'install Log::Log4perl'
Also, it needs LWP::UserAgent and XML::Simple 2.x, which can be obtained in a similar way.
Once all dependencies have been resolved, "Net::Amazon" installs with the typical sequence
perl Makefile.PL
make
make test
make install
Make sure you're connected to the Internet while running "make test" because it will actu-
ally contact amazon.com and run a couple of live tests.
The module's distribution tarball and documentation are available at
http://perlmeister.com/devel/#amzn
and on CPAN.
SEE ALSO
The following modules play well within the "Net::Amazon" framework:
"Net::Amazon::RemoteCart"
by David Emery <dave AT skiddlydee.com> provides a complete API for creating Amazon shop-
ping carts on a local site, managing them and finally submitting them to Amazon for
checkout. It is available on CPAN.
CONTACT
The "Net::Amazon" project's home page is hosted on
http://net-amazon.sourceforge.net
where you can find documentation, news and the latest development and stable releases for
download. If you have questions about how to use "Net::Amazon", want to report a bug or
just participate in its development, please send a message to the mailing list net-ama-
zon-devel AT lists.net
AUTHOR
Mike Schilli, <na AT perlmeister.com> (Please contact me via the mailing list: net-ama-
zon-devel AT lists.net )
Maintainers: Christopher Boumenot, <boumenot+na AT gmail.com>
Contributors (thanks y'all!):
Andy Grundman <andy AT hybridized.org>
Barnaby Claydon <bclaydon AT perseus.com>
Batara Kesuma <bkesuma AT gaijinweb.com>
Bill Fitzpatrick
Brian <brianbrian AT gmail.com>
Brian Hirt <bhirt AT mobygames.com>
Dan Kreft <dan AT kreft.net>
Dan Sully <daniel AT electricrain.com>
Jackie Hamilton <kira AT cgi101.com>
Konstantin Gredeskoul <kig AT get.com>
Lance Cleveland <lancec AT proactivewm.com>
Martha Greenberg <marthag AT mit.edu>
Martin Streicher <martin.streicher AT apress.com>
Mike Evron <evronm AT dtcinc.net>
Padraic Renaghan <padraic AT renaghan.com>
rayg <rayg AT varchars.com>
Robert Graff <rgraff AT workingdemo.com>
Robert Rothenberg <wlkngowl AT i-2000.com>
Steve Rushe <steve AT deeden.uk>
Tatsuhiko Miyagawa <miyagawa AT livedoor.jp>
Tony Bowden <tony AT kasei.com>
COPYRIGHT AND LICENSE
Copyright 2003, 2004 by Mike Schilli <na AT perlmeister.com>
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
perl v5.8.8 2007-11-11 Net::Amazon(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-24 20:00 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)