perldoc > Net::Twitter

📛 NAME

Net::Twitter — Perl interface to the Twitter APIs

🚀 Quick Reference

Use CaseCommandDescription
Post a tweet$nt->update('Hello, world!')Update authenticating user's status
Get home timeline$nt->home_timeline()Retrieve 20 most recent statuses from friends
Search tweets$nt->search({ q => $term })Search public tweets
Follow a user$nt->create_friend($screen_name)Follow a user by screen name
Upload an image$nt->upload($file)Upload media without posting
Verify credentials$nt->verify_credentials()Test if authentication is valid
Show a user$nt->show_user({ screen_name => $name })Get extended user information
List followers$nt->followers_ids()Get array of follower IDs
Send direct message$nt->new_direct_message($text)Send DM to a user
Get trending topics$nt->trends_place(1)Global trending topics (WOEID=1)

📦 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 your 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.

📖 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.

ON 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 its 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.

📤 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:

Examples:

$nt = Net::Twitter->new(traits => ['API::RESTv1_1']);
$nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 API::Search WrapError/]);
$nt = Net::Twitter->new(traits => ['Legacy']);

legacy

A boolean. If set to 0, constructs a Net::Twitter object implementing the REST API and throwing exceptions. If set to 1, uses the Legacy trait.

username, password

Credentials for Basic Authentication (deprecated by Twitter, but supported for compatible services).

clientname, clientver, clienturl

Values for HTTP headers X-Twitter-Client-Name, X-Twitter-Client-Version, X-Twitter-Client-URL.

useragent_class, useragent_args, useragent

Specify LWP::UserAgent compatible class and configuration. Default: LWP::UserAgent and "Net::Twitter/4.01043 (Perl)".

source

No longer used by Twitter; retained for compatible services.

apiurl, apirealm, identica, ssl, netrc, netrc_machine

Configuration for API endpoint, realm, identi.ca support, SSL, and .netrc credentials.

consumer_key, consumer_secret

OAuth consumer credentials (available when OAuth trait is included).

decode_html_entities

If set to 1, HTML entities in the "text" field of statuses are automatically decoded. Default 0.

credentials($username, $password)

Set credentials for Basic Authentication. Useful 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 consumer_key and consumer_secret options to new. When provided, the OAuth trait is automatically included. See Net::Twitter::Role::OAuth for more information on using OAuth, including examples.

To set up Basic Authentication, provide username and password options to new or call the credentials method.

In addition to the arguments specified for each API method, an additional -authenticate parameter can be passed to request or suppress an Authorization header.

🛠️ 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 methods accept simple positional arguments. See full documentation for details.

Cursors and Paging

Some methods return partial results a page at a time. Originally used page parameter; newer methods use cursor parameter. Examples:

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

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

Synthetic Arguments

🔴 REST API Methods

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

Common Parameters

Method List

🔍 Search API Methods

These methods are provided when trait API::Search is included.

📋 Lists API Methods

The original Lists API methods are deprecated. See Net::Twitter::Role::API::Lists for backwards compatibility.

🌐 TwitterVision API Methods

Provided when trait API::TwitterVision is included.

🔄 LEGACY COMPATIBILITY

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

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

Existing applications written for a prior version of Net::Twitter should continue to run without modification. In a future release, the default traits may change, and a warning will be added if no traits option is provided.

⚠️ ERROR HANDLING

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

Wrapping Errors

When trait WrapError (or Legacy) is specified, Net::Twitter returns undef on error. Retrieve error info via http_code, http_message, and get_error. See Net::Twitter::Role::WrapError.

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

Exception Handling

When Net::Twitter encounters an error, it throws a Net::Twitter::Error object. Use eval blocks:

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

Net::Twitter::Error stringifies reasonably:

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

❓ FAQ

👀 SEE ALSO

📞 SUPPORT

Report bugs to bug-net-twitter AT rt.org or via web 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.

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

🙏 ACKNOWLEDGEMENTS

Many thanks to Chris Thompson (cpan AT 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.

✍️ AUTHOR

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

👥 CONTRIBUTORS

Roberto Etcheverry, KATOU Akira, Francisco Pecorella, Doug Bell, Justin Hunter, Allen Haim, 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.

Net::Twitter □✕
📛 NAME 🚀 Quick Reference 📦 VERSION 📋 SYNOPSIS 🐦 TWITTER API V1.1 SUPPORT 📖 DESCRIPTION
ON TWITTER API VERSION 1.1 OMG! THE MOOSE!
📤 RETURN VALUES ⚙️ METHODS AND ARGUMENTS
new credentials($username, $password) ua
🔐 AUTHENTICATION 🛠️ API METHODS AND ARGUMENTS
Cursors and Paging Synthetic Arguments 🔴 REST API Methods 🔍 Search API Methods 📋 Lists API Methods 🌐 TwitterVision API Methods
🔄 LEGACY COMPATIBILITY ⚠️ ERROR HANDLING
Wrapping Errors Exception Handling
❓ FAQ 👀 SEE ALSO 📞 SUPPORT 🙏 ACKNOWLEDGEMENTS ✍️ AUTHOR 👥 CONTRIBUTORS 📄 LICENSE ⚖️ DISCLAIMER OF WARRANTY

Generated by phpman v4.9.29 · Markdown · JSON · MCP Author: Che Dong Under GNU General Public License
2026-07-21 00:33 @2600:1f28:365:80b0:d8a5:c3c6:bf94:28c0
CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0 Transitional!Valid CSS!
Enhanced by LLM: deepseek-v4-flash / taotoken.net / www.chedong.com - original format

^_top_^