man > Net::Twitter

man perldoc info pydoc3 ri search

📘 NAME

Net::Twitter - A perl interface to the Twitter API

🚀 Quick Reference

Use Case	Command	Description
Create object (no auth)	Net::Twitter->new(legacy => 0)	Construct a Net::Twitter object for API v1.1 without authentication
Create object (OAuth)	Net::Twitter->new(traits => [qw/API::RESTv1_1/], consumer_key => $key, ...)	Construct with OAuth credentials for authenticated requests
Post a tweet	$nt->update('Hello, world!')	Update status (requires authentication)
Fetch home timeline	$nt->home_timeline({ since_id => $id, count => 100 })	Retrieve recent tweets from user and friends
Search tweets	$nt->search($query)	Search for tweets matching query
Follow a user	$nt->create_friend($screen_name)	Follow user by screen name or ID
Upload media	$nt->upload($media)	Upload image for later use in tweet
Error handling (exception)	eval { ... }; if ($@) { ... }	Catch Net::Twitter::Error exceptions
Error handling (wrap)	if (my $r = $nt->method) { ... } else { $nt->get_error }	Use WrapError trait to avoid exceptions
Cursor-based paging	for (my $c = -1; $c; $c = $r->{next_cursor}) { ... }	Iterate over pages of followers/friends

📌 VERSION

version 4.01043

📝 SYNOPSIS

use Net::Twitter;
use Scalar::Util 'blessed';

# When no authentication is required:
my $nt = Net::Twitter->new(legacy => 0);

# As of 13-Aug-2010, Twitter requires OAuth for authenticated requests
my $nt = Net::Twitter->new(
    traits   => [qw/API::RESTv1_1/],
    consumer_key        => $consumer_key,
    consumer_secret     => $consumer_secret,
    access_token        => $token,
    access_token_secret => $token_secret,
);

my $result = $nt->update('Hello, world!');

eval {
    my $statuses = $nt->friends_timeline({ since_id => $high_water, count => 100 });
    for my $status ( @$statuses ) {
        print "$status->{created_at} <$status->{user}{screen_name}> $status->{text}\n";
    }
};
if ( my $err = $@ ) {
    die $@ unless blessed $err && $err->isa('Net::Twitter::Error');

    warn "HTTP Response Code: ", $err->code, "\n",
         "HTTP Message......: ", $err->message, "\n",
         "Twitter error.....: ", $err->error, "\n";
}

🐦 TWITTER API V1.1 SUPPORT

This version of Net::Twitter provides Twitter API v1.1 support. Enable it by including the "API::RESTv1_1" trait instead of "API::REST". Using Twitter API v1.1 may require changes to you code! It is not completely backwards compatible with v1.

For help migrating your application to Twitter API v1.1, see Net::Twitter::Manual::MigratingToV1_1.

🔹 TWITTER API VERSION 1.1

Twitter will (perhaps has by the time you read this) deprecated version 1 of the API. Documentation, here, assumes version 1.1 of the API. For version 1 documentation, see Net::Twitter::Role::API::REST.

To use Twitter API version 1.1, simply replace "API::REST" in the "traits" argument to "new" with "API::RESTv1_1". The Net::Twitter API is backwards compatible to the extent possible. If Twitter does not provide a 1.1 endpoint for a version 1 call, Net::Twitter cannot support it, of course.

Twitter API version 1.1 requires OAuth authentication for all calls. There is no longer an IP address limit and a per-user limit. Each API call has it's own rate limit. Most are 15 calls reset every 15 minutes. Others are 180 calls, reset every 15 minutes. These limits may change. For current rate limits, see https://dev.twitter.com/docs/rate-limiting/1.1/limits.

🔹 OMG! THE MOOSE!

Net::Twitter is Moose based. Moose provides some advantages, including the ability for the maintainer of this module to respond quickly to Twitter API changes.

See Net::Twitter::Lite if you need an alternative without Moose and its dependencies.

Net::Twitter::Lite's API method definitions and documentation are generated from Net::Twitter. It is a related module, but does not depend on Net::Twitter or Moose for installation.

📖 DESCRIPTION

This module has been superseded by Twitter::API. Please update as soon as you possibly can to use new features and the new API versions. This module will no longer be supported.

This module provides a perl interface to the Twitter APIs. See http://dev.twitter.com/docs for a full description of the Twitter APIs.

📤 RETURN VALUES

Net::Twitter decodes the data structures returned by the Twitter API into native perl data structures (HASH references and ARRAY references). The full layout of those data structures are not documented, here. They change often, usually with the addition of new elements, and documenting all of those changes would be a significant challenge.

Instead, rely on the online Twitter API documentation and inspection of the returned data.

The Twitter API online documentation is located at http://dev.twitter.com/doc.

To inspect the data, use Data::Dumper or similar module of your choice. Here's a simple example using Data::Dumper:

use Data::Dumper;

my $r = $nt->search($search_term);
print Dumper $r;

For more information on perl data structures, see perlreftut, perldsc, and perllol.

⚙️ METHODS AND ARGUMENTS

new

This constructs a "Net::Twitter" object. It takes several named parameters, all of them optional:

• traits — An ARRAY ref of traits used to control which APIs the constructed Net::Twitter object will support and how it handles errors. Possible values are:
  • API::RESTv1_1 — Provides support for the Twitter REST API version 1.1 methods.
  • API::Search — Deprecated. Use "search" in API::RESTv1_1 instead.
  • AppAuth — Provides Application-Only Authentication with methods "request_access_token" and "invalidate_token". See Net::Twitter::Role::AppAuth.
  • AutoCursor — A parameterized trait that provides an automatic loop for cursored calls. See Net::Twitter::Role::AutoCursor.
  • InflateObjects — Inflates HASH refs into objects with read accessors, dates to DateTime objects, URLs to URI objects.
  • Legacy — Provides backwards compatibility to Net::Twitter versions prior to 3.00.
  • OAuth — Provides OAuth authentication.
  • RateLimit — Adds utility methods for rate limit status.
  • RetryOnError — Automatically retries on temporary failures.
  • WrapError — Returns undef on error and makes error available via get_error.
• legacy — Boolean. If set to 0, constructs a Net::Twitter object implementing the REST API and throws exceptions on API method errors.
• username — Username for Basic Authentication (deprecated, use OAuth).
• password — Password for Basic Authentication.
• clientname — Value for X-Twitter-Client-Name header. Defaults to "Perl Net::Twitter".
• clientver — Value for X-Twitter-Client-Version header. Defaults to current version.
• clienturl — Value for X-Twitter-Client-URL header. Defaults to search.cpan.org page.
• useragent_class — LWP::UserAgent compatible class. Defaults to "LWP::UserAgent".
• useragent_args — HASH ref of arguments to pass to useragent_class constructor.
• useragent — Value for User-Agent header. Defaults to "Net::Twitter/4.01043 (Perl)".
• source — Twitter no longer uses this parameter; kept for compatibility.
• apiurl — URL for Twitter API. Defaults to "http://api.twitter.com/1".
• apihost — DEPRECATED.
• apirealm — Realm for Basic Authentication. Defaults to "Twitter API".
• identica — If set to 1, overrides apiurl, apihost, apirealm for Identi.ca.
• consumer_key — OAuth consumer key.
• consumer_secret — OAuth consumer secret.
• ssl — If set to 1, use SSL for all API calls. Defaults to 1.
• netrc — Sets machine key to look up in .netrc.
• netrc_machine — Machine entry to look up. Defaults to "api.twitter.com".
• decode_html_entities — If set to 1, automatically decode HTML entities in status text.

credentials($username, $password)

Set the credentials for Basic Authentication. Helpful for managing multiple accounts.

ua

Provides access to the constructed user agent object. Use with caution.

🔐 AUTHENTICATION

With REST API version 1.1, all API calls require OAuth. Since 31-Aug-2010, version 1 required OAuth requests requiring authentication. Other Twitter compatible services, like Identi.ca, accept Basic Authentication. So, Net::Twitter provides support for both.

To set up OAuth, include the "consumer_key" and "consumer_secret" options to "new". When they are provided, the "OAuth" trait will be automatically included. See Net::Twitter::Role::OAuth for more information on using OAuth, including examples.

To set up Basic Authentication in Net::Twitter, provide the "username" and "password" options to "new" or call the "credentials" method.

In addition to the arguments specified for each API method described below, an additional "-authenticate" parameter can be passed. To request an "Authorization" header, pass "-authenticate => 1"; to suppress, pass "-authenticate => 0".

📡 API METHODS AND ARGUMENTS

Most Twitter API methods take parameters. All Net::Twitter API methods will accept a HASH ref of named parameters as specified in the Twitter API documentation. For convenience, many Net::Twitter methods accept simple positional arguments. The positional parameter passing style is optional; you can always use the named parameters in a HASH reference if you prefer.

You may pass any number of required parameters as positional parameters. You must pass them in the order specified in the documentation for each method. Optional parameters must be passed as named parameters in a HASH reference. The HASH reference containing the named parameters must be the final parameter to the method call. Any required parameters not passed as positional parameters, must be included in the named parameter HASH reference.

For example, the REST API method "update" has one required parameter, "status". You can call "update" with a HASH ref argument:

$nt->update({ status => 'Hello world!' });

Or, you can use the convenient, positional parameter form:

$nt->update('Hello world!');

The "update" method also has an optional parameter, "in_reply_to_status_id". To use it, you must use the HASH ref form:

$nt->update({ status => 'Hello world!', in_reply_to_status_id => $reply_to });

You may use the convenient positional form for the required "status" parameter with the optional parameters specified in the named parameter HASH reference:

$nt->update('Hello world!', { in_reply_to_status_id => $reply_to });

Convenience form is provided for the required parameters of all API methods. So, these two calls are equivalent:

$nt->friendship_exists({ user_a => $fred, user_b => $barney });
$nt->friendship_exists($fred, $barney);

Many API methods have aliases. You can use the API method name, or any of its aliases, as you prefer. For example, these calls are all equivalent:

$nt->friendship_exists($fred, $barney);
$nt->relationship_exists($fred, $barney);
$nt->follows($fred, $barney);

Aliases support both the HASH ref and convenient forms:

$nt->follows({ user_a => $fred, user_b => $barney });

🔹 Cursors and Paging

Some methods return partial results a page at a time. Originally, methods that returned partial results used a "page" parameter. A more recent addition to the Twitter API for retrieving multiple pages uses the "cursor" parameter. Usually, a method uses either the "page" parameter or the "cursor" parameter, but not both. There have been exceptions to this rule when Twitter deprecates the use of "page" for a method in favor of "cursor". In that case, both methods may work during a transition period. So, if a method supports both, you should always use the "cursor" parameter.

Paging

For methods that support paging, the first page is returned by passing "page => 1", the second page by passing "page => 2", etc. If no "page" parameter is passed, the first page is returned.

Here's an example that demonstrates how to obtain all favorites in a loop:

my @favs;
for ( my $page = 1; ; ++$page ) {
    my $r = $nt->favorites({ page => $page });
    last unless @$r;
    push @favs, @$r;
}

Cursors

Cursoring employs a different strategy. To obtain the first page of results, pass "cursor => -1". Twitter returns a reference to a hash that includes entries "next_cursor", "previous_cursor", and an entry with a reference to an array containing a page of the requested items. The key for the array reference will be named "users", "ids", or something similar depending upon the type of returned items. For example, when "cursor" parameter is used with the "followers_ids" method, the returned in hash entry "ids".

The "next_cursor" value can be used in a subsequent call to obtain the next page of results. When you have obtained the last page of results, "next_cursor" will be 0. Likewise, you can use the value for "previous_cursor" to obtain the previous page of results. When you have obtained the first page, "previous_cursor" will be 0.

Here's an example that demonstrates how to obtain all follower IDs in a loop using the "cursor" parameter:

my @ids;
for ( my $cursor = -1, my $r; $cursor; $cursor = $r->{next_cursor} ) {
    $r = $nt->followers_ids({ cursor => $cursor });
    push @ids, @{ $r->{ids} };
}

🔹 Synthetic Arguments

In addition to the arguments described in the Twitter API Documentation for each API method, Net::Twitter supports additional synthetic arguments.

• -authenticate — When set to 1, provide an Authorization header; when set to 0, suppress it. Overrides the defined authentication behavior for the API method.
• -since — API methods that accept "since_id" argument will also accept the synthetic "-since" argument. -since may be a DateTime object, an epoch time, or a string in the same format returned by Twitter for "created_at".
• -legacy_lists_api — Only effective when the legacy API::Lists trait is applied. Passing -legacy_lists_api set to 0 will use the new lists endpoints.

🔧 REST API Methods

These methods are provided when trait "API::RESTv1_1" is included in the "traits" option to "new".

🔹 Common Parameters

• id — Several of these methods accept a user ID as the "id" parameter. The user ID can be either a screen name, or the users numeric ID. To disambiguate, use the "screen_name" or "user_id" parameters, instead.
• skip_user — The timeline methods all accept an optional "skip_user" parameter. When set to a true value, the statuses returned will not contain an entire embedded user HASH.

🔹 Methods

Each method is listed with its parameters, required parameters, description, return type, and Twitter API documentation link.

🔧 account_settings

Parameters: none
Required: none

Returns the current trend, geo and sleep time information for the authenticating user.

Returns: HashRef

Twitter API documentation: GET account/settings

🔧 account_totals [DEPRECATED]

Parameters: none
Required: none

Returns the current count of friends, followers, updates and favorites of the authenticating user.

Returns: HashRef

🔧 add_list_member

Parameters: list_id, slug, user_id, screen_name, owner_screen_name, owner_id
Required: none

Add a member to a list. The authenticated user must own the list. Note that lists can't have more than 500 members.

Returns: User

Twitter API documentation: POST lists/members/create

🔧 add_place(name, contained_within, token, lat, long)

Parameters: name, contained_within, token, lat, long, attribute:street_address, callback
Required: name, contained_within, token, lat, long

Creates a new place object at the given latitude and longitude.

Returns: Place

Twitter API documentation: POST geo/place

🔧 block_exists [DEPRECATED]

Parameters: id, user_id, screen_name, include_entities
Required: id

Returns if the authenticating user is blocking a target user. Will return the blocked user's object if a block exists, and error with HTTP 404 response code otherwise.

Returns: BasicUser

🔧 blocking (alias: blocks_list)

Parameters: cursor, include_entities, skip_status
Required: none

Returns an array of user objects that the authenticating user is blocking.

Returns: ArrayRef[BasicUser]

Twitter API documentation: GET blocks/list

🔧 blocking_ids (alias: blocks_ids)

Parameters: cursor, stringify_ids
Required: none

Returns an array of numeric user ids the authenticating user is blocking.

Returns: ArrayRef[Int]

Twitter API documentation: GET blocks/ids

🔧 contributees [DEPRECATED]

Parameters: user_id, screen_name, include_entities, skip_satus
Required: none

Returns an array of users that the specified user can contribute to.

Returns: ArrayRef[User]

🔧 contributors [DEPRECATED]

Parameters: user_id, screen_name, include_entities, skip_satus
Required: none

Returns an array of users who can contribute to the specified account.

Returns: ArrayRef[User]

🔧 create_block

Parameters: user_id, screen_name, include_entities, skip_status
Required: id

Blocks the user specified. Returns the blocked user when successful.

Returns: BasicUser

Twitter API documentation: POST blocks/create

🔧 create_favorite

Parameters: id, include_entities
Required: id

Favorites the status specified. Returns the favorite status when successful.

Returns: Status

Twitter API documentation: POST favorites/create

🔧 create_friend (alias: follow, follow_new, create_friendship)

Parameters: user_id, screen_name, follow
Required: none

Follows the user specified. Returns the befriended user when successful.

Returns: BasicUser

Twitter API documentation: POST friendships/create

🔧 create_list

Parameters: list_id, slug, name, mode, description, owner_screen_name, owner_id
Required: name

Creates a new list for the authenticated user. Note that you can't create more than 20 lists per account.

Returns: List

Twitter API documentation: POST lists/create

🔧 create_media_metadata

Parameters: media_id, alt_text
Required: media_id

Adds metadata (alt text) to a previously uploaded media object. The alt_text parameter must be a hashref with key "text".

Returns: HashRef

Twitter API documentation: POST media/metadata/create

🔧 create_mute

Parameters: user_id, screen_name
Required: id

Mutes the user specified. Returns the muted user when successful.

Returns: BasicUser

Twitter API documentation: POST mutes/users/create

🔧 create_saved_search

Parameters: query
Required: query

Creates a saved search for the authenticated user.

Returns: SavedSearch

Twitter API documentation: POST saved_searches/create

🔧 delete_list

Parameters: owner_screen_name, owner_id, list_id, slug
Required: none

Deletes the specified list. The authenticated user must own the list.

Returns: List

Twitter API documentation: POST lists/destroy

🔧 delete_list_member (alias: remove_list_member)

Parameters: list_id, slug, user_id, screen_name, owner_screen_name, owner_id
Required: none

Removes the specified member from the list. The authenticated user must be the list's owner.

Returns: User

Twitter API documentation: POST lists/members/destroy

🔧 destroy_block

Parameters: user_id, screen_name, include_entities, skip_status
Required: id

Un-blocks the user specified. Returns the un-blocked user when successful.

Returns: BasicUser

Twitter API documentation: POST blocks/destroy

🔧 destroy_direct_message

Parameters: id, include_entities
Required: id

Destroys the direct message specified. The authenticating user must be the recipient.

Returns: DirectMessage

Twitter API documentation: POST direct_messages/destroy

🔧 destroy_favorite

Parameters: id, include_entities
Required: id

Un-favorites the status specified. Returns the un-favorited status.

Returns: Status

Twitter API documentation: POST favorites/destroy

🔧 destroy_friend (alias: unfollow, destroy_friendship)

Parameters: user_id, screen_name
Required: id

Discontinues friendship with the user specified. Returns the un-friended user when successful.

Returns: BasicUser

Twitter API documentation: POST friendships/destroy

🔧 destroy_mute

Parameters: user_id, screen_name
Required: id

Un-mutes the user specified. Returns the un-muted user when successful.

Returns: BasicUser

Twitter API documentation: POST mutes/users/destroy

🔧 destroy_saved_search (alias: delete_saved_search)

Parameters: id
Required: id

Destroys a saved search owned by the authenticating user.

Returns: SavedSearch

Twitter API documentation: POST saved_searches/destroy/:id

🔧 destroy_status

Parameters: id, trim_user
Required: id

Destroys the status specified. The authenticating user must be the author.

Returns: Status

Twitter API documentation: POST statuses/destroy/:id

🔧 direct_messages

Parameters: since_id, max_id, count, page, include_entities, skip_status
Required: none

Returns a list of the 20 most recent direct messages sent to the authenticating user.

Returns: ArrayRef[DirectMessage]

Twitter API documentation: GET direct_messages

🔧 disable_notifications [DEPRECATED]

Parameters: id, screen_name, include_entities
Required: id

Disables notifications for updates from the specified user.

Returns: BasicUser

🔧 enable_notifications [DEPRECATED]

Parameters: id, screen_name, include_entities
Required: id

Enables notifications for updates from the specified user.

Returns: BasicUser

🔧 end_session [DEPRECATED]

Parameters: none
Required: none

Ends the session of the authenticating user, returning a null cookie.

Returns: Error

🔧 favorites

Parameters: user_id, screen_name, count, since_id, max_id, include_entities
Required: none

Returns the 20 most recent favorite statuses for the authenticating user or user specified.

Returns: ArrayRef[Status]

Twitter API documentation: GET favorites/list

🔧 followers (alias: followers_list)

Parameters: user_id, screen_name, cursor
Required: none

Returns a cursored collection of user objects for users following the specified user.

Returns: HashRef

Twitter API documentation: GET followers/list

🔧 followers_ids

Parameters: user_id, screen_name, cursor, stringify_ids
Required: none

Returns a reference to an array of numeric IDs for every user following the specified user. Use cursor for paging.

Returns: HashRef|ArrayRef[Int]

Twitter API documentation: GET followers/ids

🔧 friends (alias: friends_list)

Parameters: user_id, screen_name, cursor
Required: none

Returns a cursored collection of user objects for users followed by the specified user.

Returns: HashRef

Twitter API documentation: GET friends/list

🔧 friends_ids (alias: following_ids)

Parameters: user_id, screen_name, cursor, stringify_ids
Required: none

Returns a reference to an array of numeric IDs for every user followed by the specified user. Use cursor for paging.

Returns: HashRef|ArrayRef[Int]

Twitter API documentation: GET friends/ids

🔧 friends_timeline [DEPRECATED] (alias: following_timeline)

Parameters: since_id, max_id, count, exclude_replies, contributor_details, include_entities, trim_user
Required: none

Returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user's friends.

Returns: ArrayRef[Status]

🔧 friendship_exists [DEPRECATED] (alias: relationship_exists, follows)

Parameters: user_id_a, user_id_b, screen_name_a, screen_name_b, user_a, user_b
Required: user_a, user_b

Tests for the existence of friendship between two users. Returns true if user_a follows user_b.

Returns: Bool

🔧 friendships_incoming (alias: incoming_friendships)

Parameters: cursor, stringify_ids
Required: none

Returns an HASH ref with an array of numeric IDs for every user who has a pending request to follow the authenticating user.

Returns: HashRef

Twitter API documentation: GET friendships/incoming

🔧 friendships_outgoing (alias: outgoing_friendships)

Parameters: cursor, stringify_ids
Required: none

Returns an HASH ref with an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request.

Returns: HashRef

Twitter API documentation: GET friendships/outgoing

🔧 geo_id

Parameters: place_id
Required: place_id

Returns details of a place returned from the reverse_geocode method.

Returns: HashRef

Twitter API documentation: GET geo/id/:place_id

🔧 geo_search

Parameters: lat, long, query, ip, granularity, accuracy, max_results, contained_within, attribute:street_address, callback
Required: none

Search for places that can be attached to a statuses/update. Given a latitude and longitude pair, an IP address, or a name, this request will return a list of all the valid places.

Returns: HashRef

Twitter API documentation: GET geo/search

🔧 get_configuration

Parameters: none
Required: none

Returns the current configuration used by Twitter including twitter.com slugs, maximum photo resolutions, and t.co URL lengths.

Returns: HashRef

Twitter API documentation: GET help/configuration

🔧 get_languages

Parameters: none
Required: none

Returns the list of languages supported by Twitter along with their ISO 639-1 code.

Returns: ArrayRef[Language]

Twitter API documentation: GET help/languages

🔧 get_list (alias: show_list)

Parameters: list_id, slug, owner_screen_name, owner_id
Required: none

Returns the specified list. Private lists will only be shown if the authenticated user owns the list.

Returns: List

Twitter API documentation: GET lists/show

🔧 get_lists (alias: list_lists, all_subscriptions)

Parameters: user_id, screen_name, reverse
Required: none

Returns all lists the authenticating or specified user subscribes to, including their own.

Returns: Hashref

Twitter API documentation: GET lists/list

🔧 get_privacy_policy

Parameters: none
Required: none

Returns Twitter's privacy policy.

Returns: HashRef

Twitter API documentation: GET help/privacy

🔧 get_tos

Parameters: none
Required: none

Returns the Twitter Terms of Service.

Returns: HashRef

Twitter API documentation: GET help/tos

🔧 home_timeline

Parameters: since_id, max_id, count, exclude_replies, contributor_details, include_entities, trim_user
Required: none

Returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user's friends.

Returns: ArrayRef[Status]

Twitter API documentation: GET statuses/home_timeline

🔧 list_members

Parameters: list_id, slug, owner_screen_name, owner_id, cursor, include_entities, skip_status
Required: none

Returns the members of the specified list. Private list members will only be shown if the authenticated user owns the list.

Returns: Hashref

Twitter API documentation: GET lists/members

🔧 list_memberships

Parameters: user_id, screen_name, cursor, filter_to_owned_lists
Required: none

Returns the lists the specified user has been added to. If user_id or screen_name are not provided, memberships for the authenticating user are returned.

Returns: Hashref

Twitter API documentation: GET lists/memberships

🔧 list_ownerships

Parameters: user_id, screen_name, count, cursor
Required: none

Obtain a collection of the lists owned by the specified Twitter user. Private lists will only be shown if the authenticated user is also the owner.

Returns: ArrayRef[List]

Twitter API documentation: GET lists/ownerships

🔧 list_statuses

Parameters: list_id, slug, owner_screen_name, owner_id, since_id, max_id, count, include_entities, include_rts
Required: none

Returns tweet timeline for members of the specified list. Use include_rts=true to additionally receive retweet objects.

Returns: ArrayRef[Status]

Twitter API documentation: GET lists/statuses

🔧 list_subscribers

Parameters: list_id, slug, owner_screen_name, owner_id, cursor, include_entities, skip_status
Required: none

Returns the subscribers of the specified list. Private list subscribers will only be shown if the authenticated user owns the list.

Returns: Hashref

Twitter API documentation: GET lists/subscribers

🔧 list_subscriptions (alias: subscriptions)

Parameters: user_id, screen_name, count, cursor
Required: none

Obtain a collection of the lists the specified user is subscribed to, 20 lists per page by default. Does not include the user's own lists.

Returns: ArrayRef[List]

Twitter API documentation: GET lists/subscriptions

🔧 lookup_friendships

Parameters: user_id, screen_name
Required: none

Returns the relationship of the authenticating user to the comma separated list or ARRAY ref of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none.

Returns: ArrayRef

Twitter API documentation: GET friendships/lookup

🔧 lookup_statuses

Parameters: id, include_entities, trim_user, map
Required: id

Returns a hash reference of tweets from an arbitrary set of ids.

Returns: HashRef

Twitter API documentation: GET statuses/lookup

🔧 lookup_users

Parameters: user_id, screen_name, include_entities
Required: none

Return up to 100 users worth of extended information, specified by either ID, screen name, or combination of the two. This method will accept user IDs or screen names as either a comma delimited string, or as an ARRAY ref.

Returns: ArrayRef[User]

Twitter API documentation: GET users/lookup

🔧 members_create_all (alias: add_list_members)

Parameters: list_id, slug, owner_screen_name, owner_id
Required: none

Adds multiple members to a list, by specifying a reference to an array or a comma-separated list of member ids or screen names. Limited to adding up to 100 members at a time.

Returns: List

Twitter API documentation: POST lists/members/create_all

🔧 members_destroy_all (alias: remove_list_members)

Parameters: list_id, slug, user_id, screen_name, owner_screen_name, owner_id
Required: none

Removes multiple members from a list, by specifying a reference to an array of member ids or screen names, or a string of comma separated user ids or screen names. Limited to removing up to 100 members at a time.

Returns: List

Twitter API documentation: POST lists/members/destroy_all

🔧 mentions (alias: replies, mentions_timeline)

Parameters: since_id, max_id, count, trim_user, include_entities, contributor_details
Required: none

Returns the 20 most recent mentions (statuses containing @username) for the authenticating user.

Returns: ArrayRef[Status]

Twitter API documentation: GET statuses/mentions_timeline

🔧 mutes (alias: muting_ids, muted_ids)

Parameters: cursor
Required: none

Returns an array of numeric user ids the authenticating user has muted.

Returns: ArrayRef[Int]

Twitter API documentation: GET mutes/users/ids

🔧 muting (alias: mutes_list)

Parameters: cursor, include_entities, skip_status
Required: none

Returns an array of user objects that the authenticating user is muting.

Returns: ArrayRef[BasicUser]

Twitter API documentation: GET mutes/users/list

🔧 new_direct_message

Parameters: user_id, screen_name, text
Required: text

Sends a new direct message to the specified user from the authenticating user. Requires both the user and text parameters.

Returns: DirectMessage

Twitter API documentation: POST direct_messages/new

🔧 no_retweet_ids (alias: no_retweets_ids)

Parameters: none
Required: none

Returns an ARRAY ref of user IDs for which the authenticating user does not want to receive retweets.

Returns: ArrayRef[UserIDs]

Twitter API documentation: GET friendships/no_retweets/ids

🔧 oembed

Parameters: id, url, maxwidth, hide_media, hide_thread, omit_script, align, related, lang
Required: none

Returns information allowing the creation of an embedded representation of a Tweet on third party sites.

Returns: Status

Twitter API documentation: GET statuses/oembed

🔧 profile_banner

Parameters: user_id, screen_name
Required: none

Returns a hash reference mapping available size variations to URLs that can be used to retrieve each variation of the banner.

Returns: HashRef

Twitter API documentation: GET users/profile_banner

🔧 rate_limit_status

Parameters: resources
Required: none

Returns the remaining number of API requests available to the authenticated user before the API limit is reached for the current hour.

Returns: RateLimitStatus

Twitter API documentation: GET application/rate_limit_status

🔧 related_results [DEPRECATED]

Parameters: id
Required: id

If available, returns an array of replies and mentions related to the specified status.

Returns: ArrayRef[Status]

🔧 remove_profile_banner

Parameters: none
Required: none

Removes the uploaded profile banner for the authenticating user.

Returns: Nothing

Twitter API documentation: POST account/remove_profile_banner

🔧 report_spam

Parameters: user_id, screen_name
Required: id

The user specified in the id is blocked by the authenticated user and reported as a spammer.

Returns: User

Twitter API documentation: POST users/report_spam

🔧 retweet

Parameters: id, trim_user
Required: id

Retweets a tweet.

Returns: Status

Twitter API documentation: POST statuses/retweet/:id

🔧 retweeted_by [DEPRECATED]

Parameters: id, count, page, trim_user, include_entities
Required: id

Returns up to 100 users who retweeted the status identified by "id".

Returns: ArrayRef[User]

🔧 retweeted_by_ids [DEPRECATED]

Parameters: id, count, page, trim_user, include_entities
Required: id

Returns the IDs of up to 100 users who retweeted the status identified by "id".

Returns: ArrayRef[User]

🔧 retweeted_by_me [DEPRECATED]

Parameters: since_id, max_id, count, page, trim_user, include_entities
Required: none

Returns the 20 most recent retweets posted by the authenticating user.

Returns: ArrayRef[Status]

🔧 retweeted_by_user [DEPRECATED]

Parameters: id, user_id, screen_name
Required: id

Returns the 20 most recent retweets posted by the specified user.

Returns: ArrayRef

🔧 retweeted_to_me [DEPRECATED]

Parameters: since_id, max_id, count, page
Required: none

Returns the 20 most recent retweets posted by the authenticating user's friends.

Returns: ArrayRef[Status]

🔧 retweeted_to_user [DEPRECATED]

Parameters: id, user_id, screen_name
Required: id

Returns the 20 most recent retweets posted by users the specified user follows.

Returns: ArrayRef

🔧 retweeters_ids

Parameters: id, cursor, stringify_ids
Required: id

Returns a collection of up to 100 user IDs belonging to users who have retweeted the tweet specified by the id parameter.

Returns: HashRef

Twitter API documentation: GET statuses/retweeters/ids

🔧 retweets

Parameters: id, count, trim_user
Required: id

Returns up to 100 of the first retweets of a given tweet.

Returns: Arrayref[Status]

Twitter API documentation: GET statuses/retweets/:id

🔧 retweets_of_me (alias: retweeted_of_me)

Parameters: since_id, max_id, count, trim_user, include_entities, include_user_entities
Required: none

Returns the 20 most recent tweets of the authenticated user that have been retweeted by others.

Returns: ArrayRef[Status]

Twitter API documentation: GET statuses/retweets_of_me

🔧 reverse_geocode

Parameters: lat, long, accuracy, granularity, max_results, callback
Required: lat, long

Search for places (cities and neighborhoods) that can be attached to a statuses/update. Given a latitude and a longitude, return a list of all the valid places.

Returns: HashRef

Twitter API documentation: GET geo/reverse_geocode

🔧 saved_searches

Parameters: none
Required: none

Returns the authenticated user's saved search queries.

Returns: ArrayRef[SavedSearch]

Twitter API documentation: GET saved_searches/list

🔧 search

Parameters: q, count, callback, lang, locale, rpp, since_id, max_id, until, geocode, result_type, include_entities
Required: q

Returns a HASH reference with some meta-data about the query including the "next_page", "refresh_url", and "max_id". The statuses are returned in "results".

Returns: HashRef

Twitter API documentation: GET search/tweets

🔧 sent_direct_messages (alias: direct_messages_sent)

Parameters: since_id, max_id, page, count, include_entities
Required: none

Returns a list of the 20 most recent direct messages sent by the authenticating user.

Returns: ArrayRef[DirectMessage]

Twitter API documentation: GET direct_messages/sent

🔧 show_direct_message

Parameters: id
Required: id

Returns a single direct message, specified by an id parameter. Includes the user objects of the sender and recipient.

Returns: HashRef

Twitter API documentation: GET direct_messages/show

🔧 show_friendship (alias: show_relationship)

Parameters: source_id, source_screen_name, target_id, target_screen_name
Required: none

Returns detailed information about the relationship between two users.

Returns: Relationship

Twitter API documentation: GET friendships/show

🔧 show_list_member (alias: is_list_member)

Parameters: owner_screen_name, owner_id, list_id, slug, user_id, screen_name, include_entities, skip_status
Required: none

Check if the specified user is a member of the specified list. Returns the user or undef.

Returns: Maybe[User]

Twitter API documentation: GET lists/members/show

🔧 show_list_subscriber (alias: is_list_subscriber, is_subscriber_lists)

Parameters: owner_screen_name, owner_id, list_id, slug, user_id, screen_name, include_entities, skip_status
Required: none

Returns the user if they are a subscriber.

Returns: User

Twitter API documentation: GET lists/subscribers/show

🔧 show_saved_search

Parameters: id
Required: id

Retrieve the data for a saved search, by "id", owned by the authenticating user.

Returns: SavedSearch

Twitter API documentation: GET saved_searches/show/:id

🔧 show_status

Parameters: id, trim_user, include_entities, include_my_retweet
Required: id

Returns a single status, specified by the id parameter. The status's author will be returned inline.

Returns: Status

Twitter API documentation: GET statuses/show/:id

🔧 show_user

Parameters: user_id, screen_name, include_entities
Required: none

Returns extended information of a given user, specified by ID or screen name. Includes design settings.

Returns: ExtendedUser

Twitter API documentation: GET users/show

🔧 similar_places

Parameters: lat, long, name, contained_within, attribute:street_address, callback
Required: lat, long, name

Locates places near the given coordinates which are similar in name.

Returns: HashRef

Twitter API documentation: GET geo/similar_places

🔧 subscribe_list

Parameters: owner_screen_name, owner_id, list_id, slug
Required: none

Subscribes the authenticated user to the specified list.

Returns: List

Twitter API documentation: POST lists/subscribers/create

🔧 suggestion_categories

Parameters: none
Required: none

Returns the list of suggested user categories. Does not require authentication.

Returns: ArrayRef

Twitter API documentation: GET users/suggestions

🔧 test [DEPRECATED]

Parameters: none
Required: none

Returns the string "ok" status code.

Returns: Hash

🔧 trends_available

Parameters: none
Required: none

Returns the locations with trending topic information. The response is an array of "locations" that encode the location's WOEID.

Returns: ArrayRef[Location]

Twitter API documentation: GET trends/available

🔧 trends_closest

Parameters: lat, long
Required: none

Returns the locations with trending topic information, sorted by distance from that location.

Returns: ArrayRef[Location]

Twitter API documentation: GET trends/closest

🔧 trends_current [DEPRECATED]

Parameters: exclude
Required: none

Returns the current top ten trending topics on Twitter.

Returns: HashRef

🔧 trends_daily [DEPRECATED]

Parameters: date, exclude
Required: none

Returns the top 20 trending topics for each hour in a given day.

Returns: HashRef

🔧 trends_place (alias: trends_location)

Parameters: id, exclude
Required: id

Returns the top 10 trending topics for a specific WOEID.

Returns: ArrayRef[Trend]

Twitter API documentation: GET trends/place

🔧 trends_weekly [DEPRECATED]

Parameters: date, exclude
Required: none

Returns the top 30 trending topics for each day in a given week.

Returns: HashRef

🔧 unsubscribe_list

Parameters: list_id, slug, owner_screen_name, owner_id
Required: none

Unsubscribes the authenticated user from the specified list.

Returns: List

Twitter API documentation: POST lists/subscribers/destroy

🔧 update

Parameters: attachment_url, display_coordinates, in_reply_to_status_id, lat, long, media_ids, place_id, status, trim_user
Required: status

Updates the authenticating user's status. Requires the status parameter specified. A status update with text identical to the authenticating user's current status will be ignored.

Returns: Status

Twitter API documentation: POST statuses/update

🔧 update_account_settings

Parameters: trend_location_woid, sleep_time_enabled, start_sleep_time, end_sleep_time, time_zone, lang
Required: none

Updates the authenticating user's settings.

Returns: HashRef

Twitter API documentation: POST account/settings

🔧 update_delivery_device

Parameters: device, include_entities
Required: device

Sets which device Twitter delivers updates to for the authenticating user. Sending none as the device parameter will disable SMS updates.

Returns: BasicUser

Twitter API documentation: POST account/update_delivery_device

🔧 update_friendship

Parameters: user_id, screen_name, device, retweets
Required: none

Allows you enable or disable retweets and device notifications from the specified user. Requires authentication.

Returns: HashRef

Twitter API documentation: POST friendships/update

🔧 update_list

Parameters: list_id, slug, name, mode, description, owner_screen_name, owner_id
Required: none

Updates the specified list. The authenticated user must own the list.

Returns: List

Twitter API documentation: POST lists/update

🔧 update_location [DEPRECATED]

Parameters: location
Required: location

This method has been deprecated in favor of the update_profile method.

Returns: BasicUser

🔧 update_profile

Parameters: name, url, location, description, include_entities, skip_status
Required: none

Sets values that users are able to set under the "Account" tab of their settings page. Only the parameters specified will be updated.

Returns: ExtendedUser

Twitter API documentation: POST account/update_profile

🔧 update_profile_background_image

Parameters: image, tile, include_entities, skip_status, use
Required: none

Updates the authenticating user's profile background image. The "image" parameter must be an arrayref with the same interpretation as in update_profile_image.

Returns: ExtendedUser

Twitter API documentation: POST account/update_profile_background_image

🔧 update_profile_banner

Parameters: banner, width, height, offset_left, offset_top
Required: banner

Uploads a profile banner on behalf of the authenticating user. The "image" parameter is an arrayref.

Returns: Nothing

Twitter API documentation: POST account/update_profile_banner

🔧 update_profile_colors

Parameters: profile_background_color, profile_text_color, profile_link_color, profile_sidebar_fill_color, profile_sidebar_border_color, include_entities, skip_status
Required: none

Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com.

Returns: ExtendedUser

Twitter API documentation: POST account/update_profile_colors

🔧 update_profile_image

Parameters: image, include_entities, skip_status
Required: image

Updates the authenticating user's profile image. The "image" parameter is an arrayref.

Returns: ExtendedUser

Twitter API documentation: POST account/update_profile_image

🔧 update_with_media [DEPRECATED]

Parameters: status, media[], possibly_sensitive, in_reply_to_status_id, lat, long, place_id, display_coordinates
Required: status, media[]

Updates the authenticating user's status and attaches media for upload. Note: Twitter has marked this endpoint as deprecated.

Returns: Status

🔧 upload

Parameters: media
Required: media

Uploads an image to twitter without immediately posting it to the authenticating user's timeline. Returns a hashref with a "media_id" value.

Returns: HashRef

Twitter API documentation: POST media/upload

🔧 upload_status

Parameters: media_id, command
Required: media_id, command

Check the status for async video uploads.

Returns: status

Twitter API documentation: GET media/upload

🔧 user_suggestions (alias: follow_suggestions)

Parameters: slug, lang
Required: slug

Access the users in a given slug of the Twitter suggested user list and return their most recent status if they are not a protected user.

Returns: ArrayRef

Twitter API documentation: GET users/suggestions/:slug/members

🔧 user_suggestions_for (alias: follow_suggestions_for)

Parameters: slug, lang
Required: slug

Access the users in a given slug of the Twitter suggested user list.

Returns: ArrayRef

Twitter API documentation: GET users/suggestions/:slug

🔧 user_timeline

Parameters: user_id, screen_name, since_id, max_id, count, trim_user, exclude_replies, include_rts, contributor_details
Required: none

Returns the 20 most recent statuses posted by the authenticating user, or the user specified by "screen_name" or "user_id".

Returns: ArrayRef[Status]

Twitter API documentation: GET statuses/user_timeline

🔧 users_search (alias: find_people, search_users)

Parameters: q, per_page, page, count, include_entities
Required: q

Run a search for users similar to Find People button on Twitter.com. It is only possible to retrieve the first 1000 matches.

Returns: ArrayRef[Users]

Twitter API documentation: GET users/search

🔧 verify_credentials

Parameters: include_entities, skip_status, include_email
Required: none

Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not.

Returns: ExtendedUser

Twitter API documentation: GET account/verify_credentials

🔍 Search API Methods

These methods are provided when trait "API::Search" is included in the "traits" option to "new".

🔹 search

Parameters: q, geocode, lang, locale, result_type, count, until, since_id, max_id, include_entities, callback
Required: q

Returns a HASH reference with some meta-data about the query including the "next_page", "refresh_url", and "max_id". The statuses are returned in "results".

Returns: HashRef

📋 Lists API Methods

The original Lists API methods have been deprecated. Net::Twitter::Role::API::Lists provides backwards compatibility for code written using those deprecated methods. If you're not already using the "API::Lists" trait, don't! Use the lists methods described above.

🕵️ TwitterVision API Methods

These methods are provided when trait "API::TwitterVision" is included in the "traits" option to "new".

🔹 current_status

Parameters: id, callback
Required: id

Get the current location and status of a user.

Returns: HashRef

🔹 update_twittervision

Parameters: location
Required: location

Updates the location for the authenticated user.

Returns: HashRef

🔙 LEGACY COMPATIBILITY

This version of Net::Twitter automatically includes the "Legacy" trait if no "traits" option is provided to "new". Therefore, these 2 calls are currently equivalent:

$nt = Net::Twitter->new(username => $user, password => $passwd);
$nt = Net::Twitter->new(
    username => $user,
    password => $passwd,
    traits   => ['Legacy'],
);

Thus, existing applications written for a prior version of Net::Twitter should continue to run, without modification, with this version.

In a future release, the default traits may change. Prior to that change, however, a nearer future version will add a warning if no "traits" option is provided to "new". To avoid this warning, add an appropriate "traits" option to your existing application code.

⚠️ ERROR HANDLING

There are currently two strategies for handling errors: throwing exceptions and wrapping errors. Exception handling is the newer, recommended strategy.

🔹 Wrapping Errors

When trait "WrapError" is specified (or "Legacy", which includes trait "WrapError"), Net::Twitter returns undef on error. To retrieve information about the error, use methods "http_code", "http_message", and "get_error".

if ( my $followers = $nt->followers ) {
    for my $follower ( @$followers ) {
        #...
    }
}
else {
    warn "HTTP message: ", $nt->http_message, "\n";
}

Since an error is stored in the object instance, this error handling strategy is problematic when using a user agent like LWP::UserAgent::POE that provides concurrent requests.

🔹 Exception Handling

When Net::Twitter encounters a Twitter API error or a network error, it throws a Net::Twitter::Error object. You can catch and process these exceptions by using "eval" blocks and testing $@:

eval {
    my $statuses = $nt->friends_timeline(); # this might die!
    for my $status ( @$statuses ) {
        #...
    }
};
if ( $@ ) {
    if ( blessed $@ && $@->isa('Net::Twitter::Error') ) {
        warn $@->error;
    }
    else {
        die $@;
    }
}

Net::Twitter::Error stringifies to something reasonable, so if you don't need detailed error information, you can simply treat $@ as a string:

eval { $nt->update($status) };
if ( $@ ) {
    warn "update failed because: $@\n";
}

❓ FAQ

• Why does followers({ screen_name => $friend }) return my followers instead of $friend's? — Check carefully to make sure you've spelled "screen_name" correctly. Twitter sometimes discards parameters it doesn't recognize.
• How do I use the "geocode" parameter in the Search API? — The geocode parameter value includes a latitude, longitude, and radius separated with commas: $r = $nt->search({ geocode => "45.511795,-122.675629,25mi" });
• How do I get Twitter to display something other than "from Perl Net::Twitter"? — If you set the source parameter to "api", twitter will display "from API", and if you set it to the empty string, twitter will display "from web". If you want something other than "Net::Twitter", "API", or "web", you need to register an application and use OAuth authentication.

📚 SEE ALSO

• Net::Twitter::Error — The Net::Twitter exception object.
• http://dev.twitter.com/doc — Official Twitter API documentation.
• LWP::UserAgent::POE — LWP::UserAgent compatible class for POE based applications.
• Catalyst::Authentication::Credential::Twitter — Twitter OAuth authentication support for Catalyst.

🛠️ SUPPORT

Please report bugs to bug-net-twitter@rt.org, or through the web interface at https://rt.cpan.org/Dist/Display.html?Queue=Net-Twitter.

Join the Net::Twitter IRC channel at irc://irc.perl.org/net-twitter.

Follow perl_api: http://twitter.com/perl_api.

Track Net::Twitter development at http://github.com/semifor/Net-Twitter.

🙏 ACKNOWLEDGEMENTS

Many thanks to Chris Thompson cpan@cthompson.com, the original author of Net::Twitter and all versions prior to 3.00.

Also, thanks to Chris Prather (perigrin) for answering many design and implementation questions, especially with regards to Moose.

👤 AUTHOR

Marc Mims marc@questright.com (@semifor on Twitter)

👥 CONTRIBUTORS

• Roberto Etcheverry retcheverry@gmail.com
• KATOU Akira
• Francisco Pecorella
• Doug Bell doug@plainblack.com
• Justin Hunter justin.d.hunter@gmail.com
• Allen Haim allen@netherrealm.net
• Joe Papperello
• Samuel Kaufman
• AnnMary Mathew
• Olaf Alders

📄 LICENSE

Copyright (c) 2009-2016 Marc Mims

The Twitter API itself, and the description text used in this module is: Copyright (c) 2016 Twitter

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

⚠️ DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

📘 NAME 🚀 Quick Reference 📌 VERSION 📝 SYNOPSIS 🐦 TWITTER API V1.1 SUPPORT 📖 DESCRIPTION 📤 RETURN VALUES ⚙️ METHODS AND ARGUMENTS 🔐 AUTHENTICATION 📡 API METHODS AND ARGUMENTS 🔧 REST API Methods 🔍 Search API Methods 📋 Lists API Methods 🕵️ TwitterVision API Methods 🔙 LEGACY COMPATIBILITY ⚠️ ERROR HANDLING ❓ FAQ 📚 SEE ALSO 🛠️ SUPPORT 🙏 ACKNOWLEDGEMENTS 👤 AUTHOR 👥 CONTRIBUTORS 📄 LICENSE ⚠️ DISCLAIMER OF WARRANTY