Net::T...APIv1_1(3pm)

📦
version 0.12008 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Net::Twitter::Lite::WithAPIv1_1 — the perl-to-Twitter-v1.1 pipeline bestie 💖

okay so. this is a perl interface to the Twitter API v1.1, and the manual name is Net::T...APIv1_1(3pm) — yes the man page really does abbreviate it like that, no cap, that's just how the header got squished. let's go 🌸

✨ NAME ✨

Net::Twitter::Lite::WithAPIv1_1 — a perl interface to the Twitter API v1.1 🦋

✨ VERSION ✨

version 0.12008 💅

✨ SYNOPSIS ✨

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

my $nt = Net::Twitter::Lite::WithAPIv1_1->new(
    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->home_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::Lite::Error');

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

like. look at that. an entire twitter client in a few lines. she's beauty, she's grace 💅✨

✨ DESCRIPTION ✨

This module hands you a perl interface to the Twitter APIs. Want the full scoop on what those APIs even are? Go read <https://dev.twitter.com/docs/api/1.1/overview>. 🫶

✨ RETURN VALUES ✨

okay bestie, here's the vibe: Net::Twitter::Lite takes the data structures Twitter sends back and decodes them into native perl data structures — that's HASH references and ARRAY references, iykyk.

The full layout of those structures is not documented here. nope. because they change constantly — usually by just tacking on new elements — and documenting every single one of those changes would be a significant challenge. 😭

so instead? rely on the online Twitter API documentation and, honestly, on just inspecting the returned data yourself. main character research energy.

the Twitter API online documentation lives at <https://dev.twitter.com/docs/api/1.1/overview> 👑

and to peek at the data, use Data::Dumper or whatever similar module you're obsessed with. here's a little example with Data::Dumper:

use Data::Dumper;

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

want more on perl data structures in general? see perlreftut, perldsc, and perllol. 📚

✨ METHODS AND ARGUMENTS ✨

new 💖

This constructs a Net::Twitter::Lite::WithAPIv1_1 object. It takes a bunch of named parameters, and guess what — all of them are optional. iconic behaviour, honestly.

  • clientname — the value for the X-Twitter-Client-Name HTTP header. defaults to Perl Net::Twitter::Lite::WithAPIv1_1. ⚠️ note: this option has nothing to do with the via application byline, so don't get it twisted.
  • clientver — the value for the X-Twitter-Client-Version HTTP header. defaults to the current version of this module.
  • clienturl — the value for the X-Twitter-Client-URL HTTP header. defaults to the search.cpan.org page for the Net::Twitter::Lite distribution.
  • useragent_class — the LWP::UserAgent-compatible class used internally to make HTTP requests. defaults to LWP::UserAgent. if you're building a POE-based application, consider LWP::UserAgent::POE instead. 🧚
  • useragent_args — an HASH ref of arguments to pass to the constructor of the class you set with useragent_class (above). defaults to {} (an empty HASH ref).
  • useragent — the value for the User-Agent HTTP header. defaults to Net::Twitter::Lite::WithAPIv1_1/$VERSION (Perl), where $VERSION is the current version of this module.
  • source — Twitter no longer uses the source parameter (and yes, the original docs literally say "on longer", we're keeping it real, no cap 💀). Support for it remains in this module for any compatible services that might still use it. It was originally used by Twitter to provide a via application byline.
  • apiurl — the URL for the Twitter API. defaults to http://api.twitter.com/1.1. this option is available when the API::RESTv1_1 trait is included.
  • upload_url — base URL for media uploads. defaults to https://upload.twitter.com/1.1.
  • apirealm — a string containing the Twitter API realm used for Basic Authentication. defaults to Twitter API. this option is available when the API::RESTv1_1 trait is included.
  • identica — if set to 1, Net::Twitter::Lite::WithAPIv1_1 overrides the defaults for apiurl, apihost, and apirealm to http://identi.ca/api, identi.ca:80, and Laconica API respectively. defaults to 0.
  • consumer_key — a string containing the OAuth consumer key Twitter hands you when an application is registered. this option is available when the OAuth trait is included. 🔑
  • consumer_secret — a string containing the OAuth consumer secret. this option is available when the OAuth trait is included. 🤫
  • ssl — if set to 1, an SSL connection will be used for all API calls. defaults to 1. 🔒
  • netrc — (optional) sets the machine key to look up in .netrc to obtain credentials. if set to 1, it'll use the value of the netrc_machine option (below).
# in .netrc
machine api.twitter.com
  login YOUR_TWITTER_USER_NAME
  password YOUR_TWITTER_PASSWORD
machine semifor.twitter.com
  login semifor
  password SUPERSECRET

# in your perl program
$nt = Net::Twitter::Lite::WithAPIv1_1->new(netrc => 1);
$nt = Net::Twitter::Lite::WithAPIv1_1->new(netrc => 'semifor.twitter.com');
  • netrc_machine — (optional) sets the machine entry to look up in .netrc when <netrc = 1>> is used. defaults to api.twitter.com.
  • wrap_result — (optional) if set to 1, this option returns a Net::Twitter::Lite::WrapResult object, which hands you both the Twitter API result and the HTTP::Response object for the API call. see Net::Twitter::Lite::WrapResult for the deets. 🎀

credentials($username, $password) 🔐

Sets the credentials for Basic Authentication. super handy for juggling multiple accounts at once. slay.

✨ AUTHENTICATION ✨

okay so here's the tea with Twitter API version 1.1: all API calls require OAuth. periodt. Other Twitter-compatible services, like Identi.ca, accept Basic Authentication. So this module supports both. 🫶

For OAuth authentication: pass consumer_key and consumer_secret arguments to new. Set access_token and access_token_secret for each call, or just pass them as arguments to new.

For Basic Authentication: pass the username and password options to new, or call the credentials method.

And on top of the arguments specified for each API method below, you can also pass an extra authenticate parameter. Want an Authorization header? pass authenticate => 1. Want to suppress an authentication header? pass authenticate => 0. But heads up: even if you ask for one, an Authorization header will not be added if there are no user credentials — that's username and password for Basic Authentication, access tokens for OAuth. 💀

This is probably only useful for non-Twitter sites that use the Twitter API and support unauthenticated calls.

✨ API METHODS AND ARGUMENTS ✨

Most Twitter API methods take parameters. All API methods will accept a HASH ref of named parameters, exactly as specified in the Twitter API documentation. But for convenience, lots of methods also accept simple positional arguments. The positional style is totally optional — you can always use the named parameters in a HASH reference if that's more your vibe.

Here's the deal:

  • 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 positionally 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 form:

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

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

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

You can also use the convenient positional form for the required status parameter while putting the optional parameters 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);

Lots of API methods have aliases. Use the API method name, or any of its aliases, whichever you prefer. For example, these calls are all equivalent:

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

And aliases support both the HASH ref and convenient forms:

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

🌈 Synthetic Arguments 🌈

On top of the arguments described in the Twitter API Documentation for each API method, these additional synthetic arguments are supported.

  • authenticate — when set to 1, an Authorization header for the API call will be provided; when set to 0, it suppresses the Authentication header. This argument overrides the defined authentication behavior for the API method. It's probably only useful for the rate_limit_satus method, which returns different values for authenticated and unauthenticated calls. See "AUTHENTICATION" for more details. 💅

✨ API Methods ✨

account_settings ⚙️

Parameters: none
Required: none

Returns the current trend, geo and sleep time information for 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 to be able to add members to it. ⚠️ Note that lists can't have more than 500 members.

Returns: User

add_place 📍

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

(more parts coming bestie, don't go anywhere 💖)

okay so back to create_place for a sec, because the setup matters: before you can make a place, you have to query similar_places with the latitude, longitude and name of the place you wanna create. That query hands you back an array of places that are similar to the one you're dreaming up, plus a token. And if your place isn't in that returned array? You take the token and use this method to create a brand new one. That's the whole vibe. 💅

  • Returns: Place

🦋 blocking

alias: blocks_list

  • Parameters: cursor, include_entities, skip_status
  • Required: none

Returns an array of user objects that the authenticating user is blocking. like, the full receipts of who you've blocked. 🙈

  • Returns: ArrayRef[BasicUser]

🦋 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]

🦋 contributees

  • 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

  • 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

🎀 create_block(id)

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

Blocks the user specified in the user_id or screen_name parameter as the authenticating user. Returns the blocked user when it works. You can find out more about blocking in the Twitter Support Knowledge Base.

  • Returns: BasicUser

🎀 create_favorite

🎀 create_favorite(id)

  • Parameters: id, include_entities
  • Required: id

Favorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful. it's giving "you're my favorite, officially". ⭐

  • Returns: Status

🎀 create_friend

alias: follow

alias: follow_new

alias: create_friendship

  • Parameters: user_id, screen_name, follow
  • Required: none

Follows the user specified in the user_id or screen_name parameter as the authenticating user. Returns the befriended user when successful. And when it doesn't work? It returns a string describing the failure condition. no silent Ls here.

  • Returns: BasicUser

🎀 create_list

🎀 create_list(name)

  • 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. (the limit is real, bestie.)

  • Returns: List

🎀 create_saved_search(query)

  • Parameters: query
  • Required: query

Creates a saved search for the authenticated user.

  • Returns: SavedSearch

💀 delete_list

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

Deletes the specified list. The authenticated user must own the list to be able to destroy it. you can only delete what's yours, periodt.

  • Returns: List

💀 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 to remove members from the list.

  • Returns: User

💀 destroy_block

💀 destroy_block(id)

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

Un-blocks the user specified in the user_id or screen_name parameter as the authenticating user. Returns the un-blocked user when successful. unblocking arc. ✨

  • Returns: BasicUser

💀 destroy_direct_message

💀 destroy_direct_message(id)

  • Parameters: id, include_entities
  • Required: id

Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message.

Important: this method requires an access token with RWD (read, write, and direct message) permissions. 🔥
  • Returns: DirectMessage

💀 destroy_favorite

💀 destroy_favorite(id)

  • Parameters: id, include_entities
  • Required: id

Un-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status.

  • Returns: Status

💀 destroy_friend

💀 destroy_friend(id)

alias: unfollow

alias: destroy_friendship

  • Parameters: user_id, screen_name
  • Required: id

Discontinues friendship with the user specified in the user_id or screen_name parameter as the authenticating user. Returns the un-friended user when successful. Returns a string describing the failure condition when unsuccessful. sad girl hours but make it API. 😭

  • Returns: BasicUser

💀 destroy_saved_search(id)

alias: delete_saved_search

  • Parameters: id
  • Required: id

Destroys a saved search. The search, specified by id, must be owned by the authenticating user.

  • Returns: SavedSearch

💀 destroy_status

💀 destroy_status(id)

  • Parameters: id, trim_user
  • Required: id

Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status.

  • Returns: Status

🌈 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, including detailed information about the sending and recipient users.

Important: this method requires an access token with RWD (read, write, and direct message) permissions. 🔥
  • Returns: ArrayRef[DirectMessage]

🌈 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 by the ID parameter.

  • Returns: ArrayRef[Status]

🌈 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

🌈 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. Heads up: the order of the IDs may change from call to call. If you want the screen names, pass the arrayref to lookup_users.

Use the optional cursor parameter to retrieve IDs in pages of 5000. When the cursor parameter is used, the return value is a reference to a hash with keys previous_cursor, next_cursor, and ids. The value of ids is a reference to an array of IDS of the user's followers. Set the optional cursor parameter to -1 to get the first page of IDs. Set it to the prior return's value of previous_cursor or next_cursor to page forward or backwards. When there are no prior pages, the value of previous_cursor will be 0. When there are no subsequent pages, the value of next_cursor will be 0.

  • Returns: HashRef|ArrayRef[Int]

🌈 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

🌈 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. The order of the IDs is reverse chronological.

Use the optional cursor parameter to retrieve IDs in pages of 5000. When the cursor parameter is used, the return value is a reference to a hash with keys previous_cursor, next_cursor, and ids. The value of ids is a reference to an array of IDS of the user's friends. Set the optional cursor parameter to -1 to get the first page of IDs. Set it to the prior return's value of previous_cursor or next_cursor to page forward or backwards. When there are no prior pages, the value of previous_cursor will be 0. When there are no subsequent pages, the value of next_cursor will be 0.

  • Returns: HashRef|ArrayRef[Int]

🧚 friendships_incoming

alias: incoming_friendships

  • Parameters: cursor, stringify_ids
  • Required: none

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

  • Returns: HashRef

🧚 friendships_outgoing

alias: outgoing_friendships

  • Parameters: cursor, stringify_ids
  • Required: none

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

  • Returns: HashRef

🗺️ geo_id

🗺️ geo_id(id)

  • Parameters: id
  • Required: id

Returns details of a place returned from the reverse_geocode method.

  • Returns: HashRef
  • 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 a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status.

Conceptually, a query can be made from the user's location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location with a call to statuses/update.

This is the recommended method to use to find places that can be attached to statuses/update. Unlike geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regards to the user who is authenticated. This approach is also preferred for interactive place matching with the user.

  • Returns: HashRef

⚙️ get_configuration

  • Parameters: none
  • Required: none

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

It is recommended applications request this endpoint when they are loaded, but no more than once a day. don't be that app. 🙈

Returns: HashRef

get_languages

  • Parameters: none
  • Required: none

Bestie, this one hands you back every language Twitter supports, plus its ISO 639-1 code. And that ISO 639-1 code? It's the two-letter value you'd drop in as lang if you're passing lang along with any of your requests. 💖

  • Returns: ArrayRef[Lanugage]

get_list

  • alias: show_list
  • Parameters: list_id, slug, owner_screen_name, owner_id
  • Required: none

Gives you back the list you asked for. Heads up tho — private lists will only be shown if the authenticated user owns the specified list. 👑

  • Returns: List

get_lists

  • alias: all_subscriptions
  • alias: list_lists all_subscriptions
  • Parameters: user_id, screen_name, reverse
  • Required: none

Returns every list the authenticating user — or a specified user — subscribes to, their own included. You point at the user with the user_id or screen_name parameters. No user given? Then it's the authenticating user, periodt.

Now the tea ☕: a maximum of 100 results come back from this call. Subscribed lists show up first, then owned lists. So if someone subscribes to 90 lists and owns 20, this method gives you 90 subscriptions and 10 owned lists. The reverse method flips it — owned lists first — so with "reverse =" 1>, you'd get 20 owned lists and 80 subscriptions. If your actual goal is to grab every list a user owns or subscribes to, use <list_ownerships> and/or "list_subscriptions" instead. 🌈

  • Returns: ArrayRef[Lists]

get_privacy_policy

  • Parameters: none
  • Required: none

Returns Twitter's privacy policy. That's it, that's the whole vibe. 📜

  • Returns: HashRef

get_tos

  • Parameters: none
  • Required: none

Returns the Twitter Terms of Service. And no, these are not the same as the Developer Rules of the Road — don't @ me. ⚖️

  • Returns: HashRef

home_timeline

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

Returns the 20 most recent statuses, retweets included, posted by the authenticating user and that user's friends. It's giving home feed energy fr fr. 🏠

  • Returns: ArrayRef[Status]

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 show up if the authenticated user owns that list. 🔒

  • Returns: Hashref

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 you don't provide user_id or screen_name, you get the memberships of the authenticating user instead. 🫶

  • Returns: Hashref

list_statuses

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

Returns the tweet timeline for the members of the specified list. Historically, retweets were not available in list timeline responses — but now you can use the include_rts=true parameter to additionally receive retweet objects. Glow up moment. ✨

  • Returns: ArrayRef[Status]

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 specified list. 🤫

  • Returns: Hashref

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 you provide. Values for connections can be: following, following_requested, followed_by, none. Requires authentication.

  • Returns: ArrayRef

lookup_users

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

Returns up to 100 users worth of extended info, specified by either ID, screen name, or a combo of the two. The author's most recent status (if the authenticating user has permission) comes back inline. This method is rate limited to 1000 calls per hour — pace yourself bestie. 🏃‍♀️

This method will accept user IDs or screen names as either a comma delimited string, or as an ARRAY ref. It'll also accept arguments in the normal HASHREF form or as a simple list of named arguments. I.e., any of the following forms are acceptable:

    $nt->lookup_users({ user_id => '1234,6543,3333' });
    $nt->lookup_users(user_id => '1234,6543,3333');
    $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] });
    $nt->lookup_users({ screen_name => 'fred,barney,wilma' });
    $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']);

    $nt->lookup_users(
        screen_name => ['fred', 'barney' ],
        user_id     => '4321,6789',
    );
  • Returns: ArrayRef[User]

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 handing over a reference to an array, or a comma-separated list, of member ids or screen names. The authenticated user must own the list to be able to add members to it. Also note: lists can't have more than 500 members, and you're limited to adding up to 100 members to a list at a time with this method. 💅

  • Returns: List

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. The authenticated user must own the list to be able to remove members from it. Same rules as before: lists can't have more than 500 members, and you're limited to removing up to 100 members to a list at a time with this method.

Please note that there can be issues with lists that rapidly remove and add memberships. Take care when using these methods such that you are not too rapidly switching between removals and adds on the same list. 😭
  • Returns: List

mentions

  • alias: replies
  • alias: 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. It's giving main character notifications. 🔔

  • Returns: ArrayRef[Status]

new_direct_message

new_direct_message(text)
  • Parameters: user_id, screen_name, text
  • Required: text

Sends a brand new direct message to the specified user from the authenticating user. Requires both the user and text parameters. Returns the sent message when it works out. 💌 And — in order to support numeric screen names, the screen_name or user_id parameters may be used instead of user.

Important: this method requires an access token with RWD (read, write, and direct message) permissions.
  • Returns: DirectMessage

no_retweet_ids

  • Parameters: none
  • Required: none

Returns an ARRAY ref of user IDs for which the authenticating user does not want to receive retweets. Setting boundaries, we love to see it. 🙈

  • Returns: ArrayRef[UserIDs]

oembed

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

Returns information that lets you create an embedded representation of a Tweet on third party sites. Peep the oEmbed <http://oembed.com/> specification for info about the response format.

While this endpoint allows a bit of customization for the final appearance of the embedded Tweet, be aware that the appearance of the rendered Tweet may change over time to be consistent with Twitter's Display Requirements <https://dev.twitter.com/terms/display-requirements>. So do not rely on any class or id parameters staying constant in the returned markup. 😤

  • Returns: Status

profile_banner

  • Parameters: user_id, screen_name
  • Required: none

Returns a hash reference mapping the available size variations to URLs you can use to retrieve each variation of the banner. 🎀

  • Returns: HashRef

rate_limit_status

rate_limit_status(resources)
  • 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. ⏳

Use ->rate_limit_status({ authenticate => 0 }) to force an unauthenticated call, which will return the status for the IP address rather than the authenticated user. (Note: for a web application, this is the server's IP address.)

  • Returns: RateLimitStatus

remove_profile_banner

  • Parameters: none
  • Required: none

Removes the uploaded profile banner for the authenticating user. Gone, deleted, no more. 🧹

  • Returns: Nothing

report_spam

report_spam(id)
  • Parameters: user_id, screen_name
  • Required: id

The user specified in the id gets blocked by the authenticated user and reported as a spammer. Double tap. 🚫

  • Returns: User

retweet

retweet(id)
  • Parameters: idtrim_user
  • Required: id

Retweets a tweet. Simple as that. 🔁

  • Returns: Status

retweets

retweets(id)
  • Parameters: id, count, trim_user
  • Required: id

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

  • Returns: Arrayref[Status]

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. Look at you getting shared around. 👑

  • Returns: ArrayRef[Status]

reverse_geocode

reverse_geocode(lat, long)
  • 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 that can be used as a place_id when updating a status. Conceptually, a query can be made from the user's location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location up with a call to statuses/update. 📍

There are multiple granularities of places that can be returned — neighborhoods, cities, etc. At this time, only United States data is available through this method. 😭

  • lat — Required, bestie, you gotta give it. The latitude you're asking about. Valid ranges are -90.0 to +90.0 (North is positive) inclusive. 💅
  • long — Required. The longitude you're asking about. Valid ranges are -180.0 to +180.0 (East is positive) inclusive. 🌍
  • accuracy — Optional. A lil hint on the "region" to search in. If it's a number, that's a radius in meters, but it can also take a string suffixed with ft to say feet. Not passed in? Then it's assumed to be 0m. If it's coming from a device, in practice this value is whatever accuracy the device has measuring its location (whether that's GPS, WiFi triangulation, etc.). 📡
  • granularity — Optional. The minimal granularity of data to return. Not passed in? Then "neighborhood" is assumed. "city" can also be passed. 🏙️
  • max_results — Optional. A hint on how many results to return. This does not guarantee the number returned will equal max_results, it just informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here. ✨

Returns: HashRef

saved_searches

Parameters: none Required: none

Returns the authenticated user's saved search queries. 🎀

Returns: ArrayRef[SavedSearch]

search(q)

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". To iterate over the results, use something similar to:

my $r = $nt->search($searh_term);
for my $status ( @{$r->{statuses}} ) {
    print "$status->{text}\n";
}

Returns: HashRef

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, including detailed info about the sending and recipient users. 💌

Important: this method requires an access token with RWD (read, write, and direct message) permissions. 🔐

Returns: ArrayRef[DirectMessage]

show_direct_message

show_direct_message(id)

Parameters: id Required: id

Returns a single direct message, specified by an id parameter. Like the "direct_messages" request, this method will include the user objects of the sender and recipient. Requires authentication. ✨

Important: this method requires an access token with RWD (read, write, and direct message) permissions. 🔐

Returns: HashRef

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

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]

show_list_subscriber

alias: is_list_subscriber

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

show_saved_search(id)

Parameters: id Required: id

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

Returns: SavedSearch

show_status

show_status(id)

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

show_user

Parameters: user_id, screen_name, include_entities Required: none

Returns extended information of a given user, specified by ID or screen name as per the required id parameter. This information includes design settings, so third party developers can theme their widgets according to a given user's preferences. You must be properly authenticated to request the page of a protected user. 🎨

Returns: ExtendedUser

similar_places

similar_places(lat, long, name)

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. 🗺️

Conceptually you would use this method to get a list of known places to choose from first. Then, if the desired place doesn't exist, make a request to "add_place" to create a new one.

The token contained in the response is the token needed to be able to create a new place. 🔑

Returns: HashRef

subscribe_list

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

Subscribes the authenticated user to the specified list. 🫶

Returns: List

list_subscriptions

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

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]

list_ownerships

Parameters: user_id screen_name count cursor

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 of the lists. 👑

Returns: Hashref

suggestion_categories

Parameters: none Required: none

Returns the list of suggested user categories. The category slug can be used in the "user_suggestions" API method get the users in that category. Does not require authentication. 🌈

Returns: ArrayRef

Parameters: none Required: none

Returns the locations with trending topic information. The response is an array of "locations" that encode the location's WOEID (a Yahoo! Where On Earth ID <http://developer.yahoo.com/geo/geoplanet/>) and some other human-readable information such as a the location's canonical name and country. 🔥

For backwards compatibility, this method accepts optional "lat" and "long" parameters. You should call "trends_closest" directly, instead.

Use the WOEID returned in the location object to query trends for a specific location. 📍

Returns: ArrayRef[Location]

Parameters: lat, long Required: none

Returns the locations with trending topic information. The response is an array of "locations" that encode the location's WOEID (a Yahoo! Where On Earth ID <http://developer.yahoo.com/geo/geoplanet/>) and some other human-readable information such as a the location's canonical name and country. The results are sorted by distance from that location, nearest to farthest. 📏

Use the WOEID returned in the location object to query trends for a specific location. 📍

Returns: ArrayRef[Location]

Parameters: id, exclude Required: id

Returns the top 10 trending topics for a specific WOEID. The response is an array of "trend" objects that encode the name of the trending topic, the query parameter that can be used to search for the topic on Search, and the direct URL that can be issued against Search. This information is cached for five minutes, and therefore users are discouraged from querying these endpoints faster than once every five minutes. Global trends information is also available from this API by using a WOEID of 1. 🔥

Returns: ArrayRef[Trend]

unsubscribe_list

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

Unsubscribes the authenticated user from the specified list. 💔

Returns: List

update

update(status)

Parameters: status, lat, long, place_id, display_coordinates, in_reply_to_status_id, 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. ✍️

  • status — Required. The text of your status update. URL encode as necessary. Statuses over 140 characters will cause a 403 error to be returned from the API. 😭
  • in_reply_to_status_id — Optional. The ID of an existing status that the update is in reply to. o Note: This parameter will be ignored unless the author of the tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced tweet, within the update. 💬
  • lat — Optional. The location's latitude that this tweet refers to. The valid ranges for latitude is -90.0 to +90.0 (North is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding long parameter with this tweet. 📍
  • long — Optional. The location's longitude that this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding lat parameter with this tweet. 🌍
  • place_id — Optional. The place to attach to this status update. Valid place_ids can be found by querying "reverse_geocode". 🗺️

display_coordinates

okay so this one's optional, bestie 💅 By default, geo-tweets are gonna have their coordinates right there, exposed in the status object (that's the whole point — staying backwards compatible with all the existing API apps out there ✨). But if you wanna turn OFF the display of the precise latitude and longitude — while keeping the contextual location info, because we're not monsters 🙈 — just pass display_coordinates => 0 on the status update 🫶

Returns: Status

update_account_settings

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

Required: none

Updates the settings of the user who's authenticating. Glow-up your own account, that's the vibe 💖

Returns: HashRef

update_delivery_device / update_delivery_device(device)

Parameters: device, include_entities

Required: device

Sets which device Twitter delivers updates to for the authenticating user. And listen — if you send none as the device parameter, it disables SMS updates entirely. Ghost mode, no cap 💀

Returns: BasicUser

update_friendship

Parameters: user_id, screen_name, device, retweets

Required: none

Lets you enable or disable retweets and device notifications from a specific user 👀 All the other values? Assumed to be false, fr fr. Requires authentication.

Returns: HashRef

update_list

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

Required: none

Updates the list you specified. Heads up though — the authenticated user has to actually own the list to be able to update it 👑 no borrowing, bestie.

Returns: List

update_profile

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

Required: none

Sets the values that users are able to set under the "Account" tab of their settings page ✨ And here's the cute part — only the parameters you actually specify get updated. So if you wanna update just the "name" attribute, you only include that one parameter in your request. Minimal effort, maximum slay 💅

Returns: ExtendedUser

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 has to be an arrayref with the exact same interpretation as the image parameter in the update_profile_image method — go read that one's docs for the deets, bestie 🫶 And the use parameter lets you say whether to actually use the uploaded profile background or not.

Returns: ExtendedUser

update_profile_banner / update_profile_banner(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 with the following interpretation:

[ $file ]
[ $file, $filename ]
[ $file, $filename, Content_Type => $mime_type ]
[ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]

The first value of the array ($file) is the name of a file to open 📂 The second value ($filename) is the name given to Twitter for the file. If $filename isn't provided, the basename portion of $file gets used instead. And if $mime_type isn't provided, it'll be provided automatically using LWP::MediaTypes::guess_media_type() ✨

$raw_image_data can be provided — instead of opening a file — by passing undef as the first array value. Iconic behaviour, honestly 💖

Returns: Nothing

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 🌈 Customize that palette, bestie! These values also get returned in the /users/show API method, iykyk.

Returns: ExtendedUser

update_profile_image / update_profile_image(image)

Parameters: image, include_entities, skip_status

Required: image

Updates the authenticating user's profile image 💖 The image parameter is an arrayref with the following interpretation:

[ $file ]
[ $file, $filename ]
[ $file, $filename, Content_Type => $mime_type ]
[ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]

The first value of the array ($file) is the name of a file to open 📂 The second value ($filename) is the name given to Twitter for the file. If $filename isn't provided, the basename portion of $file gets used instead. If $mime_type isn't provided, it'll be provided automatically using LWP::MediaTypes::guess_media_type() ✨

$raw_image_data can be provided — rather than opening a file — by passing undef as the first array value 🫶

Returns: ExtendedUser

upload_media

  • alias: upload

Parameters: media, media_data, additional_owners

Required: media or media_data

The media parameter is an arrayref with the following interpretation:

[ $file ]
[ $file, $filename ]
[ $file, $filename, Content_Type => $mime_type ]
[ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]

The first value of the array ($file) is the name of a file to open 📂 The second value ($filename) is the name given to Twitter for the file. If $filename isn't provided, the basename portion of $file gets used instead. If $mime_type isn't provided, it'll be provided automatically using LWP::MediaTypes::guess_media_type() ✨

$raw_image_data can be provided — rather than opening a file — by passing undef as the first array value 🫶

Or, you can pass base64-encoded data with the media_data parameter instead. Choose your fighter 💅

Returns: Hashref with media_id.

user_suggestions / user_suggestions(category)

  • alias: follow_suggestions

Parameters: category, lang

Required: category

Access the users in a given category of the Twitter suggested user list, and return their most recent status — if they're not a protected user 👀 Currently the supported values for the optional lang parameter are "en", "fr", "de", "es", "it". Does not require authentication, so go off 🎀

Returns: ArrayRef

user_suggestions_for / user_suggestions_for(category)

  • alias: follow_suggestions

Parameters: category, lang

Required: category

Access the users in a given category of the Twitter suggested user list 🌸 (yeah, that's the whole thing, short and sweet bestie)

Returns: ArrayRef

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 by the user you specify with screen_name or user_id 💖

Returns: ArrayRef[Status]

users_search / users_search(q)

  • alias: find_people
  • alias: search_users

Parameters: q, per_page, page, count, include_entities

Required: q

Runs a search for users, similar to the Find People button on Twitter.com ✨ The same results that Twitter.com's people search returns will come back from this API (the whole "being listed in the People Search" thing). Just know: it's only possible to retrieve the first 1000 matches from this API. That's the ceiling, bestie, no going past it 🫶

Returns: ArrayRef[Users]

verify_credentials

Parameters: include_entities, skip_status

Required: none

Returns an HTTP 200 OK response code plus a representation of the requesting user if authentication worked out ✅ And if it didn't? You get a 401 status code and an error message 😭 Use this method to test whether the supplied user credentials are valid. Vibe check your own login, fr fr.

Returns: ExtendedUser

update_with_media / update_with_media(status, media)

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 📸

The media[] parameter is an arrayref with the following interpretation:

[ $file ]
[ $file, $filename ]
[ $file, $filename, Content_Type => $mime_type ]
[ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]

The first value of the array ($file) is the name of a file to open 📂 The second value ($filename) is the name given to Twitter for the file. If $filename isn't provided, the basename portion of $file gets used instead. If $mime_type isn't provided, it'll be provided automatically using LWP::MediaTypes::guess_media_type() ✨

$raw_image_data can be provided — rather than opening a file — by passing undef as the first array value 🫶

Okay important thing: the Tweet text will get rewritten to include the media URL(s), which reduces the number of characters allowed in the Tweet text 😭 And if the URL(s) can't be appended without text truncation, the tweet gets rejected and this method returns an HTTP 403 error. Not a drill, bestie.

Returns: Status

🔍 Search API Methods 🔍

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

search / search(q)

Parameters: q, callback, lang, locale, rpp, page, since_id, until, geocode, show_user, result_type

Required: q

Returns a HASH reference with some meta-data about the query — including the next_page, refresh_url, and max_id 🌟 The statuses come back in results. And to iterate over the results, use something similar to:

my $r = $nt->search($searh_term);
for my $status ( @{$r->{results}} ) {
    print "$status->{text}\n";
}

Returns: HashRef

🌍 TwitterVision API Methods 🌍

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

current_status / current_status(id)

Parameters: id, callback

Required: id

Gets the current location and status of a user 👀 where they at, bestie?

Returns: HashRef

update_twittervision / update_twittervision(location)

Parameters: location

Required: location

Updates the location for the authenticated user 📍

Returns: HashRef

💥 ERROR HANDLING 💥

okay bestie, listen up, because this part is IMPORTANT. when a Twitter API error or a network error happens, a Net::Twitter::Lite::Error object gets thrown. thrown, like, yeeted into the void of $@. so you gotta catch and process those exceptions using eval blocks and testing $@, mmkay? 🎀

eval {
    my $statuses = $nt->friends_timeline(); # this might die!

    for my $status ( @$statuses ) {
        #...
    }
};
if ( $@ ) {
    # friends_timeline encountered an error

    if ( blessed $@ && $@->isa('Net::Twitter::Lite::Error') ) {
        #... use the thrown error obj
        warn $@->error;
    }
    else {
        # something bad happened!
        die $@;
    }
}

see what we did there? 👑 blessed $@ and an isa check, so you know it's your error object and not some random chaos. if it is, you use $@->error. if it's not — something bad happened — you just die $@ and let it be someone else's problem fr fr. 💀

and here's the cute part: Net::Twitter::Lite::Error stringifies to something reasonable, so if you don't need all the detailed error info, you can literally just treat $@ as a plain string and move on with your life:

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

lowkey elegant. highkey convenient. 🦋

👀 SEE ALSO 👀

  • Net::Twitter::Lite::Error — the Net::Twitter::Lite exception object, aka the thing that gets thrown at you when stuff goes sideways. 💅
  • <http://dev.twitter.com/rest/reference> — the official Twitter API documentation. it describes the methods and their parameters in more detail, and honestly? it may be more current than the documentation provided with this module. so like, go look, bestie. 📖✨
  • LWP::UserAgent::POE — this LWP::UserAgent compatible class can be used in POE based application along with Net::Twitter::Lite to provide concurrent, non-blocking requests. very async, very slay. 🔥
  • Catalyst::Authentication::Credential::Twitter — this module, by Jesse Stay, provides Twitter OAuth authentication support for the popular Catalyst web application framework. auth, but make it Catalyst. 🎀
  • AnyEvent::Twitter::Stream — an excellent module for Twitter Streaming API support. excellent, the manpage said it, not me. 🌈

🫶 SUPPORT 🫶

found a bug? first of all, not me manifesting bugs, but please report bugs at <https://github.com/semifor/net-twitter-lite/issues>.

join the #net-twitter IRC channel on irc.perl.org. come hang, it's giving community. 💜

follow perl_api: <http://twitter.com/perl_api>.

track development at <http://github.com/semifor/net-twitter-lite>. 👑

🌟 AUTHOR 🌟

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

🧚 CONTRIBUTORS 🧚

Marek Foss (@f055)

📜 LICENSE 📜

Copyright (c) 2013 Marc Mims

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

and that's a wrap on the whole page, bestie!! 🎉 you made it through every single section. iconic behavior, no cap. 💖

this was perl v5.34.0, dated 2022-06-16, brought to you by Net::T...APIv1_1(3pm) — the manpage that ate and left no crumbs. now go forth and tweet responsibly. ✨🌸🦋

📦 where this page comes from