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 supports 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 the XML to a file. AUTHOR Vipul Ved Prakash LICENSE This software is distributed under the same terms as perl itself.