Net::Amazon - Framework for accessing amazon.com via SOAP and XML/HTTP
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"; }
Net::Amazon provides an object-oriented interface to amazon.com's SOAP and XML/HTTP interfaces. 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.
Net::Amazon works very much like LWP: First you define a useragent like
Net::Amazon
LWP
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://amazon.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).
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:
search()
$ua->search(asin => "0201360683")
The asin parameter has Net::Amazon search for an item with the specified ASIN. Returns at most one result.
asin
$ua->search(artist => "Rolling Stones")
The artist parameter has the user agent search for items created by the specified artist. Can return many results.
artist
$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(keyword => "perl xml", mode => "books")
Search by keyword, mandatory parameters keyword and mode. Can return many results.
keyword
mode
$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.
upc
music
$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.
The user agent's search method returns a response object, which can be checked for success or failure:
search
if($resp->is_success()) { print $resp->as_string(); } else { print "Error: ", $resp->message(), "\n"; }
In case the request 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.
properties()
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 messages() (notice the plural) will return a reference to an array of message strings.
message()
messages()
Response objects always have the methods is_success(), is_error(), message(), as_string() and properties() available.
is_success()
is_error()
as_string()
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:
Net::Amazon::Property
Net::Amazon::Property::Book
Net::Amazon::Property::Music
for ($resp->properties) { print $_->Asin(), " ", $_->OurPrice(), "\n"; }
Also the specialized classes Net::Amazon::Property::Book and Net::Amazon::Property::Music feature convenience methods like authors() (returning the list of authors of a book) or album() for CDs, returning the album title.
authors()
album()
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::Amazon::Attribute::Review objects. Check the respective man pages for details on what's available.
review_set()
Net::Amazon::Attribute::ReviewSet
Net::Amazon::Attribute::Review
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:
Search by ASIN, mandatory parameter asin. Returns at most one result.
Music search by Artist, mandatory parameter artist. Can return many results.
Returns category (node) listing. Mandatory parameters browsenode (must be numeric) and mode. Can return many results.
browsenode
Keyword search, mandatory parameters keyword and mode. Can return many results.
'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.
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.
Create a new Net::Amazon useragent. $token is the value of the mandatory Amazon developer's token, which can be obtained from http://amazon.com/soap.
$token
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.
affiliate_id => $affiliate_id
your Amazon affiliate ID, if you have one. It defaults to webservices-20 which is currently (as of 06/2003) required by Amazon.
webservices-20
$resp = $ua->request($request)
Sends a request to the Amazon web service. $request is of a Net::Amazon::Request::* type and $response will be of the corresponding Net::Amazon::Response::* type.
$request
Net::Amazon::Request::*
$response
Net::Amazon::Response::*
As of this writing (07/2003), Amazon also offers its web service for the UK, Germany, and Japan. Just pass in
locale => 'uk' locale => 'de' locale => 'jp'
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.
new()
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"; }
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 documentation for details. In fact, any other type of cache implementation will do as well, see the requirements below.
new
Cache
Cache::Memory
Cache::File
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 internally by requests submitted to Amazon.
Caching isn't limited to the Cache class. Any cache object which adheres to the following 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);
If something's going wrong and you want more verbosity, just bump up Net::Amazon's logging level. Net::Amazon comes with Log::Log4perl statements embedded, which are disabled by default. However, if you initialize Log::Log4perl, e.g. like
Log::Log4perl
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 Amazon 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.
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
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
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/Net-Amazon login cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/Net-Amazon co Net-Amazon
If this doesn't work (and it didn't work at the time of this writing), just use the latest distribution from net-amazon.sourceforge.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 documentation 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@lists.sourceforge.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).
There's a number of useful scripts in the distribution's eg/ directory. Take power for example, written by Martin Streicher <martin.streicher@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
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:
-s
-f
computer
power -s 1 -f 10 'subject: computer'
Check out the script power in eg/ for more options.
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@cvs.net-amazon.sourceforge.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.
Net-Amazon
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_mike.txt
Email me patch_to_mike.txt. If your patch works (and you've included test cases and documentation), I'll apply it on the spot.
patch_to_mike.txt
Net::Amazon depends on Log::Log4perl, which can be pulled from CPAN by simply saying
perl -MCPAN -eshell 'install Log::Log4perl'
Also, it needs 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 actually contact amazon.com and run a couple of live tests.
make test
The module's distribution tarball and documentation are available at
http://perlmeister.com/devel/#amzn
and on CPAN.
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-amazon-devel@lists.sourceforge.net
Mike Schilli, <na@perlmeister.com> (Please contact me via the mailing list: net-amazon-devel@lists.sourceforge.net )
Contributors (thanks y'all!):
Barnaby Claydon <bclaydon@perseus.com> Brian Hirt <bhirt@mobygames.com> Dan Sully <daniel@electricrain.com> Jackie Hamilton <kira@cgi101.com> Konstantin Gredeskoul <kig@get.topica.com> Martha Greenberg <marthag@mit.edu> Martin Streicher <martin.streicher@apress.com> Mike Evron <evronm@dtcinc.net> Padraic Renaghan <padraic@renaghan.com> Robert Graff <rgraff@workingdemo.com> Tony Bowden <tony@kasei.com>
Copyright 2003 by Mike Schilli <na@perlmeister.com>
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Net::Amazon, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Amazon
CPAN shell
perl -MCPAN -e shell install Net::Amazon
For more information on module installation, please visit the detailed CPAN module installation guide.