1######################################################################
2 Net::Amazon 0.62
3######################################################################
4NAME
5 Net::Amazon - Framework for accessing amazon.com via REST
6
7SYNOPSIS
8 use Net::Amazon;
9
10 my $ua = Net::Amazon->new(
11 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
12 token => 'YOUR_AMZN_TOKEN',
13 secret_key => 'YOUR_AMZN_SECRET_KEY');
14
15 # Get a request object
16 my $response = $ua->search(asin => '0201360683');
17
18 if($response->is_success()) {
19 print $response->as_string(), "\n";
20 } else {
21 print "Error: ", $response->message(), "\n";
22 }
23
24ABSTRACT
25 Net::Amazon provides an object-oriented interface to amazon.com's
26 REST interface. This way it's possible to create applications
27 using Amazon's vast amount of data via a functional interface, without
28 having to worry about the underlying communication mechanism.
29
30DESCRIPTION
31 "Net::Amazon" works very much like "LWP": First you define a useragent
32 like
33
34 my $ua = Net::Amazon->new(
35 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
36 token => 'YOUR_AMZN_TOKEN',
37 secret_key => 'YOUR_AMZN_SECRET_KEY',
38 max_pages => 3,
39 );
40
41 which you pass your personal amazon developer's token (can be obtained
42 from <http://amazon.com/soap>) and (optionally) the maximum number of
43 result pages the agent is going to request from Amazon in case all
44 results don't fit on a single page (typically holding 20 items). Note
45 that each new page requires a minimum delay of 1 second to comply with
46 Amazon's one-query-per-second policy.
47
48 According to the different search methods on Amazon, there's a bunch of
49 different request types in "Net::Amazon". The user agent's convenience
50 method "search()" triggers different request objects, depending on which
51 parameters you pass to it:
52
53 "$ua->search(asin => "0201360683")"
54 The "asin" parameter has Net::Amazon search for an item with the
55 specified ASIN. If the specified value is an arrayref instead of a
56 single scalar, like in
57
58 $ua->search(asin => ["0201360683", "0596005083"])
59
60 then a search for multiple ASINs is performed, returning a list of
61 results.
62
63 "$ua->search(actor => "Adam Sandler")"
64 The "actor" parameter has the user agent search for items created by
65 the specified actor. Can return many results.
66
67 "$ua->search(artist => "Rolling Stones")"
68 The "artist" parameter has the user agent search for items created
69 by the specified artist. Can return many results.
70
71 "$ua->search(author => "Robert Jordan")"
72 The "author" parameter has the user agent search for items created
73 by the specified author. Can return many results.
74
75 "$ua->search(browsenode=>"4025", mode=>"books" [, keywords=>"perl"])"
76 Returns a list of items by category ID (node). For example node
77 "4025" is the CGI books category. You can add a keywords parameter
78 to filter the results by that keyword.
79
80 "$ua->search(exchange => 'Y04Y3424291Y2398445')"
81 Returns an item offered by a third-party seller. The item is
82 referenced by the so-called *exchange ID*.
83
84 "$ua->search(keyword => "perl xml", mode => "books")"
85 Search by keyword, mandatory parameters "keyword" and "mode". Can
86 return many results.
87
88 DETAILS Net::Amazon is based on Amazon Web Services version 4, and
89 uses WSDL version 2011-08-01.
90
91CACHING
92 Responses returned by Amazon's web service can be cached locally.
93 "Net::Amazon"'s "new" method accepts a reference to a "Cache" object.
94 "Cache" (or one of its companions like "Cache::Memory", "Cache::File",
95 etc.) can be downloaded from CPAN, please check their documentation for
96 details. In fact, any other type of cache implementation will do as
97 well, see the requirements below.
98
99 Here's an example utilizing a file cache which causes "Net::Amazon" to
100 cache responses for 30 minutes:
101
102 use Cache::File;
103
104 my $cache = Cache::File->new(
105 cache_root => '/tmp/mycache',
106 default_expires => '30 min',
107 );
108
109 my $ua = Net::Amazon->new(
110 token => 'YOUR_AMZN_TOKEN',
111 secret_key => 'YOUR_AMZN_SECRET_KEY',
112 cache => $cache,
113 );
114
115 "Net::Amazon" uses *positive* caching only, errors won't be cached.
116 Erroneous requests will be sent to Amazon every time. Positive cache
117 entries are keyed by the full URL used internally by requests submitted
118 to Amazon.
119
120 Caching isn't limited to the "Cache" class. Any cache object which
121 adheres to the following interface can be used:
122
123 # Set a cache value
124 $cache->set($key, $value);
125
126 # Return a cached value, 'undef' if it doesn't exist
127 $cache->get($key);
128
129
130COMPRESSION
131
132By default "Net::Amazon" will attempt to use HTTP compression if the
133"Compress::Zlib" module is available. Pass "compress => 0" to "->new()" to
134disable this feature.
135
136PROXY SETTINGS
137 "Net::Amazon" uses "LWP::UserAgent" under the hood to send web requests
138 to Amazon's web site. If you're in an environment where all Web traffic
139 goes through a proxy, there's two ways to configure that.
140
141 First, "Net::Amazon" picks up proxy settings from environment variables:
142
143 export http_proxy=http://proxy.my.place:8080
144
145 in the surrounding shell or setting
146
147 $ENV{http_proxy} = "http://proxy.my.place:8080";
148
149 in your Perl script will route all requests through the specified proxy.
150
151 Secondly, you can pass a user agent instance to Net::Amazon's
152 constructor:
153
154 use Net::Amazon;
155 use LWP::UserAgent;
156
157 my $ua = LWP::UserAgent->new();
158 my $na = Net::Amazon->new(
159 ua => $ua,
160 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
161 token => 'YOUR_AMZN_TOKEN',
162 secret_key => 'YOUR_AMZN_SECRET_KEY',
163 );
164 # ...
165
166 This way, you can configure $ua up front before Net::Amazon will use it.
167
168DEBUGGING
169 If something's going wrong and you want more verbosity, just bump up
170 "Net::Amazon"'s logging level. "Net::Amazon" comes with "Log::Log4perl"
171 statements embedded, which are disabled by default. However, if you
172 initialize "Log::Log4perl", e.g. like
173
174 use Net::Amazon;
175 use Log::Log4perl qw(:easy);
176
177 Log::Log4perl->easy_init($DEBUG);
178 my Net::Amazon->new();
179 # ...
180
181 you'll see what's going on behind the scenes, what URLs the module is
182 requesting from Amazon and so forth. Log::Log4perl allows all kinds of
183 fancy stuff, like writing to a file or enabling verbosity in certain
184 parts only -- check http://log4perl.sourceforge.net for details.
185
186LIVE TESTING
187 Results returned by Amazon can be incomplete or simply wrong at times,
188 due to their "best effort" design of the service. This is why the test
189 suite that comes with this module has been changed to perform its test
190 cases against canned data. If you want to perform the tests against the
191 live Amazon servers instead, just set the environment variable
192
193 NET_AMAZON_LIVE_TESTS=1
194
195WHY ISN'T THERE SUPPORT FOR METHOD XYZ?
196 Because nobody wrote it yet. If Net::Amazon doesn't yet support a method
197 advertised on Amazon's web service, you could help us out. Net::Amazon
198 has been designed to be expanded over time, usually it only takes a
199 couple of lines to support a new method, the rest is done via
200 inheritance within Net::Amazon.
201
202 Here's the basic plot:
203
204 * Get Net::Amazon from CVS. Use
205
206 # (Just hit enter when prompted for a password)
207 cvs -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon login
208 cvs -z3 -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon co Net-Amazon
209
210 If this doesn't work, just use the latest distribution from
211 net-amazon.sourceforge.net.
212
213 * Write a new Net::Amazon::Request::XYZ package, start with this
214 template
215
216 ######################################
217 package Net::Amazon::Request::XYZ;
218 ######################################
219 use base qw(Net::Amazon::Request);
220
221 ######################################
222 sub new {
223 ######################################
224 my($class, %options) = @_;
225
226 if(!exists $options{XYZ_option}) {
227 die "Mandatory parameter 'XYZ_option' not defined";
228 }
229
230 my $self = $class->SUPER::new(%options);
231
232 bless $self, $class; # reconsecrate
233 }
234
235 and add documentation. Then, create a new Net::Amazon::Response::XYZ
236 module:
237
238 ##############################
239 package Net::Amazon::Response;
240 ##############################
241 use base qw(Net::Amazon::Response);
242
243 use Net::Amazon::Property;
244
245 ##############################
246 sub new {
247 ##############################
248 my($class, %options) = @_;
249
250 my $self = $class->SUPER::new(%options);
251
252 bless $self, $class; # reconsecrate
253 }
254
255 and also add documentation to it. Then, add the line
256
257 use Net::Amazon::Request::XYZ;
258
259 to Net/Amazon.pm.
260
261 And that's it! Again, don't forget the *add documentation* part. Modules
262 without documentation are of no use to anybody but yourself.
263
264 Check out the different Net::Amazon::Request::* and
265 Net::Amazon::Response modules in the distribution if you need to adapt
266 your new module to fulfil any special needs, like a different Amazon URL
267 or a different way to handle the as_string() method. Also, post and
268 problems you might encounter to the mailing list, we're gonna help you
269 out.
270
271 If possible, provide a test case for your extension. When finished, send
272 a patch to the mailing list at
273
274 net-amazon-devel@lists.sourceforge.net
275
276 and if it works, I'll accept it and will work it into the main
277 distribution. Your name will show up in the contributor's list below
278 (unless you tell me otherwise).
279
280 SAMPLE SCRIPTS
281 There's a number of useful scripts in the distribution's eg/ directory.
282 Take "power" for example, written by Martin Streicher
283 <martin.streicher@apress.com>: I lets you perform a *power search* using
284 Amazon's query language. To search for all books written by Randal
285 Schwartz about Perl, call this from the command line:
286
287 power 'author: schwartz subject: perl'
288
289 Note that you need to quote the query string to pass it as one argument
290 to "power". If a power search returns more results than you want to
291 process at a time, just limit the number of pages, telling "power" which
292 page to start at ("-s") and which one to finish with ("-f"). Here's a
293 search for all books on the subject "computer", limited to the first 10
294 pages:
295
296 power -s 1 -f 10 'subject: computer'
297
298 Check out the script "power" in eg/ for more options.
299
300 HOW TO SEND ME PATCHES
301 If you want me to include your modification or enhancement in the
302 distribution of Net::Amazon, please do the following:
303
304 * Work off the latest CVS version. Here's the steps to get it:
305
306 CVSROOT=:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon
307 export CVSROOT
308 cvs login (just hit Enter)
309 cvs co Net-Amazon
310
311 This will create a new "Net-Amazon" directory with the latest
312 development version of "Net::Amazon" on your local machine.
313
314 * Apply your changes to this development tree.
315
316 * Run a diff between the tree and your changes it in this way:
317
318 cd Net-Amazon
319 cvs diff -Nau >patch_to_christopher.txt
320
321 * Email me "patch_to_christopher.txt". If your patch works (and you've
322 included test cases and documentation), I'll apply it on the spot.
323
324INSTALLATION
325 "Net::Amazon" depends on Log::Log4perl, which can be pulled from CPAN by
326 simply saying
327
328 perl -MCPAN -eshell 'install Log::Log4perl'
329
330 Also, it needs LWP::UserAgent and XML::Simple 2.x, which can be obtained
331 in a similar way.
332
333 Once all dependencies have been resolved, "Net::Amazon" installs with
334 the typical sequence
335
336 perl Makefile.PL
337 make
338 make test
339 make install
340
341 Make sure you're connected to the Internet while running "make test"
342 because it will actually contact amazon.com and run a couple of live
343 tests.
344
345 The module's distribution tarball and documentation are available at
346
347 http://perlmeister.com/devel/#amzn
348
349 and on CPAN.
350
351SEE ALSO
352 The following modules play well within the "Net::Amazon" framework:
353
354 "Net::Amazon::RemoteCart"
355 by David Emery <dave@skiddlydee.com> provides a complete API for
356 creating Amazon shopping carts on a local site, managing them and
357 finally submitting them to Amazon for checkout. It is available on
358 CPAN.
359
360CONTACT
361 The "Net::Amazon" project's home page is hosted on
362
363 http://net-amazon.sourceforge.net
364
365 where you can find documentation, news and the latest development and
366 stable releases for download. If you have questions about how to use
367 "Net::Amazon", want to report a bug or just participate in its
368 development, please send a message to the mailing list
369 net-amazon-devel@lists.sourceforge.net
370
371 The source code has moved from sourceforge.net to github.com. The git
372 URL is
373
374 git://github.com/boumenot/p5-Net-Amazon.git
375
376 The hope is that github.com makes collaboration much easier, and git is
377 a much more modern SCM tool.
378
379AUTHOR
380 Mike Schilli, <na@perlmeister.com> (Please contact me via the mailing
381 list: net-amazon-devel@lists.sourceforge.net )
382
383 Maintainers: Christopher Boumenot, <boumenot+na@gmail.com>
384
385 Contributors (thanks y'all!):
386
387 Andy Grundman <andy@hybridized.org>
388 Barnaby Claydon <bclaydon@perseus.com>
389 Batara Kesuma <bkesuma@gaijinweb.com>
390 Bill Fitzpatrick
391 Brian <brianbrian@gmail.com>
392 Brian Hirt <bhirt@mobygames.com>
393 Dan Kreft <dan@kreft.net>
394 Dan Sully <daniel@electricrain.com>
395 Dave Cardwell <http://davecardwell.co.uk/>
396 Jackie Hamilton <kira@cgi101.com>
397 Konstantin Gredeskoul <kig@get.topica.com>
398 Lance Cleveland <lancec@proactivewm.com>
399 Martha Greenberg <marthag@mit.edu>
400 Martin Streicher <martin.streicher@apress.com>
401 Mike Evron <evronm@dtcinc.net>
402 Padraic Renaghan <padraic@renaghan.com>
403 rayg <rayg@varchars.com>
404 Robert Graff <rgraff@workingdemo.com>
405 Robert Rothenberg <wlkngowl@i-2000.com>
406 Steve Rushe <steve@deeden.co.uk>
407 Tatsuhiko Miyagawa <miyagawa@livedoor.jp>
408 Tony Bowden <tony@kasei.com>
409 Vince Veselosky
410
411COPYRIGHT AND LICENSE
412 Copyright 2003, 2004 by Mike Schilli <na@perlmeister.com> Copyright
413 2007-2009 by Christopher Boumenot <boumenot+na@gmail.com>
414
415 This library is free software; you can redistribute it and/or modify it
416 under the same terms as Perl itself.
417
418POD ERRORS
419 Hey! The above document had some coding errors, which are explained
420 below:
421
422 Around line 748:
423 You forgot a '=back' before '=head1'
424
425