NAME

SYNOPSIS

  use Net::Amazon;

  my $ua = Net::Amazon->new(
        associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
        token         => 'YOUR_AMZN_TOKEN',
        secret_key    => 'YOUR_AMZN_SECRET_KEY');

    # 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

  my $ua = Net::Amazon->new(
      associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
      token         => 'YOUR_AMZN_TOKEN',
      secret_key    => 'YOUR_AMZN_SECRET_KEY',
      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). Note that each new page requires a minimum delay of 1 second to comply with Amazon'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.

DETAILS Net::Amazon is based on Amazon Web Services version 4, and uses WSDL version 2011-08-01.

CACHING

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',
        secret_key  => 'YOUR_AMZN_SECRET_KEY',
        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);

COMPRESSION

PROXY SETTINGS

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, 
        associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
        token         => 'YOUR_AMZN_TOKEN',
        secret_key    => 'YOUR_AMZN_SECRET_KEY',
    );
    # ...

This way, you can configure $ua up front before Net::Amazon will use it.

DEBUGGING

    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.

LIVE TESTING

    NET_AMAZON_LIVE_TESTS=1

WHY ISN'T THERE SUPPORT FOR METHOD XYZ?

Here's the basic plot:

• Get Net::Amazon from CVS. Use

          # (Just hit enter when prompted for a password)
      cvs -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon login
      cvs -z3 -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon co Net-Amazon
      

  If this doesn't work, 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).

    power 'author: schwartz subject: perl'

    power -s 1 -f 10 'subject: computer'

INSTALLATION

    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 actually 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

"Net::Amazon::RemoteCart"

by David Emery <dave@skiddlydee.com> provides a complete API for creating Amazon shopping carts on a local site, managing them and finally submitting them to Amazon for checkout. It is available on CPAN.

CONTACT

    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

The source code has moved from sourceforge.net to github.com. The git URL is

    git://github.com/boumenot/p5-Net-Amazon.git

The hope is that github.com makes collaboration much easier, and git is a much more modern SCM tool.

AUTHOR

Maintainers: Christopher Boumenot, <boumenot+na@gmail.com>

Contributors (thanks y'all!):

    Andy Grundman <andy@hybridized.org>
    Barnaby Claydon <bclaydon@perseus.com>
    Batara Kesuma <bkesuma@gaijinweb.com>
    Bill Fitzpatrick
    Brian <brianbrian@gmail.com>
    Brian Hirt <bhirt@mobygames.com>
    Dan Kreft <dan@kreft.net>
    Dan Sully <daniel@electricrain.com>
    Dave Cardwell <http://davecardwell.co.uk/>
    Jackie Hamilton <kira@cgi101.com>
    Konstantin Gredeskoul <kig@get.topica.com>
    Lance Cleveland <lancec@proactivewm.com>
    Martha Greenberg <marthag@mit.edu>
    Martin Streicher <martin.streicher@apress.com>
    Mike Evron <evronm@dtcinc.net>
    Padraic Renaghan <padraic@renaghan.com>
    rayg <rayg@varchars.com>
    Robert Graff <rgraff@workingdemo.com>
    Robert Rothenberg <wlkngowl@i-2000.com>
    Steve Rushe <steve@deeden.co.uk>
    Tatsuhiko Miyagawa <miyagawa@livedoor.jp>
    Tony Bowden <tony@kasei.com>
    Vince Veselosky

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

POD ERRORS

Around line 761:

You forgot a '=back' before '=head1'