Twitter::API::Trait::ApiMethods(3p)

NAME
Twitter::API::Trait::ApiMethods - Convenient API Methods

VERSION
version 1.0006

DESCRIPTION
This trait provides convenient methods for calling API endpoints. They are Net::Twitter compatible, with the same names and calling conventions.

Refer to Twitter's API documentation <https://developer.twitter.com/en/docs/api-reference-index> for details about each method's parameters.

These methods are simply shorthand forms of "get" and "post". All methods can be called with a parameters hashref. It can be omitted for endpoints that do not require any parameters, such as "mentions". For example, all of these calls are equivalent:

    $client->mentions;
    $client->mentions({});
    $client->get('statuses/mentions_timeline');
    $client->get('statuses/mentions_timeline', {});

Use the parameters hashref to pass optional parameters. For example,

    $client->mentions({ count => 200, trim_user=>'true' });

Some methods, with required parameters, can take positional parameters. For example, "geo_id" requires a "place_id" parameter. These calls are equivalent:

    $client->place_id($place);
    $client->place_id({ place_id => $place });

When positional parameters are allowed, they must be specified in the correct order, but they don't all need to be specified. Those not specified positionally can be added to the parameters hashref. For example, these calls are equivalent:

    $client->add_collection_entry($id, $tweet_id);
    $client->add_collection_entry($id, { tweet_id => $tweet_id);
    $client->add_collection_entry({ id => $id, tweet_id => $tweet_id });

Many calls require a "screen_name" or "user_id". Where noted, you may pass either ID as the first positional parameter. Twitter::API will inspect the value. If it contains only digits, it will be considered a "user_id". Otherwise, it will be considered a "screen_name". Best practice is to explicitly declare the ID type by passing it in the parameters hashref, because it is possible to for users to set their screen names to a string of digits, making the inferred ID ambiguous. These calls are equivalent:

   $client->create_block('realDonaldTrump');
   $client->create_block({ screen_name => 'realDonaldTrump' });

Since all of these methods simple resolve to a "get" or "post" call, see the Twitter::API for details about return values and error handling.

METHODS

  account_settings([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-settings>

  blocking([ \%args ])
Aliases: blocks_list

<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list>

  blocking_ids([ \%args ])
Aliases: blocks_ids

<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids>

  collection_entries([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-entries>

  collections([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-list>

  favorites([ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list>

  followers([ \%args ])
Aliases: followers_list

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list>

  followers_ids([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids>

  friends([ \%args ])
Aliases: friends_list

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-list>

  friends_ids([ \%args ])
Aliases: following_ids

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids>

  friendships_incoming([ \%args ])
Aliases: incoming_friendships

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-incoming>

  friendships_outgoing([ \%args ])
Aliases: outgoing_friendships

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-outgoing>

  geo_id([ $place_id, ][ \%args ])
<https://developer.twitter.com/en/docs/geo/place-information/api-reference/get-geo-id-place_id>

  geo_search([ \%args ])
<https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-search>

  get_configuration([ \%args ])
<https://developer.twitter.com/en/docs/developer-utilities/configuration/api-reference/get-help-configuration>

  get_languages([ \%args ])
<https://developer.twitter.com/en/docs/developer-utilities/supported-languages/api-reference/get-help-languages>

  get_list([ \%args ])
Aliases: show_list

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-show>

  get_lists([ \%args ])
Aliases: list_lists, all_subscriptions

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list>

  get_privacy_policy([ \%args ])
<https://developer.twitter.com/en/docs/developer-utilities/privacy-policy/api-reference/get-help-privacy>

  get_tos([ \%args ])
<https://developer.twitter.com/en/docs/developer-utilities/terms-of-service/api-reference/get-help-tos>

  home_timeline([ \%args ])
<https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline>

  list_members([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members>

  list_memberships([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships>

  list_ownerships([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships>

  list_statuses([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses>

  list_subscribers([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers>

  list_subscriptions([ \%args ])
Aliases: subscriptions

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions>

  lookup_friendships([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup>

  lookup_statuses([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-lookup>

  lookup_users([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup>

  mentions([ \%args ])
Aliases: replies, mentions_timeline

<https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline>

  mutes([ \%args ])
Aliases: muting_ids, muted_ids

<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids>

  muting([ \%args ])
Aliases: mutes_list

<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list>

  no_retweet_ids([ \%args ])
Aliases: no_retweets_ids

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-no_retweets-ids>

  oembed([ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-oembed>

  profile_banner([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-users-profile_banner>

  rate_limit_status([ \%args ])
<https://developer.twitter.com/en/docs/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status>

  retweeters_ids([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids>

  retweets([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets-id>

  retweets_of_me([ \%args ])
Aliases: retweeted_of_me

<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me>

  reverse_geocode([ $lat, [ $long, ]][ \%args ])
<https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-reverse_geocode>

  saved_searches([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-list>

  search([ $q, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets>

  sent_direct_messages([ \%args ])
Aliases: direct_messages_sent

<https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-sent-message>

  show_friendship([ \%args ])
Aliases: show_relationship

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-show>

  show_list_member([ \%args ])
Aliases: is_list_member

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members-show>

  show_list_subscriber([ \%args ])
Aliases: is_list_subscriber, is_subscriber_lists

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers-show>

  show_saved_search([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-show-id>

  show_status([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id>

  show_user([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-show>

  suggestion_categories([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions>

  trends_available([ \%args ])
<https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available>

  trends_closest([ \%args ])
<https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest>

  trends_place([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place>

  user_suggestions([ $slug, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug-members>

  user_suggestions_for([ $slug, ][ \%args ])
Aliases: follow_suggestions

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug>

  user_timeline([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline>

  users_search([ $q, ][ \%args ])
Aliases: find_people, search_users

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search>

  verify_credentials([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials>

  add_collection_entry([ $id, [ $tweet_id, ]][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-add>

  add_list_member([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create>

  create_block([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create>

  create_collection([ $name, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-create>

  create_favorite([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-create>

  create_friend([ $screen_name | $user_id, ][ \%args ])
Aliases: follow, follow_new, create_friendship

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create>

  create_list([ $name, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-create>

  create_media_metadata([ \%args ])
<https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-metadata-create>

  create_mute([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create>

Alias: mute

  create_saved_search([ $query, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-create>

  curate_collection([ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-curate>

  delete_list([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy>

  delete_list_member([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy>

  destroy_block([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy>

  destroy_collection([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-destroy>

  destroy_favorite([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-destroy>

  destroy_friend([ $screen_name | $user_id, ][ \%args ])
Aliases: unfollow, destroy_friendship

<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy>

  destroy_mute([ $screen_name | $user_id, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy>

Alias: unmute

  destroy_saved_search([ $id, ][ \%args ])
Aliases: delete_saved_search

<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-destroy-id>

  destroy_status([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-destroy-id>

  members_create_all([ \%args ])
Aliases: add_list_members

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create_all>

  members_destroy_all([ \%args ])
Aliases: remove_list_members

<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy_all>

  move_collection_entry([ $id, [ $tweet_id, [ $relative_to, ]]][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-move>

  remove_collection_entry([ $id, [ $tweet_id, ]][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-remove>

  remove_profile_banner([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-remove_profile_banner>

  report_spam([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-users-report_spam>

  retweet([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id>

  subscribe_list([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-create>

  unretweet([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-unretweet-id>

  unsubscribe_list([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-destroy>

  update([ $status, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update>

  update_account_settings([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-settings>

  update_collection([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-update>

  update_friendship([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update>

  update_list([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-update>

  update_profile([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile>

  update_profile_background_image([ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_background_image>

  update_profile_banner([ $banner, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_banner>

  update_profile_image([ $image, ][ \%args ])
<https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image>

  upload_media([ $media, ][ \%args ])
Aliases: upload

<https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload>

  direct_messages_events([ \%args ])
<https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events.html>

  show_direct_messages_event([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event>

  destroy_direct_messages_event([ $id, ][ \%args ])
<https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message-event>

  new_direct_messages_event([$text, $recipient_id ] | [ \%event ], [ \%args ])
For simple usage, pass text and recipient ID:

    $client->new_dirrect_messages_event($text, $recipient_id)

For more complex messages, pass a full event structure, for example:

    $client->new_direct_massages_event({
        type => 'message_create',
        message_create => {
            target => { recipient_id => $user_id },
            message_data => {
                text => $text,
                attachment => {
                    type  => 'media',
                    media => { id => $media->{id} },
                },
            },
        },
    })

<https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-message>

  invalidate_access_token([ \%args ])
Calling this method has the same effect as a user revoking access to the application via Twitter settings. The access token/secret pair will no longer be valid.

This method can be called with client that has been initialized with "access_token" and "access_token_secret" attributes, by passing "-token" and "-token_secret" parameters, or by passing "access_token" and "access_token_secret" parameters.

    $client->invalidate_access_token;
    $client->invalidate_access_token({ -token => $token, -token_secret => $secret });
    $client->invalidate_access_token({
        access_token        => $token,
        access_token_secret => $secret,
    });

Twitter added this method to the API on 2018-09-20.

See <https://developer.twitter.com/en/docs/basics/authentication/api-reference/invalidate_access_token>

AUTHOR
Marc Mims <marc@questright.com>

COPYRIGHT AND LICENSE
This software is copyright (c) 2015-2021 by Marc Mims.

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