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 <vipul@slaant.com>

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