NAME

WebService::Google::Reader - Perl interface to the Google Reader API

SYNOPSIS

    use WebService::Google::Reader;

    my $reader = WebService::Google::Reader->new(
        host     => 'www.inoreader.com',
        appid    => $appid,
        appkey   => $appey,
        username => $username,
        password => $password,
    );

    my $feed = $reader->unread(count => 100);
    my @entries = $feed->entries;

    # Fetch past entries.
    while ($reader->more($feed)) {
        my @entries = $feed->entries;
    }

DESCRIPTION

The "WebService::Google::Reader" module provides an interface to webservices using the Google Reader API. The only tested webservice at this time is www.inoreader.com.

METHODS

$reader = WebService::Google::Reader->new: Creates a new WebService::Google::Reader object. The following named parameters are accepted:

host: The hostname of the service.
username and password: Required for accessing any personalized or account-related functionality (reading-list, editing, etc.).
appid and appkey: Inoreader requires users to also obtain an appid and appkey.
See <http://www.inoreader.com/developers/register-app>
https / secure: Use https scheme for all requests, even when not required.
ua: An optional useragent object.
debug: Enable debugging. Default: 0. This will dump the headers and content for both requests and responses.
compress: Disable compression. Default: 1. This is useful when debugging is enabled and you want to read the response content.

$error = $reader->error: Returns the error string, if any.
$response = $reader->response: Returns an HTTP::Response object for the last submitted request. Can be used to determine the details of an error.

Feed generators

The following methods request an ATOM feed and return a subclass of "XML::Atom::Feed". These methods accept the following optional named parameters:

order / sort: The sort order of the entries: desc (default) or asc in time. When ordering by asc, Google only returns entries within 30 days, whereas the default order has no limitation.
start_time: Request entries only newer than this time (represented as a unix timestamp).
exclude(feed => $feed|[@feeds], tag => $tag|[@tags]): Accepts a hash reference to one or more of feed / tag / state. Each of which is a scalar or array reference.

feed($feed): Accepts a single feed url.
tag($tag): Accepts a single tag name. See "TAGS"
state($state): Accepts a single state name. See "STATES".
shared: Shortcut for state('broadcast').
starred: Shortcut for state('starred').
unread: Shortcut for state('reading-list', exclude => { state => 'read' })
liked: Shortcut for state('like').
search($query, %params): Accepts a query string and the following named parameters:

feed / state / tag: One or more (as a array reference) feed / state / tag to search. The default is to search all feed subscriptions.
results: The total number of search results: defaults to 1000.
count: The number of entries per fetch: defaults to 40.
order / sort: The sort order of the entries: desc (default) or asc in time.

more / previous / next: A feed generator only returns $count entries. If more are available, calling this method will return a feed with the next $count entries.

List generators

The following methods return an object of type "WebService::Google::Reader::ListElement".

counts: Returns a list of subscriptions and a count of unread entries. Also listed are any tags or states which have positive unread counts. The following accessors are provided: id, count. The maximum count reported is 1000.
feeds: Returns the list of user subscriptions. The following accessors are provided: id, title, categories, firstitemmsec. categories is a reference to a list of "ListElement"s providing accessors: id, label.
preferences: Returns the list of preference settings. The following accessors are provided: id, value.
tags: Returns the list of user-created tags. The following accessors are provided: id, shared.
userinfo: Returns the list of user information. The following accessors are provided: isBloggerUser, userId, userEmail.

Edit feeds

The following methods are used to edit feed subscriptions.

edit_feed($feed|[@feeds], %params): Requires a feed url or Feed object, or a reference to a list of them. The following named parameters are accepted:

subscribe / unsubscribe: Flag indicating whether the target feeds should be added or removed from the user's subscriptions.
title: Accepts a title to associate with the feed. This probaby wouldn't make sense to use when there are multiple feeds. (Maybe later will consider allowing a list here and zipping the feed and title lists).
tag / state / untag / unstate: Accepts a tag / state or a reference to a list of tags / states for which to associate / unassociate the target feeds.

tag_feed($feed|[@feeds], @tags)
untag_feed($feed|[@feeds], @tags)
state_feed($feed|[@feeds], @states)
unstate_feed($feed|[@feeds], @states): Associate / unassociate a list of tags / states from a feed / feeds.
subscribe(@feeds|[@feeds])
unsubscribe(@feeds|[@feeds]): Subscribe or unsubscribe from a list of feeds.
rename_feed($feed|[@feeds], $title): Renames a feed to the given title.
mark_read_feed(@feeds|[@feeds]): Marks the feeds as read.

Edit tags / states

The following methods are used to edit tags and states.

edit_tag($tag|[@tags], %params)
edit_state($state|[@states], %params): Accepts the following parameters.

share / public: Make the given tags / states public.
unshare / private: Make the given tags / states private.
disable / delete: Only tags (and not states) can be disabled.

share_tag(@tags|[@tags])
unshare_tag(@tags|[@tags])
share_state(@states|[@states])
unshare_state(@states|[@states]): Associate / unassociate the 'broadcast' state with the given tags / states.
delete_tag(@tags|[@tags]): Delete the given tags.
rename_feed_tag($oldtag|[@oldtags], $newtag|[@newtags]: Renames the tags associated with any feeds.
rename_entry_tag($oldtag|[@oldtags], $newtag|[@newtags]: Renames the tags associated with any individual entries.
rename_tag($oldtag|[@oldtags], $newtag|[@newtags]: Calls rename_feed_tag and rename_entry_tag, and finally delete_tag.
mark_read_tag(@tags|[@tags])
mark_read_state(@states|[@states]): Marks all entries as read for the given tags / states.

Edit entries

The following methods are used to edit individual entries.

edit_entry($entry|[@entries], %params)

tag / state / untag / unstate: Associate / unassociate the entries with the given tags / states.

tag_entry($entry|[@entries], @tags)
untag_entry($entry|[@entries], @tags)
state_entry($entry|[@entries], @tags)
unstate_entry($entry|[@entries], @tags): Associate / unassociate the entries with the given tags / states.
share_entry(@entries|[@entries])
unshare_entry(@entries|[@entries]): Marks all the given entries as "broadcast".
star(@entries|[@entries])
star_entry(@entries|[@entries])
unstar(@entries|[@entries])
unstar_entry(@entries|[@entries]): Marks / unmarks all the given entries as "starred".
mark_read_entry(@entries|[@entries]): Marks all the given entries as "read".
like(@entries|[@entries])
like_entry(@entries|[@entries])
unlike(@entries|[@entries])
unlike_entry(@entries|[@entries]): Marks / unmarks all the given entries as "liked".

Miscellaneous

These are a list of other useful methods.

edit_preference($key, $value): Sets the given preference name to the given value.
mark_read(feed => $feed|[@feeds], state => $state|[@states], tag => $tag|[@tags])
opml: Exports feed subscriptions as OPML.
ping: Returns true / false on success / failure. Unsure of when this needs to be used.

Private methods

The following private methods may be of use to others.

_login: This is automatically called from within methods that require authorization. An optional parameter is accepted which when true, will force a login even if a previous login was successful. The end result of a successful login is to set the auth token.
_request: Given an "HTTP::Request", this will perform the request and if the response indicates a bad (expired) token, it will request another token before performing the request again. Returns an "HTTP::Response" on success, false on failure (check error).
_token: This is automatically called from within methods that require a user token. If successful, the token is available via the token accessor.
_states: Returns a list of all the known states. See "STATES".

STATES

These are tags in a Google-specific namespace. The following are all the known used states.

read: Entries which have been read.
kept-unread: Entries which have been read, but marked unread.
fresh: New entries from reading-list.
starred: Entries which have been starred.
broadcast: Entries which have been shared and made publicly available.
reading-list: Entries from all subscriptions.
tracking-body-link-used: Entries for which a link in the body has been clicked.
tracking-emailed: Entries which have been mailed.
tracking-item-link-used: Entries for which the title link has been clicked.
tracking-kept-unread: Entries which have been kept unread. (Not sure how this differs from "kept-unread").

REQUESTS AND BUGS

Please report any bugs or feature requests to <http://rt.cpan.org/Public/Bug/Report.html?Queue=WebService-Google-Reader>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WebService::Google::Reader

You can also look for information at:

GitHub Source Repository
<http://github.com/gray/webservice-google-reader>
AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/WebService-Google-Reader>
CPAN Ratings
<http://cpanratings.perl.org/d/WebService-Google-Reader>
RT: CPAN's request tracker
<http://rt.cpan.org/Public/Dist/Display.html?Dist=WebService-Google-Reader>
Search CPAN
<http://search.cpan.org/dist/WebService-Google-Reader/>

COPYRIGHT AND LICENSE

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

AUTHOR

gray, <gray at cpan.org>