1Net::Amazon(3)        User Contributed Perl Documentation       Net::Amazon(3)
2
3
4

NAME

6       Net::Amazon - Framework for accessing amazon.com via REST
7

SYNOPSIS

9         use Net::Amazon;
10
11         my $ua = Net::Amazon->new(
12               associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
13               token         => 'YOUR_AMZN_TOKEN',
14               secret_key    => 'YOUR_AMZN_SECRET_KEY');
15
16           # Get a request object
17         my $response = $ua->search(asin => '0201360683');
18
19         if($response->is_success()) {
20             print $response->as_string(), "\n";
21         } else {
22             print "Error: ", $response->message(), "\n";
23         }
24

ABSTRACT

26         Net::Amazon provides an object-oriented interface to amazon.com's
27         REST interface. This way it's possible to create applications
28         using Amazon's vast amount of data via a functional interface, without
29         having to worry about the underlying communication mechanism.
30

DESCRIPTION

32       "Net::Amazon" works very much like "LWP": First you define a useragent
33       like
34
35         my $ua = Net::Amazon->new(
36             associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
37             token         => 'YOUR_AMZN_TOKEN',
38             secret_key    => 'YOUR_AMZN_SECRET_KEY',
39             max_pages     => 3,
40         );
41
42       which you pass your personal amazon developer's token (can be obtained
43       from <http://amazon.com/soap>) and (optionally) the maximum number of
44       result pages the agent is going to request from Amazon in case all
45       results don't fit on a single page (typically holding 20 items).  Note
46       that each new page requires a minimum delay of 1 second to comply with
47       Amazon's one-query-per-second policy.
48
49       According to the different search methods on Amazon, there's a bunch of
50       different request types in "Net::Amazon". The user agent's convenience
51       method search() triggers different request objects, depending on which
52       parameters you pass to it:
53
54       "$ua->search(asin => "0201360683")"
55           The "asin" parameter has Net::Amazon search for an item with the
56           specified ASIN. If the specified value is an arrayref instead of a
57           single scalar, like in
58
59               $ua->search(asin => ["0201360683", "0596005083"])
60
61           then a search for multiple ASINs is performed, returning a list of
62           results.
63
64       "$ua->search(actor => "Adam Sandler")"
65           The "actor" parameter has the user agent search for items created
66           by the specified actor. Can return many results.
67
68       "$ua->search(artist => "Rolling Stones")"
69           The "artist" parameter has the user agent search for items created
70           by the specified artist. Can return many results.
71
72       "$ua->search(author => "Robert Jordan")"
73           The "author" parameter has the user agent search for items created
74           by the specified author. Can return many results.
75
76       "$ua->search(browsenode=>"4025", mode=>"books" [, keywords=>"perl"])"
77           Returns a list of items by category ID (node). For example node
78           "4025" is the CGI books category.  You can add a keywords parameter
79           to filter the results by that keyword.
80
81       "$ua->search(exchange => 'Y04Y3424291Y2398445')"
82           Returns an item offered by a third-party seller. The item is
83           referenced by the so-called exchange ID.
84
85       "$ua->search(keyword => "perl xml", mode => "books")"
86           Search by keyword, mandatory parameters "keyword" and "mode".  Can
87           return many results.
88
89           DETAILS
90                   Net::Amazon is based on Amazon Web Services version 4, and
91           uses
92                   WSDL version 2011-08-01.
93

CACHING

95       Responses returned by Amazon's web service can be cached locally.
96       "Net::Amazon"'s "new" method accepts a reference to a "Cache" object.
97       "Cache" (or one of its companions like "Cache::Memory", "Cache::File",
98       etc.) can be downloaded from CPAN, please check their documentation for
99       details. In fact, any other type of cache implementation will do as
100       well, see the requirements below.
101
102       Here's an example utilizing a file cache which causes "Net::Amazon" to
103       cache responses for 30 minutes:
104
105           use Cache::File;
106
107           my $cache = Cache::File->new(
108               cache_root        => '/tmp/mycache',
109               default_expires   => '30 min',
110           );
111
112           my $ua = Net::Amazon->new(
113               token       => 'YOUR_AMZN_TOKEN',
114               secret_key  => 'YOUR_AMZN_SECRET_KEY',
115               cache       => $cache,
116           );
117
118       "Net::Amazon" uses positive caching only, errors won't be cached.
119       Erroneous requests will be sent to Amazon every time. Positive cache
120       entries are keyed by the full URL used internally by requests submitted
121       to Amazon.
122
123       Caching isn't limited to the "Cache" class. Any cache object which
124       adheres to the following interface can be used:
125
126               # Set a cache value
127           $cache->set($key, $value);
128
129               # Return a cached value, 'undef' if it doesn't exist
130           $cache->get($key);
131

COMPRESSION

133       By default "Net::Amazon" will attempt to use HTTP compression if the
134       Compress::Zlib module is available. Pass "compress => 0" to "->new()"
135       to disable this feature.
136

PROXY SETTINGS

138       "Net::Amazon" uses "LWP::UserAgent" under the hood to send web requests
139       to Amazon's web site. If you're in an environment where all Web traffic
140       goes through a proxy, there's two ways to configure that.
141
142       First, "Net::Amazon" picks up proxy settings from environment
143       variables:
144
145           export http_proxy=http://proxy.my.place:8080
146
147       in the surrounding shell or setting
148
149           $ENV{http_proxy} = "http://proxy.my.place:8080";
150
151       in your Perl script will route all requests through the specified
152       proxy.
153
154       Secondly, you can pass a user agent instance to Net::Amazon's
155       constructor:
156
157           use Net::Amazon;
158           use LWP::UserAgent;
159
160           my $ua = LWP::UserAgent->new();
161           my $na = Net::Amazon->new(
162               ua            => $ua,
163               associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
164               token         => 'YOUR_AMZN_TOKEN',
165               secret_key    => 'YOUR_AMZN_SECRET_KEY',
166           );
167           # ...
168
169       This way, you can configure $ua up front before Net::Amazon will use
170       it.
171

DEBUGGING

173       If something's going wrong and you want more verbosity, just bump up
174       "Net::Amazon"'s logging level. "Net::Amazon" comes with "Log::Log4perl"
175       statements embedded, which are disabled by default. However, if you
176       initialize "Log::Log4perl", e.g. like
177
178           use Net::Amazon;
179           use Log::Log4perl qw(:easy);
180
181           Log::Log4perl->easy_init($DEBUG);
182           my Net::Amazon->new();
183           # ...
184
185       you'll see what's going on behind the scenes, what URLs the module is
186       requesting from Amazon and so forth. Log::Log4perl allows all kinds of
187       fancy stuff, like writing to a file or enabling verbosity in certain
188       parts only -- check http://log4perl.sourceforge.net for details.
189

LIVE TESTING

191       Results returned by Amazon can be incomplete or simply wrong at times,
192       due to their "best effort" design of the service. This is why the test
193       suite that comes with this module has been changed to perform its test
194       cases against canned data. If you want to perform the tests against the
195       live Amazon servers instead, just set the environment variable
196
197           NET_AMAZON_LIVE_TESTS=1
198

WHY ISN'T THERE SUPPORT FOR METHOD XYZ?

200       Because nobody wrote it yet. If Net::Amazon doesn't yet support a
201       method advertised on Amazon's web service, you could help us out.
202       Net::Amazon has been designed to be expanded over time, usually it only
203       takes a couple of lines to support a new method, the rest is done via
204       inheritance within Net::Amazon.
205
206       Here's the basic plot:
207
208       •   Get Net::Amazon from CVS. Use
209
210                   # (Just hit enter when prompted for a password)
211               cvs -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon login
212               cvs -z3 -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon co Net-Amazon
213
214           If this doesn't work, just use the latest distribution from
215           net-amazon.sourceforge.net.
216
217       •   Write a new Net::Amazon::Request::XYZ package, start with this
218           template
219
220               ######################################
221               package Net::Amazon::Request::XYZ;
222               ######################################
223               use base qw(Net::Amazon::Request);
224
225               ######################################
226               sub new {
227               ######################################
228                   my($class, %options) = @_;
229
230                   if(!exists $options{XYZ_option}) {
231                       die "Mandatory parameter 'XYZ_option' not defined";
232                   }
233
234                   my $self = $class->SUPER::new(%options);
235
236                   bless $self, $class;   # reconsecrate
237               }
238
239           and add documentation. Then, create a new
240           Net::Amazon::Response::XYZ module:
241
242               ##############################
243               package Net::Amazon::Response;
244               ##############################
245               use base qw(Net::Amazon::Response);
246
247               use Net::Amazon::Property;
248
249               ##############################
250               sub new {
251               ##############################
252                   my($class, %options) = @_;
253
254                   my $self = $class->SUPER::new(%options);
255
256                   bless $self, $class;   # reconsecrate
257               }
258
259           and also add documentation to it. Then, add the line
260
261               use Net::Amazon::Request::XYZ;
262
263           to Net/Amazon.pm.
264
265       And that's it! Again, don't forget the add documentation part. Modules
266       without documentation are of no use to anybody but yourself.
267
268       Check out the different Net::Amazon::Request::* and
269       Net::Amazon::Response modules in the distribution if you need to adapt
270       your new module to fulfil any special needs, like a different Amazon
271       URL or a different way to handle the as_string() method. Also, post and
272       problems you might encounter to the mailing list, we're gonna help you
273       out.
274
275       If possible, provide a test case for your extension. When finished,
276       send a patch to the mailing list at
277
278          net-amazon-devel@lists.sourceforge.net
279
280       and if it works, I'll accept it and will work it into the main
281       distribution.  Your name will show up in the contributor's list below
282       (unless you tell me otherwise).
283
284   SAMPLE SCRIPTS
285       There's a number of useful scripts in the distribution's eg/ directory.
286       Take "power" for example, written by Martin Streicher
287       <martin.streicher@apress.com>: I lets you perform a power search using
288       Amazon's query language. To search for all books written by Randal
289       Schwartz about Perl, call this from the command line:
290
291           power 'author: schwartz subject: perl'
292
293       Note that you need to quote the query string to pass it as one argument
294       to "power". If a power search returns more results than you want to
295       process at a time, just limit the number of pages, telling "power"
296       which page to start at ("-s") and which one to finish with ("-f").
297       Here's a search for all books on the subject "computer", limited to the
298       first 10 pages:
299
300           power -s 1 -f 10 'subject: computer'
301
302       Check out the script "power" in eg/ for more options.
303
304   HOW TO SEND ME PATCHES
305       If you want me to include your modification or enhancement in the
306       distribution of Net::Amazon, please do the following:
307
308       •   Work off the latest CVS version. Here's the steps to get it:
309
310               CVSROOT=:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon
311               export CVSROOT
312               cvs login (just hit Enter)
313               cvs co Net-Amazon
314
315           This will create a new "Net-Amazon" directory with the latest
316           development version of "Net::Amazon" on your local machine.
317
318       •   Apply your changes to this development tree.
319
320       •   Run a diff between the tree and your changes it in this way:
321
322               cd Net-Amazon
323               cvs diff -Nau >patch_to_christopher.txt
324
325       •   Email me "patch_to_christopher.txt". If your patch works (and
326           you've included test cases and documentation), I'll apply it on the
327           spot.
328

INSTALLATION

330       "Net::Amazon" depends on Log::Log4perl, which can be pulled from CPAN
331       by simply saying
332
333           perl -MCPAN -eshell 'install Log::Log4perl'
334
335       Also, it needs LWP::UserAgent and XML::Simple 2.x, which can be
336       obtained in a similar way.
337
338       Once all dependencies have been resolved, "Net::Amazon" installs with
339       the typical sequence
340
341           perl Makefile.PL
342           make
343           make test
344           make install
345
346       Make sure you're connected to the Internet while running "make test"
347       because it will actually contact amazon.com and run a couple of live
348       tests.
349
350       The module's distribution tarball and documentation are available at
351
352           http://perlmeister.com/devel/#amzn
353
354       and on CPAN.
355

SEE ALSO

357       The following modules play well within the "Net::Amazon" framework:
358
359       "Net::Amazon::RemoteCart"
360           by David Emery <dave@skiddlydee.com> provides a complete API for
361           creating Amazon shopping carts on a local site, managing them and
362           finally submitting them to Amazon for checkout. It is available on
363           CPAN.
364

CONTACT

366       The "Net::Amazon" project's home page is hosted on
367
368           http://net-amazon.sourceforge.net
369
370       where you can find documentation, news and the latest development and
371       stable releases for download. If you have questions about how to use
372       "Net::Amazon", want to report a bug or just participate in its
373       development, please send a message to the mailing list
374       net-amazon-devel@lists.sourceforge.net
375
376       The source code has moved from sourceforge.net to github.com.  The git
377       URL is
378
379           git://github.com/boumenot/p5-Net-Amazon.git
380
381       The hope is that github.com makes collaboration much easier, and git is
382       a much more modern SCM tool.
383

AUTHOR

385       Mike Schilli, <na@perlmeister.com> (Please contact me via the mailing
386       list: net-amazon-devel@lists.sourceforge.net )
387
388       Maintainers: Christopher Boumenot, <boumenot+na@gmail.com>
389
390       Contributors (thanks y'all!):
391
392           Andy Grundman <andy@hybridized.org>
393           Barnaby Claydon <bclaydon@perseus.com>
394           Batara Kesuma <bkesuma@gaijinweb.com>
395           Bill Fitzpatrick
396           Brian <brianbrian@gmail.com>
397           Brian Hirt <bhirt@mobygames.com>
398           Dan Kreft <dan@kreft.net>
399           Dan Sully <daniel@electricrain.com>
400           Dave Cardwell <http://davecardwell.co.uk/>
401           Jackie Hamilton <kira@cgi101.com>
402           Konstantin Gredeskoul <kig@get.topica.com>
403           Lance Cleveland <lancec@proactivewm.com>
404           Martha Greenberg <marthag@mit.edu>
405           Martin Streicher <martin.streicher@apress.com>
406           Mike Evron <evronm@dtcinc.net>
407           Padraic Renaghan <padraic@renaghan.com>
408           rayg <rayg@varchars.com>
409           Robert Graff <rgraff@workingdemo.com>
410           Robert Rothenberg <wlkngowl@i-2000.com>
411           Steve Rushe <steve@deeden.co.uk>
412           Tatsuhiko Miyagawa <miyagawa@livedoor.jp>
413           Tony Bowden <tony@kasei.com>
414           Vince Veselosky
415
417       Copyright 2003, 2004 by Mike Schilli <na@perlmeister.com> Copyright
418       2007-2009 by Christopher Boumenot <boumenot+na@gmail.com>
419
420       This library is free software; you can redistribute it and/or modify it
421       under the same terms as Perl itself.
422

POD ERRORS

424       Hey! The above document had some coding errors, which are explained
425       below:
426
427       Around line 761:
428           You forgot a '=back' before '=head1'
429
430
431
432perl v5.38.0                      2023-07-21                    Net::Amazon(3)
Impressum