NAME

WWW::Spinn3r - An interface to the Spinn3r API (http://www.spinn3r.com)

SYNOPSIS

 use WWW::Spinn3r;
 use DateTime;

 my $API = { 
    vendor          => 'acme',   # required
    limit           => 5, 
    lang            => 'en',
    tier            => '0:5', 
    after           => DateTime->now()->subtract(hours => 48),
 };

 my $spnr = new WWW::Spinn3r ( 
    api => 'permalink.getDelta', params => $API, debug => 1);
 );

 while(1) { 
     my $item = $spnr->next;
     print $item->{title};
     print $item->{link};
     print $item->{dc}->{source};
     print $item->{description};
 }

DESCRIPTION

WWW::Spinn3r is an iterative interface to the Spinn3r API. The Spinn3r API is implemented over REST and XML and documented at http://spinn3r.com/documentation.

OBTAINING A VENDOR KEY

Spinn3r service is available through a vendor key, which you can get from the good folks at Tailrank, http://spinn3r.com/contact.

HOW TO USE

Most commonly, you'll need just two functions from this module: new() and next(). new() creates a new instance of the API and next() returns the next item from the Spinn3r feed, as a reference to a hash. Details are below.

new()

The contructor. This function takes

supports the following parameters:

api

permalink.getDelta or feed.getDelta or another API supported by Spinn3r.

params

These are parameters that are passed to the API call. See http://spinn3r.com/documentation for a list of available parameters and their values.

The version parameter to the API is a function of version of this module. For instance Spinn3r API version 2.1.3 corresponds to version 2.001003xx. The version accessor method returns the version of the API.

If the version of the spinn3r API has changed, you can specify it as a parameter. While the module is not guranteed to work with higher versions of the Spinn3r API it is designed for, it might if the underlying formats and encodings have not changed.

debug

Emits debug noise on STDOUT if set to 1.

retries

The number of HTTP retries in case of a 5xx failure from the API. The default is 5.

next()

This method returns the next item from the Spinn3r feed. The item is a reference to a hash, which contains an RSS item as decoded by XML::RSS.

The module transparently fetches a new set of results from Spinn3r, using the api:next_request_url returned by Spinn3r with every request, and caches the result to implement next().

You can control the number of results that are fetched with every call by changing the limit parameter at new().

next_feed()

This method returns the raw XML returned by the next API call. This SHOULD NOT be mixed with next() - either use next() and have WWW::Spinn3r manage the iteration, or use next_feed() and manage the iteration yourself. Note that next_feed() does not set the next_url(), which has to be set explicitely, by you, after the first call.

next_url()

The next API URL that WWW::Spinn3r will fetch. This is set to the api:next_request_url value returned by Spinn3r in the next() method. This is a read/write accessor method, so you can manually set the next_url() should you want to, for instance if you are using the next_feed() interface.

last_url()

The last API URL that was fetched.

DATE STRING FORMAT

Spinn3r support ISO 8601 timestamps in the after parameter. To create ISO 8601 timestamps, use the DateTime module that returns ISO 8601 date strings by default. eg:

 after => DateTime->now()->subtract(hours => 48),
 after => DateTime->now()->subtract(days => 31),

REPORTING BUGS

Bugs should be reported at http://rt.cpan.org

TODO

Implement deflate compression.

Implement saving to a file and expose next_feed()

AUTHOR

Vipul Ved Prakash <vipul@slaant.com>

LICENSE

This software is distributed under the same terms as perl itself.

cpanm WWW::Spinn3r

perl -MCPAN -e shell
install WWW::Spinn3r