Mojo::WebService::Twitter - Simple Twitter API client
my $twitter = Mojo::WebService::Twitter->new(api_key => $api_key, api_secret => $api_secret); # Request and store access token $twitter->authentication($twitter->request_oauth2); # Blocking API request my $user = $twitter->get_user(screen_name => $name); say $user->screen_name . ' was created on ' . $user->created_at->ymd; # Non-blocking API request $twitter->get_tweet($tweet_id, sub { my ($twitter, $err, $tweet) = @_; print $err ? "Error: $err" : 'Tweet: ' . $tweet->text . "\n"; }); Mojo::IOLoop->start unless Mojo::IOLoop->is_running; # Non-blocking API request using promises $twitter->get_tweet_p($tweet_id)->then(sub { my ($tweet) = @_; print 'Tweet: ' . $tweet->text . "\n"; })->catch(sub { my ($err) = @_; print "Error: $err"; })->wait; # Some requests require authentication on behalf of a user $twitter->authentication(oauth => $token, $secret); my $authorizing_user = $twitter->verify_credentials; my $new_tweet = $twitter->post_tweet('Something new and exciting!');
Mojo::WebService::Twitter is a Mojo::UserAgent based Twitter API client that can perform requests synchronously or asynchronously. An API key and secret for a Twitter Application are required.
API requests are authenticated by the "authentication" coderef, which can either use an OAuth 2.0 access token to authenticate requests on behalf of the application itself, or OAuth 1.0 credentials (access token and secret) to authenticate requests on behalf of a specific user. The twitter_oauth_creds script can be used to obtain Twitter OAuth credentials for a user from the command-line. A web application may wish to implement its own OAuth authorization flow, passing a callback URL back to the application in "request_oauth", then calling "verify_oauth" with the passed verifier code to retrieve the credentials. See the Twitter documentation for more details.
All methods which query the Twitter API can be called with an optional trailing callback argument to run a non-blocking API query. Alternatively, the _p variant will run a non-blocking API query and return a Mojo::Promise, which can simplify complex sequences of non-blocking queries. On connection, HTTP, or API error, blocking API queries will throw a Mojo::WebService::Twitter::Error exception. Non-blocking API queries will pass this exception object to the callback or reject the promise, and otherwise pass the results to the callback or resolve the promise.
_p
Note that this distribution implements only a subset of the Twitter API. Additional features may be added as requested. See Twitter::API for a more fully-featured lightweight and modern twitter client library.
Mojo::WebService::Twitter implements the following attributes.
my $api_key = $twitter->api_key; $twitter = $twitter->api_key($api_key);
API key for your Twitter Application.
my $api_secret = $twitter->api_secret; $twitter = $twitter->api_secret($api_secret);
API secret for your Twitter Application.
my $ua = $webservice->ua; $webservice = $webservice->ua(Mojo::UserAgent->new);
HTTP user agent object to use for synchronous and asynchronous requests, defaults to a Mojo::UserAgent object.
Mojo::WebService::Twitter inherits all methods from Mojo::Base, and implements the following new ones.
my $code = $twitter->authentication; $twitter = $twitter->authentication($code); $twitter = $twitter->authentication({oauth_token => $access_token, oauth_token_secret => $access_token_secret}); $twitter = $twitter->authentication(oauth => $access_token, $access_token_secret); $twitter = $twitter->authentication({access_token => $access_token}); $twitter = $twitter->authentication(oauth2 => $access_token);
Get or set coderef used to authenticate API requests. Passing oauth with optional token and secret, or a hashref containing oauth_token and oauth_token_secret, will set a coderef which uses a WWW::OAuth to authenticate requests. Passing oauth2 with required token or a hashref containing access_token will set a coderef which authenticates using the passed access token. The coderef will receive the Mojo::Message::Request object as the first parameter, and an optional hashref of oauth_ parameters.
oauth
oauth_token
oauth_token_secret
oauth2
access_token
oauth_
my $res = $twitter->request_oauth; my $res = $twitter->request_oauth($callback_url); $twitter->request_oauth(sub { my ($twitter, $error, $res) = @_; }); my $p = $twitter->request_oauth_p;
Send an OAuth 1.0 authorization request and return a hashref containing oauth_token and oauth_token_secret (request token and secret). An optional OAuth callback URL may be passed; by default, oob is passed to use PIN-based authorization. The user should be directed to the authorization URL which can be retrieved by passing the request token to "twitter_authorize_url" in Mojo::WebService::Twitter::Util. After authorization, the user will either be redirected to the callback URL with the query parameter oauth_verifier, or receive a PIN to return to the application. Either the verifier string or PIN should be passed to "verify_oauth" to retrieve an access token and secret.
oob
oauth_verifier
my $res = $twitter->verify_oauth($verifier, $request_token, $request_token_secret); $twitter->verify_oauth($verifier, $request_token, $request_token_secret, sub { my ($twitter, $error, $res) = @_; }); my $p = $twitter->verify_oauth_p($verifier, $request_token, $request_token_secret);
Verify an OAuth 1.0 authorization request with the verifier string or PIN from the authorizing user, and the previously obtained request token and secret. The secret is cached by "request_oauth" and may be omitted. Returns a hashref containing oauth_token and oauth_token_secret (access token and secret) which may be passed directly to "authentication" to authenticate requests on behalf of the user.
my $res = $twitter->request_oauth2; $twitter->request_oauth2(sub { my ($twitter, $error, $res) = @_; }); my $p = $twitter->request_oauth2_p;
Request OAuth 2 credentials and return a hashref containing an access_token that can be passed directly to "authentication" to authenticate requests on behalf of the application itself.
my $tweet = $twitter->get_tweet($tweet_id); $twitter->get_tweet($tweet_id, sub { my ($twitter, $err, $tweet) = @_; }); $twitter->get_tweet_p($tweet_id);
Retrieve a Mojo::WebService::Twitter::Tweet by tweet ID.
my $user = $twitter->get_user(user_id => $user_id); my $user = $twitter->get_user(screen_name => $screen_name); $twitter->get_user(screen_name => $screen_name, sub { my ($twitter, $err, $user) = @_; }); my $p = $twitter->get_user_p(user_id => $user_id);
Retrieve a Mojo::WebService::Twitter::User by user ID or screen name.
my $tweet = $twitter->post_tweet($text, %options); $twitter->post_tweet($text, %options, sub { my ($twitter, $err, $tweet) = @_; }); my $p = $twitter->post_tweet_p($text, %options);
Post a status update (tweet) and retrieve the resulting Mojo::WebService::Twitter::Tweet. Requires OAuth 1.0 authentication. Accepts the following options:
in_reply_to_status_id => '12345'
Indicates the tweet is in reply to an existing tweet ID. IDs should be specified as a string to avoid issues with large integers. This parameter will be ignored by the Twitter API unless the author of the referenced tweet is mentioned within the status text as @username.
@username
lat => '37.781157'
The latitude of the location to attach to the tweet. This parameter will be ignored by the Twitter API unless it is within the range -90.0 to 90.0, and a corresponding long is specified. It is recommended to specify values as strings to avoid issues with floating-point representations.
-90.0
90.0
long
long => '-122.398720'
The longitude of the location to attach to the tweet. This parameter will be ignored by the Twitter API unless it is within the range -180.0 to 180.0, and a corresponding lat is specified. It is recommended to specify values as strings to avoid issues with floating-point representations.
-180.0
180.0
lat
place_id => 'df51dec6f4ee2b2c'
A Twitter place ID to attach to the tweet.
display_coordinates => 1
If true, tweet will display the exact coordinates the tweet was sent from.
my $tweet = $twitter->retweet($tweet_id); $twitter->retweet($tweet_id, sub { my ($twitter, $err, $tweet) = @_; }); my $p = $twitter->retweet_p($tweet_id);
Retweet the tweet ID or Mojo::WebService::Twitter::Tweet object. Returns a Mojo::WebService::Twitter::Tweet representing the original tweet. Requires OAuth 1.0 authentication.
my $tweets = $twitter->search_tweets($query); my $tweets = $twitter->search_tweets($query, %options); $twitter->search_tweets($query, %options, sub { my ($twitter, $err, $tweets) = @_; }); my $p = $twitter->search_tweets_p($query, %options);
Search Twitter and return a Mojo::Collection of Mojo::WebService::Twitter::Tweet objects. Accepts the following options:
geocode => '37.781157,-122.398720,1mi' geocode => ['37.781157','-122.398720','1mi'] geocode => {latitude => '37.781157', longitude => '-122.398720', radius => '1mi'}
Restricts tweets to the given radius of the given latitude/longitude. Radius must be specified as mi (miles) or km (kilometers). It is recommended to specify values as strings to avoid issues with floating-point representations.
mi
km
lang => 'eu'
Restricts tweets to the given ISO 639-1 language code.
result_type => 'recent'
Specifies what type of search results to receive. Valid values are recent, popular, and mixed (default).
recent
popular
mixed
count => 5
Limits the search results per page. Maximum 100, default 15.
100
15
until => '2015-07-19'
Restricts tweets to those created before the given date, in the format YYYY-MM-DD.
YYYY-MM-DD
since_id => '12345'
Restricts results to those more recent than the given tweet ID. IDs should be specified as a string to avoid issues with large integers. See here for more information on filtering results with since_id and max_id.
since_id
max_id
max_id => '54321'
Restricts results to those older than (or equal to) the given tweet ID. IDs should be specified as a string to avoid issues with large integers. See here for more information on filtering results with since_id and max_id.
my $user = $twitter->verify_credentials; $twitter->verify_credentials(sub { my ($twitter, $error, $user) = @_; }); my $p = $twitter->verify_credentials_p;
Verify the authorizing user's credentials and return a representative Mojo::WebService::Twitter::User object. Requires OAuth 1.0 authentication.
Report any issues on the public bugtracker.
Dan Book <dbook@cpan.org>
This software is Copyright (c) 2015 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
Twitter::API, WWW::OAuth
To install Mojo::WebService::Twitter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojo::WebService::Twitter
CPAN shell
perl -MCPAN -e shell install Mojo::WebService::Twitter
For more information on module installation, please visit the detailed CPAN module installation guide.