1NAME 2 3 Net::Twitter::Lite - A perl interface to the Twitter API 4 5VERSION 6 7 version 0.12008 8 9STOP! 10 11 You probably want Net::Twitter::Lite::WithAPIv1_1 which has support for 12 Twitter API v1.1. If you're using a service with an API compatible with 13 Twitter's deprecated API v1, then you're in the right place. 14 15SYNOPSIS 16 17 use Net::Twitter::Lite; 18 19 my $nt = Net::Twitter::Lite->new( 20 username => $user, 21 password => $password 22 legacy_lists_api => 0, 23 ); 24 25 my $result = eval { $nt->update('Hello, world!') }; 26 27 eval { 28 my $statuses = $nt->friends_timeline({ since_id => $high_water, count => 100 }); 29 for my $status ( @$statuses ) { 30 print "$status->{created_at} <$status->{user}{screen_name}> $status->{text}\n"; 31 } 32 }; 33 warn "$@\n" if $@; 34 35DESCRIPTION 36 37 This module provides a perl interface to the Twitter API v1. 38 39 It uses the same API definitions as Net::Twitter, but without the extra 40 bells and whistles and without the additional dependencies. Same great 41 taste, less filling. 42 43 This module is related to, but is not part of the Net::Twitter 44 distribution. It's API methods and API method documentation are 45 generated from Net::Twitter's internals. It exists for those who 46 cannot, or prefer not to install Moose and its dependencies. 47 48 You should consider upgrading to Net::Twitter for additional 49 functionality, finer grained control over features, backwards 50 compatibility with older versions of Net::Twitter, and additional error 51 handling options. 52 53CLIENT CODE CHANGES REQUIRED 54 55 Legacy Lists API 56 57 Twitter re-implemented the Lists API using new endpoints and semantics. 58 For backwards compatibility, this version of Net::Twitter::Lite 59 defaults to the deprecated, legacy endpoints and semantics. It issues a 60 warning if the legacy_lists_api option to new is not provided. 61 62 To enable the new Lists endpoints and semantics, pass (legacy_lists_api 63 = 0)> to new. To disable the warning, and keep the backwards compatible 64 endpoints and semantics, pass (legacy_lists_api = 1)> to new. 65 66 The legacy_lists_api option to new sets the default for all lists API 67 method calls. You can override the default an each API call by passing 68 a -legacy_lists_api option set to 1 or 0. 69 70 Support for legacy_lists_api option will be removed in a future version 71 and the option to new will be silently ignored. 72 73 netrc option 74 75 The default apiurl changed in version 0.08006. The change should be 76 transparent to client code, unless you're using the netrc option. If 77 so, you'll need to either update the .netrc entry and change the 78 machine value from twitter.com to api.twitter.com, or set either the 79 netrc or netrc_machine options to twitter.com. 80 81 $nt = Net::Twitter::Lite->new(netrc_machine => 'twitter.com', netrc => 1); 82 # -or- 83 $nt = Net::Twitter::Lite->new(netrc => 'twitter.com'); 84 85 OAuth requires callback parameter 86 87 Beginning with version 0.03, it is necessary for web applications using 88 OAuth authentication to pass the callback parameter to 89 get_authorization_url. In the absence of a callback parameter, when the 90 user authorizes the application a PIN number is displayed rather than 91 redirecting the user back to your site. 92 93MIGRATING FROM NET::TWITTER 2.x 94 95 If you are migrating from Net::Twitter 2.12 (or an earlier version), 96 you may need to make some minor changes to your application code in 97 order to user Net::Twitter::Lite successfully. 98 99 The primary difference is in error handling. Net::Twitter::Lite throws 100 exceptions on error. It does not support the get_error, http_code, and 101 http_message methods used in Net::Twitter 2.12 and prior versions. 102 103 Instead of 104 105 # DON'T! 106 my $friends = $nt->friends(); 107 if ( $friends ) { 108 # process $friends 109 } 110 111 wrap the API call in an eval block: 112 113 # DO! 114 my $friends = eval { $nt->friends() }; 115 if ( $friends ) { 116 # process $friends 117 } 118 119 Here's a much more complex example taken from application code using 120 Net::Twitter 2.12: 121 122 # DON'T! 123 my $friends = $nt->friends(); 124 if ( $friends ) { 125 # process $friends 126 } 127 else { 128 my $error = $nt->get_error; 129 if ( ref $error ) { 130 if ( ref($error) eq 'HASH' && exists $error->{error} ) { 131 $error = $error->{error}; 132 } 133 else { 134 $error = 'Unexpected error type ' . ref($error); 135 } 136 } 137 else { 138 $error = $nt->http_code() . ": " . $nt->http_message; 139 } 140 warn "$error\n"; 141 } 142 143 The Net::Twitter::Lite equivalent is: 144 145 # DO! 146 eval { 147 my $friends = $nt->friends(); 148 # process $friends 149 }; 150 warn "$@\n" if $@; 151 return; 152 153 In Net::Twitter::Lite, an error can always be treated as a string. See 154 Net::Twitter::Lite::Error. The HTTP Status Code and HTTP Message are 155 both available. Rather than accessing them via the Net::Twitter::Lite 156 instance, you access them via the Net::Twitter::Lite::Error instance 157 thrown as an error. 158 159 For example: 160 161 # DO! 162 eval { 163 my $friends = $nt->friends(); 164 # process $friends 165 }; 166 if ( my $error = $@ ) { 167 if ( blessed $error && $error->isa("Net::Twitter::Lite::Error) 168 && $error->code() == 502 ) { 169 $error = "Fail Whale!"; 170 } 171 warn "$error\n"; 172 } 173 174 Unsupported Net::Twitter 2.12 options to new 175 176 Net::Twitter::Lite does not support the following Net::Twitter 2.12 177 options to new. It silently ignores them: 178 179 no_fallback 180 181 If Net::Twitter::Lite is unable to create an instance of the class 182 specified in the useragent_class option to new, it dies, rather than 183 falling back to an LWP::UserAgent object. You really don't want a 184 failure to create the useragent_class you specified to go unnoticed. 185 186 twittervision 187 188 Net::Twitter::Lite does not support the TwitterVision API. Use 189 Net::Twitter, instead, if you need it. 190 191 skip_arg_validation 192 193 Net::Twitter::Lite does not API parameter validation. This is a 194 feature. If Twitter adds a new option to an API method, you can use 195 it immediately by passing it in the HASH ref to the API call. 196 197 Net::Twitter::Lite relies on Twitter to validate its own parameters. 198 An appropriate exception will be thrown if Twitter reports a 199 parameter error. 200 201 die_on_validation 202 203 See "skip_arg_validation". If Twitter returns an bad parameter error, 204 an appropriate exception will be thrown. 205 206 arrayref_on_error 207 208 This option allowed the following idiom in Net::Twitter 2.12: 209 210 # DON'T! 211 for my $friend ( @{ $nt->friends() } ) { 212 # process $friend 213 } 214 215 The equivalent Net::Twitter::Lite code is: 216 217 # DO! 218 eval { 219 for my $friend ( @{ $nt->friends() } ) { 220 # process $friend 221 } 222 }; 223 224 Unsupported Net::Twitter 2.12 methods 225 226 clone 227 228 The clone method was added to Net::Twitter 2.x to allow safe error 229 handling in an environment where concurrent requests are handled, for 230 example, when using LWP::UserAgent::POE as the useragent_class. Since 231 Net::Twitter::Lite throws exceptions instead of stashing them in the 232 Net::Twitter::Lite instance, it is safe in a current request 233 environment, obviating the need for clone. 234 235 get_error 236 237 http_code 238 239 http_message 240 241 These methods are replaced by Net::Twitter::Lite::Error. An instance 242 of that class is thrown errors are encountered. 243 244METHODS AND ARGUMENTS 245 246 new 247 248 This constructs a Net::Twitter::Lite object. It takes several named 249 parameters, all of them optional: 250 251 username 252 253 This is the screen name or email used to authenticate with Twitter. 254 Use this option for Basic Authentication, only. 255 256 password 257 258 This is the password used to authenticate with Twitter. Use this 259 option for Basic Authentication, only. 260 261 consumer_key 262 263 A string containing the OAuth consumer key provided by Twitter when 264 an application is registered. Use this option for OAuth 265 authentication, only. 266 267 consumer_secret 268 269 A string containing the OAuth consumer secret. Use this option for 270 OAuth authentication, only. the OAuth trait is included. 271 272 oauth_urls 273 274 A HASH ref of URLs to be used with OAuth authentication. Defaults 275 to: 276 277 { 278 request_token_url => "http://twitter.com/oauth/request_token", 279 authorization_url => "http://twitter.com/oauth/authorize", 280 access_token_url => "http://twitter.com/oauth/access_token", 281 xauth_url => "https://twitter.com/oauth/access_token", 282 } 283 284 clientname 285 286 The value for the X-Twitter-Client-Name HTTP header. It defaults to 287 "Perl Net::Twitter::Lite". 288 289 clientver 290 291 The value for the X-Twitter-Client-Version HTTP header. It defaults 292 to current version of the Net::Twitter::Lite module. 293 294 clienturl 295 296 The value for the X-Twitter-Client-URL HTTP header. It defaults to 297 the search.cpan.org page for the Net::Twitter::Lite distribution. 298 299 useragent_class 300 301 The LWP::UserAgent compatible class used internally by 302 Net::Twitter::Lite. It defaults to "LWP::UserAgent". For POE based 303 applications, consider using "LWP::UserAgent::POE". 304 305 useragent_args 306 307 An HASH ref of arguments to pass to constructor of the class 308 specified with useragent_class, above. It defaults to {} (an empty 309 HASH ref). 310 311 useragent 312 313 The value for User-Agent HTTP header. It defaults to 314 "Net::Twitter::Lite/0.11002 (Perl)". 315 316 source 317 318 The value used in the source parameter of API method calls. It is 319 currently only used in the update method in the REST API. It 320 defaults to "twitterpm". This results in the text "from 321 Net::Twitter" rather than "from web" for status messages posted 322 from Net::Twitter::Lite when displayed via the Twitter web 323 interface. The value for this parameter is provided by Twitter when 324 a Twitter application is registered. See 325 http://apiwiki.twitter.com/FAQ#HowdoIget%E2%80%9CfromMyApp%E2%80%9DappendedtoupdatessentfrommyAPIapplication. 326 327 apiurl 328 329 The URL for the Twitter API. This defaults to "http://twitter.com". 330 331 identica 332 333 If set to 1 (or any value that evaluates to true), apiurl defaults 334 to "http://identi.ca/api". 335 336 ssl 337 338 If set to 1, an SSL connection will be used for all API calls. 339 Defaults to 0. 340 341 netrc 342 343 (Optional) Sets the machine key to look up in .netrc to obtain 344 credentials. If set to 1, Net::Twitter::Lite will use the value of 345 the netrc_machine option (below). 346 347 # in .netrc 348 machine api.twitter.com 349 login YOUR_TWITTER_USER_NAME 350 password YOUR_TWITTER_PASSWORD 351 machine semifor.twitter.com 352 login semifor 353 password SUPERSECRET 354 355 # in your perl program 356 $nt = Net::Twitter::Lite->new(netrc => 1); 357 $nt = Net::Twitter::Lite->new(netrc => 'semifor.twitter.com'); 358 359 netrc_machine 360 361 (Optional) Sets the machine entry to look up in .netrc when <netrc 362 = 1>> is used. Defaults to api.twitter.com. 363 364 legacy_lists_api 365 366 If set to 1, this option enables backwards compatibility by using 367 the now deprecated endpoints and semantics for lists API methods. 368 If set to 0, the new endpoints and semantics will be used. Only the 369 new lists API methods are documented here. 370 371 If you do not provide this option to new a warning is issued. 372 Support for this option and the legacy lists API methods will be 373 removed in a future version. 374 375 wrap_result 376 377 (Optional) If set to 1, this option will return an 378 Net::Twitter::Lite::WrapResult object, which provides both the 379 Twitter API result and the HTTP::Response object for the API call. 380 See Net::Twitter::Lite::WrapResult for details. 381 382 BASIC AUTHENTICATION METHODS 383 384 credentials($username, $password) 385 386 Set the credentials for Basic Authentication. This is helpful for 387 managing multiple accounts. 388 389 OAUTH METHODS 390 391 authorized 392 393 Whether the client has the necessary credentials to be authorized. 394 395 Note that the credentials may be wrong and so the request may fail. 396 397 request_access_token 398 399 Returns list including the access token, access token secret, 400 user_id, and screen_name for this user. Takes a HASH of arguments. 401 The verifier argument is required. See "OAUTH EXAMPLES". 402 403 The user must have authorized this app at the url given by 404 get_authorization_url first. 405 406 For desktop applications, the Twitter authorization page will present 407 the user with a PIN number. Prompt the user for the PIN number, and 408 pass it as the verifier argument to request_access_token. 409 410 Returns the access token and access token secret but also sets them 411 internally so that after calling this method, you can immediately 412 call API methods requiring authentication. 413 414 get_authorization_url(callback => $callback_url) 415 416 Get the URL used to authorize the user. Returns a URI object. For web 417 applications, pass your applications callback URL as the callback 418 parameter. No arguments are required for desktop applications 419 (callback defaults to oob, out-of-band). 420 421 get_authentication_url(callback => $callback_url) 422 423 Get the URL used to authenticate the user with "Sign in with Twitter" 424 authentication flow. Returns a URI object. For web applications, pass 425 your applications callback URL as the callback parameter. No 426 arguments are required for desktop applications (callback defaults to 427 oob, out-of-band). 428 429 xauth($username, $password) 430 431 Exchanges a username and password for OAuth tokens. Your application 432 must be approved for XAuth access by Twitter for this method to work. 433 Twitter does not grant XAuth access for web applications except for a 434 brief period of time to allow them to switch form Basic 435 authentication to OAuth authentication. 436 437 access_token 438 439 Get or set the access token. 440 441 access_token_secret 442 443 Get or set the access token secret. 444 445 request_token 446 447 Get or set the request token. 448 449 request_token_secret 450 451 Get or set the request token secret. 452 453 access_token_url 454 455 Get or set the access_token URL. 456 457 authentication_url 458 459 Get or set the authentication URL. 460 461 authorization_url 462 463 Get or set the authorization URL. 464 465 request_token_url 466 467 Get or set the request_token URL. 468 469 xauth_url 470 471 Get or set the XAuth access token request URL. 472 473API METHODS AND ARGUMENTS 474 475 Most Twitter API methods take parameters. All Net::Twitter::Lite API 476 methods will accept a HASH ref of named parameters as specified in the 477 Twitter API documentation. For convenience, many Net::Twitter::Lite 478 methods accept simple positional arguments as documented, below. The 479 positional parameter passing style is optional; you can always use the 480 named parameters in a hash ref if you prefer. 481 482 For example, the REST API method update has one required parameter, 483 status. You can call update with a HASH ref argument: 484 485 $nt->update({ status => 'Hello world!' }); 486 487 Or, you can use the convenient form: 488 489 $nt->update('Hello world!'); 490 491 The update method also has an optional parameter, 492 in_reply_to_status_id. To use it, you must use the HASH ref form: 493 494 $nt->update({ status => 'Hello world!', in_reply_to_status_id => $reply_to }); 495 496 Convenience form is provided for the required parameters of all API 497 methods. So, these two calls are equivalent: 498 499 $nt->friendship_exists({ user_a => $fred, user_b => $barney }); 500 $nt->friendship_exists($fred, $barney); 501 502 Many API methods have aliases. You can use the API method name, or any 503 of its aliases, as you prefer. For example, these calls are all 504 equivalent: 505 506 $nt->friendship_exists($fred, $barney); 507 $nt->relationship_exists($fred, $barney); 508 $nt->follows($fred, $barney); 509 510 Aliases support both the HASH ref and convenient forms: 511 512 $nt->follows({ user_a => $fred, user_b => $barney }); 513 514 Methods that support the page parameter expect page numbers > 0. 515 Twitter silently ignores invalid page values. So { page => 0 } produces 516 the same result as { page => 1 }. 517 518 In addition to the arguments specified for each API method described 519 below, an additional authenticate parameter can be passed. To request 520 an Authorization header, pass authenticated => 1; to suppress an 521 authentication header, pass authentication => 0. Even if requested, an 522 Authorization header will not be added if there are no user credentials 523 (username and password for Basic Authentication; access tokens for 524 OAuth). 525 526 This is probably only useful for the "rate_limit_status" method in the 527 REST API, since it returns different values for an authenticated and a 528 non-authenticated call. 529 530REST API Methods 531 532 Several of these methods accept a user ID as the id parameter. The user 533 ID can be either a screen name, or the users numeric ID. To 534 disambiguate, use the screen_name or user_id parameters, instead. 535 536 For example, These calls are equivalent: 537 538 $nt->create_friend('perl_api'); # screen name 539 $nt->create_friend(1564061); # numeric ID 540 $nt->create_friend({ id => 'perl_api' }); 541 $nt->create_friend({ screen_name => 'perl_api' }); 542 $nt->create_friend({ user_id => 1564061 }); 543 544 However user_id 911 and screen_name 911 are separate Twitter accounts. 545 These calls are NOT equivalent: 546 547 $nt->create_friend(911); # interpreted as screen name 548 $nt->create_friend({ user_id => 911 }); # screen name: richellis 549 550 Whenever the id parameter is required and user_id and screen_name are 551 also parameters, using any one of them satisfies the requirement. 552 553 account_settings 554 555 Parameters: none 556 557 Required: none 558 559 Returns the current trend, geo and sleep time information for the 560 authenticating user. 561 562 Returns: HashRef 563 564 account_totals 565 566 Parameters: none 567 568 Required: none 569 570 Returns the current count of friends, followers, updates (statuses) 571 and favorites of the authenticating user. 572 573 Returns: HashRef 574 575 add_list_member 576 577 Parameters: list_id, slug, user_id, screen_name, owner_screen_name, 578 owner_id 579 580 Required: none 581 582 Add a member to a list. The authenticated user must own the list to 583 be able to add members to it. Note that lists can't have more than 584 500 members. 585 586 Returns: User 587 588 add_place 589 590 add_place(name, contained_within, token, lat, long) 591 592 Parameters: name, contained_within, token, lat, long, 593 attribute:street_address, callback 594 595 Required: name, contained_within, token, lat, long 596 597 Creates a new place object at the given latitude and longitude. 598 599 Before creating a place you need to query similar_places with the 600 latitude, longitude and name of the place you wish to create. The 601 query will return an array of places which are similar to the one you 602 wish to create, and a token. If the place you wish to create isn't in 603 the returned array you can use the token with this method to create a 604 new one. 605 606 Returns: Place 607 608 all_subscriptions 609 610 alias: all_lists 611 612 alias: list_subscriptions 613 614 Parameters: user_id, screen_name, count, cursor 615 616 Required: none 617 618 Returns all lists the authenticating or specified user subscribes to, 619 including their own. The user is specified using the user_id or 620 screen_name parameters. If no user is given, the authenticating user 621 is used. 622 623 Returns: ArrayRef[List] 624 625 block_exists 626 627 block_exists(id) 628 629 Parameters: id, user_id, screen_name, include_entities 630 631 Required: id 632 633 Returns if the authenticating user is blocking a target user. Will 634 return the blocked user's object if a block exists, and error with 635 HTTP 404 response code otherwise. 636 637 Returns: BasicUser 638 639 blocking 640 641 Parameters: page, include_entities 642 643 Required: none 644 645 Returns an array of user objects that the authenticating user is 646 blocking. 647 648 Returns: ArrayRef[BasicUser] 649 650 blocking_ids 651 652 Parameters: none 653 654 Required: none 655 656 Returns an array of numeric user ids the authenticating user is 657 blocking. 658 659 Returns: ArrayRef[Int] 660 661 contributees 662 663 Parameters: user_id, screen_name, include_entities, skip_satus 664 665 Required: none 666 667 Returns an array of users that the specified user can contribute to. 668 669 Returns: ArrayRef[User] 670 671 contributors 672 673 Parameters: user_id, screen_name, include_entities, skip_satus 674 675 Required: none 676 677 Returns an array of users who can contribute to the specified 678 account. 679 680 Returns: ArrayRef[User] 681 682 create_block 683 684 create_block(id) 685 686 Parameters: id, user_id, screen_name, include_entities 687 688 Required: id 689 690 Blocks the user specified in the ID parameter as the authenticating 691 user. Returns the blocked user when successful. You can find out more 692 about blocking in the Twitter Support Knowledge Base. 693 694 Returns: BasicUser 695 696 create_favorite 697 698 create_favorite(id) 699 700 Parameters: id, include_entities 701 702 Required: id 703 704 Favorites the status specified in the ID parameter as the 705 authenticating user. Returns the favorite status when successful. 706 707 Returns: Status 708 709 create_friend 710 711 create_friend(id) 712 713 alias: follow_new 714 715 Parameters: id, user_id, screen_name, follow, include_entities 716 717 Required: id 718 719 Befriends the user specified in the ID parameter as the 720 authenticating user. Returns the befriended user when successful. 721 Returns a string describing the failure condition when unsuccessful. 722 723 Returns: BasicUser 724 725 create_list 726 727 Parameters: list_id, slug, name, mode, description, 728 owner_screen_name, owner_id 729 730 Required: none 731 732 Creates a new list for the authenticated user. Note that you can't 733 create more than 20 lists per account. 734 735 Returns: List 736 737 create_saved_search 738 739 create_saved_search(query) 740 741 Parameters: query 742 743 Required: query 744 745 Creates a saved search for the authenticated user. 746 747 Returns: SavedSearch 748 749 delete_list 750 751 Parameters: owner_screen_name, owner_id, list_id, slug 752 753 Required: none 754 755 Deletes the specified list. The authenticated user must own the list 756 to be able to destroy it. 757 758 Returns: List 759 760 delete_list_member 761 762 alias: remove_list_member 763 764 Parameters: list_id, slug, user_id, screen_name, owner_screen_name, 765 owner_id 766 767 Required: none 768 769 Removes the specified member from the list. The authenticated user 770 must be the list's owner to remove members from the list. 771 772 Returns: User 773 774 destroy_block 775 776 destroy_block(id) 777 778 Parameters: id, user_id, screen_name 779 780 Required: id 781 782 Un-blocks the user specified in the ID parameter as the 783 authenticating user. Returns the un-blocked user when successful. 784 785 Returns: BasicUser 786 787 destroy_direct_message 788 789 destroy_direct_message(id) 790 791 Parameters: id, include_entities 792 793 Required: id 794 795 Destroys the direct message specified in the required ID parameter. 796 The authenticating user must be the recipient of the specified direct 797 message. 798 799 Returns: DirectMessage 800 801 destroy_favorite 802 803 destroy_favorite(id) 804 805 Parameters: id, include_entities 806 807 Required: id 808 809 Un-favorites the status specified in the ID parameter as the 810 authenticating user. Returns the un-favorited status. 811 812 Returns: Status 813 814 destroy_friend 815 816 destroy_friend(id) 817 818 alias: unfollow 819 820 Parameters: id, user_id, screen_name, include_entities 821 822 Required: id 823 824 Discontinues friendship with the user specified in the ID parameter 825 as the authenticating user. Returns the un-friended user when 826 successful. Returns a string describing the failure condition when 827 unsuccessful. 828 829 Returns: BasicUser 830 831 destroy_saved_search 832 833 destroy_saved_search(id) 834 835 Parameters: id 836 837 Required: id 838 839 Destroys a saved search. The search, specified by id, must be owned 840 by the authenticating user. 841 842 Returns: SavedSearch 843 844 destroy_status 845 846 destroy_status(id) 847 848 Parameters: id, trim_user, include_entities 849 850 Required: id 851 852 Destroys the status specified by the required ID parameter. The 853 authenticating user must be the author of the specified status. 854 855 Returns: Status 856 857 direct_messages 858 859 direct_messages(include_entities) 860 861 Parameters: since_id, max_id, count, page, include_entities 862 863 Required: include_entities 864 865 Returns a list of the 20 most recent direct messages sent to the 866 authenticating user including detailed information about the sending 867 and recipient users. 868 869 Returns: ArrayRef[DirectMessage] 870 871 disable_notifications 872 873 disable_notifications(id) 874 875 Parameters: id, screen_name, include_entities 876 877 Required: id 878 879 Disables notifications for updates from the specified user to the 880 authenticating user. Returns the specified user when successful. 881 882 Returns: BasicUser 883 884 enable_notifications 885 886 enable_notifications(id) 887 888 Parameters: id, screen_name, include_entities 889 890 Required: id 891 892 Enables notifications for updates from the specified user to the 893 authenticating user. Returns the specified user when successful. 894 895 Returns: BasicUser 896 897 end_session 898 899 Parameters: none 900 901 Required: none 902 903 Ends the session of the authenticating user, returning a null cookie. 904 Use this method to sign users out of client-facing applications like 905 widgets. 906 907 Returns: Error 908 909 favorites 910 911 Parameters: id, page, include_entities 912 913 Required: none 914 915 Returns the 20 most recent favorite statuses for the authenticating 916 user or user specified by the ID parameter. 917 918 Returns: ArrayRef[Status] 919 920 followers_ids 921 922 followers_ids(id) 923 924 Parameters: id, user_id, screen_name, cursor 925 926 Required: id 927 928 Returns a reference to an array of numeric IDs for every user 929 following the specified user. The order of the IDs may change from 930 call to call. To obtain the screen names, pass the arrayref to 931 "lookup_users". 932 933 Use the optional cursor parameter to retrieve IDs in pages of 5000. 934 When the cursor parameter is used, the return value is a reference to 935 a hash with keys previous_cursor, next_cursor, and ids. The value of 936 ids is a reference to an array of IDS of the user's followers. Set 937 the optional cursor parameter to -1 to get the first page of IDs. Set 938 it to the prior return's value of previous_cursor or next_cursor to 939 page forward or backwards. When there are no prior pages, the value 940 of previous_cursor will be 0. When there are no subsequent pages, the 941 value of next_cursor will be 0. 942 943 Returns: HashRef|ArrayRef[Int] 944 945 friends_ids 946 947 friends_ids(id) 948 949 alias: following_ids 950 951 Parameters: id, user_id, screen_name, cursor 952 953 Required: id 954 955 Returns a reference to an array of numeric IDs for every user 956 followed by the specified user. The order of the IDs is reverse 957 chronological. 958 959 Use the optional cursor parameter to retrieve IDs in pages of 5000. 960 When the cursor parameter is used, the return value is a reference to 961 a hash with keys previous_cursor, next_cursor, and ids. The value of 962 ids is a reference to an array of IDS of the user's friends. Set the 963 optional cursor parameter to -1 to get the first page of IDs. Set it 964 to the prior return's value of previous_cursor or next_cursor to page 965 forward or backwards. When there are no prior pages, the value of 966 previous_cursor will be 0. When there are no subsequent pages, the 967 value of next_cursor will be 0. 968 969 Returns: HashRef|ArrayRef[Int] 970 971 friendship_exists 972 973 friendship_exists(user_a, user_b) 974 975 alias: relationship_exists 976 977 alias: follows 978 979 Parameters: user_id_a, user_id_b, screen_name_a, screen_name_b, 980 user_a, user_b 981 982 Required: user_a, user_b 983 984 Tests for the existence of friendship between two users. Will return 985 true if user_a follows user_b, otherwise will return false. 986 987 Use of user_a and user_b is deprecated. It has been preserved for 988 backwards compatibility, and is used for the two-argument positional 989 form: 990 991 $nt->friendship_exists($user_a, $user_b); 992 993 Instead, you should use one of the named argument forms: 994 995 $nt->friendship_exists({ user_id_a => $id1, user_id_b => $id2 }); 996 $nt->friendship_exists({ screen_name_a => $name1, screen_name_b => $name2 }); 997 998 Consider using show_friendship instead. 999 1000 Returns: Bool 1001 1002 friendships_incoming 1003 1004 friendships_incoming(cursor) 1005 1006 Parameters: cursor 1007 1008 Required: cursor 1009 1010 Returns an HASH ref with an array of numeric IDs in the ids element 1011 for every user who has a pending request to follow the authenticating 1012 user. 1013 1014 Returns: HashRef 1015 1016 friendships_outgoing 1017 1018 friendships_outgoing(cursor) 1019 1020 Parameters: cursor 1021 1022 Required: cursor 1023 1024 Returns an HASH ref with an array of numeric IDs in the ids element 1025 for every protected user for whom the authenticating user has a 1026 pending follow request. 1027 1028 Returns: HashRef 1029 1030 geo_id 1031 1032 geo_id(id) 1033 1034 Parameters: id 1035 1036 Required: id 1037 1038 Returns details of a place returned from the reverse_geocode method. 1039 1040 Returns: HashRef 1041 1042 geo_search 1043 1044 Parameters: lat, long, query, ip, granularity, accuracy, max_results, 1045 contained_within, attribute:street_address, callback 1046 1047 Required: none 1048 1049 Search for places that can be attached to a statuses/update. Given a 1050 latitude and a longitude pair, an IP address, or a name, this request 1051 will return a list of all the valid places that can be used as the 1052 place_id when updating a status. 1053 1054 Conceptually, a query can be made from the user's location, retrieve 1055 a list of places, have the user validate the location he or she is 1056 at, and then send the ID of this location with a call to 1057 statuses/update. 1058 1059 This is the recommended method to use find places that can be 1060 attached to statuses/update. Unlike geo/reverse_geocode which 1061 provides raw data access, this endpoint can potentially re-order 1062 places with regards to the user who is authenticated. This approach 1063 is also preferred for interactive place matching with the user. 1064 1065 Returns: HashRef 1066 1067 get_configuration 1068 1069 Parameters: none 1070 1071 Required: none 1072 1073 Returns the current configuration used by Twitter including 1074 twitter.com slugs which are not usernames, maximum photo resolutions, 1075 and t.co URL lengths. 1076 1077 It is recommended applications request this endpoint when they are 1078 loaded, but no more than once a day. 1079 1080 Returns: HashRef 1081 1082 get_languages 1083 1084 Parameters: none 1085 1086 Required: none 1087 1088 Returns the list of languages supported by Twitter along with their 1089 ISO 639-1 code. The ISO 639-1 code is the two letter value to use if 1090 you include lang with any of your requests. 1091 1092 Returns: ArrayRef[Lanugage] 1093 1094 get_list 1095 1096 Parameters: list_id, slug, owner_screen_name, owner_id 1097 1098 Required: none 1099 1100 Returns the specified list. Private lists will only be shown if the 1101 authenticated user owns the specified list. 1102 1103 Returns: List 1104 1105 get_lists 1106 1107 alias: list_lists 1108 1109 Parameters: user_id, screen_name, cursor 1110 1111 Required: none 1112 1113 Returns the lists of the specified (or authenticated) user. Private 1114 lists will be included if the authenticated user is the same as the 1115 user whose lists are being returned. 1116 1117 Returns: Hashref 1118 1119 get_privacy_policy 1120 1121 Parameters: none 1122 1123 Required: none 1124 1125 Returns Twitter's privacy policy. 1126 1127 Returns: HashRef 1128 1129 get_tos 1130 1131 Parameters: none 1132 1133 Required: none 1134 1135 Returns the Twitter Terms of Service. These are not the same as the 1136 Developer Rules of the Road. 1137 1138 Returns: HashRef 1139 1140 home_timeline 1141 1142 Parameters: since_id, max_id, count, page, skip_user, 1143 exclude_replies, contributor_details, include_rts, include_entities, 1144 trim_user, include_my_retweet 1145 1146 Required: none 1147 1148 Returns the 20 most recent statuses, including retweets, posted by 1149 the authenticating user and that user's friends. This is the 1150 equivalent of /timeline/home on the Web. 1151 1152 Returns: ArrayRef[Status] 1153 1154 is_list_member 1155 1156 Parameters: owner_screen_name, owner_id, list_id, slug, user_id, 1157 screen_name, include_entities, skip_status 1158 1159 Required: none 1160 1161 Check if the specified user is a member of the specified list. 1162 Returns the user or undef. 1163 1164 Returns: Maybe[User] 1165 1166 is_list_subscriber 1167 1168 alias: is_subscribed_list 1169 1170 Parameters: owner_screen_name, owner_id, list_id, slug, user_id, 1171 screen_name, include_entities, skip_status 1172 1173 Required: none 1174 1175 Check if the specified user is a subscriber of the specified list. 1176 Returns the user or undef. 1177 1178 Returns: Maybe[User] 1179 1180 list_members 1181 1182 Parameters: list_id, slug, owner_screen_name, owner_id, cursor, 1183 include_entities, skip_status 1184 1185 Required: none 1186 1187 Returns the members of the specified list. Private list members will 1188 only be shown if the authenticated user owns the specified list. 1189 1190 Returns: Hashref 1191 1192 list_memberships 1193 1194 Parameters: user_id, screen_name, cursor, filter_to_owned_lists 1195 1196 Required: none 1197 1198 Returns the lists the specified user has been added to. If user_id or 1199 screen_name are not provided the memberships for the authenticating 1200 user are returned. 1201 1202 Returns: Hashref 1203 1204 list_statuses 1205 1206 Parameters: list_id, slug, owner_screen_name, owner_id, since_id, 1207 max_id, per_page, page, include_entities, include_rts 1208 1209 Required: none 1210 1211 Returns tweet timeline for members of the specified list. 1212 Historically, retweets were not available in list timeline responses 1213 but you can now use the include_rts=true parameter to additionally 1214 receive retweet objects. 1215 1216 Returns: ArrayRef[Status] 1217 1218 list_subscribers 1219 1220 Parameters: list_id, slug, owner_screen_name, owner_id, cursor, 1221 include_entities, skip_status 1222 1223 Required: none 1224 1225 Returns the subscribers of the specified list. Private list 1226 subscribers will only be shown if the authenticated user owns the 1227 specified list. 1228 1229 Returns: Hashref 1230 1231 lookup_friendships 1232 1233 Parameters: user_id, screen_name 1234 1235 Required: none 1236 1237 Returns the relationship of the authenticating user to the comma 1238 separated list or ARRAY ref of up to 100 screen_names or user_ids 1239 provided. Values for connections can be: following, 1240 following_requested, followed_by, none. Requires authentication. 1241 1242 Returns: ArrayRef 1243 1244 lookup_users 1245 1246 Parameters: user_id, screen_name, include_entities 1247 1248 Required: none 1249 1250 Return up to 100 users worth of extended information, specified by 1251 either ID, screen name, or combination of the two. The author's most 1252 recent status (if the authenticating user has permission) will be 1253 returned inline. This method is rate limited to 1000 calls per hour. 1254 1255 This method will accept user IDs or screen names as either a comma 1256 delimited string, or as an ARRAY ref. It will also accept arguments 1257 in the normal HASHREF form or as a simple list of named arguments. 1258 I.e., any of the following forms are acceptable: 1259 1260 $nt->lookup_users({ user_id => '1234,6543,3333' }); 1261 $nt->lookup_users(user_id => '1234,6543,3333'); 1262 $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] }); 1263 $nt->lookup_users({ screen_name => 'fred,barney,wilma' }); 1264 $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']); 1265 1266 $nt->lookup_users( 1267 screen_name => ['fred', 'barney' ], 1268 user_id => '4321,6789', 1269 ); 1270 1271 Returns: ArrayRef[User] 1272 1273 members_create_all 1274 1275 alias: add_list_members 1276 1277 Parameters: list_id, slug, owner_screen_name, owner_id 1278 1279 Required: none 1280 1281 Adds multiple members to a list, by specifying a reference to an 1282 array or a comma-separated list of member ids or screen names. The 1283 authenticated user must own the list to be able to add members to it. 1284 Note that lists can't have more than 500 members, and you are limited 1285 to adding up to 100 members to a list at a time with this method. 1286 1287 Returns: List 1288 1289 members_destroy_all 1290 1291 alias: remove_list_members 1292 1293 Parameters: list_id, slug, user_id, screen_name, owner_screen_name, 1294 owner_id 1295 1296 Required: none 1297 1298 Removes multiple members from a list, by specifying a reference to an 1299 array of member ids or screen names, or a string of comma separated 1300 user ids or screen names. The authenticated user must own the list to 1301 be able to remove members from it. Note that lists can't have more 1302 than 500 members, and you are limited to removing up to 100 members 1303 to a list at a time with this method. 1304 1305 Please note that there can be issues with lists that rapidly remove 1306 and add memberships. Take care when using these methods such that you 1307 are not too rapidly switching between removals and adds on the same 1308 list. 1309 1310 Returns: List 1311 1312 mentions 1313 1314 alias: replies 1315 1316 Parameters: since_id, max_id, count, page, trim_user, include_rts, 1317 include_entities 1318 1319 Required: none 1320 1321 Returns the 20 most recent mentions (statuses containing @username) 1322 for the authenticating user. 1323 1324 Returns: ArrayRef[Status] 1325 1326 new_direct_message 1327 1328 new_direct_message(user, text) 1329 1330 Parameters: user, text, screen_name, user_id, include_entities 1331 1332 Required: user, text 1333 1334 Sends a new direct message to the specified user from the 1335 authenticating user. Requires both the user and text parameters. 1336 Returns the sent message when successful. In order to support numeric 1337 screen names, the screen_name or user_id parameters may be used 1338 instead of user. 1339 1340 Returns: DirectMessage 1341 1342 no_retweet_ids 1343 1344 Parameters: none 1345 1346 Required: none 1347 1348 Returns an ARRAY ref of user IDs for which the authenticating user 1349 does not want to receive retweets. 1350 1351 Returns: ArrayRef[UserIDs] 1352 1353 public_timeline 1354 1355 Parameters: skip_user, trim_user, include_entities 1356 1357 Required: none 1358 1359 Returns the 20 most recent statuses from non-protected users who have 1360 set a custom user icon. Does not require authentication. Note that 1361 the public timeline is cached for 60 seconds so requesting it more 1362 often than that is a waste of resources. 1363 1364 If user credentials are provided, public_timeline calls are 1365 authenticated, so they count against the authenticated user's rate 1366 limit. Use ->public_timeline({ authenticate => 0 }) to make an 1367 unauthenticated call which will count against the calling IP address' 1368 rate limit, instead. 1369 1370 Returns: ArrayRef[Status] 1371 1372 rate_limit_status 1373 1374 Parameters: none 1375 1376 Required: none 1377 1378 Returns the remaining number of API requests available to the 1379 authenticated user before the API limit is reached for the current 1380 hour. 1381 1382 Use ->rate_limit_status({ authenticate => 0 }) to force an 1383 unauthenticated call, which will return the status for the IP address 1384 rather than the authenticated user. (Note: for a web application, 1385 this is the server's IP address.) 1386 1387 Returns: RateLimitStatus 1388 1389 related_results 1390 1391 related_results(id) 1392 1393 Parameters: id 1394 1395 Required: id 1396 1397 If available, returns an array of replies and mentions related to the 1398 specified status. There is no guarantee there will be any replies or 1399 mentions in the response. This method is only available to users who 1400 have access to #newtwitter. Requires authentication. 1401 1402 Returns: ArrayRef[Status] 1403 1404 report_spam 1405 1406 report_spam(id) 1407 1408 Parameters: id, user_id, screen_name, include_entities 1409 1410 Required: id 1411 1412 The user specified in the id is blocked by the authenticated user and 1413 reported as a spammer. 1414 1415 Returns: User 1416 1417 retweet 1418 1419 retweet(id) 1420 1421 Parameters: id, include_entities, trim_user 1422 1423 Required: id 1424 1425 Retweets a tweet. Requires the id parameter of the tweet you are 1426 retweeting. Returns the original tweet with retweet details embedded. 1427 1428 Returns: Status 1429 1430 retweeted_by 1431 1432 retweeted_by(id) 1433 1434 Parameters: id, count, page, trim_user, include_entities 1435 1436 Required: id 1437 1438 Returns up to 100 users who retweeted the status identified by id. 1439 1440 Returns: ArrayRef[User] 1441 1442 retweeted_by_ids 1443 1444 retweeted_by_ids(id) 1445 1446 Parameters: id, count, page, trim_user, include_entities 1447 1448 Required: id 1449 1450 Returns the IDs of up to 100 users who retweeted the status 1451 identified by id. 1452 1453 Returns: ArrayRef[User] 1454 1455 retweeted_by_me 1456 1457 Parameters: since_id, max_id, count, page, trim_user, 1458 include_entities 1459 1460 Required: none 1461 1462 Returns the 20 most recent retweets posted by the authenticating 1463 user. 1464 1465 Returns: ArrayRef[Status] 1466 1467 retweeted_by_user 1468 1469 retweeted_by_user(id) 1470 1471 Parameters: id, user_id, screen_name 1472 1473 Required: id 1474 1475 Returns the 20 most recent retweets posted by the specified user. The 1476 user is specified using the user_id or screen_name parameters. This 1477 method is identical to retweeted_by_me except you can choose the user 1478 to view. Does not require authentication, unless the user is 1479 protected. 1480 1481 Returns: ArrayRef 1482 1483 retweeted_to_me 1484 1485 Parameters: since_id, max_id, count, page 1486 1487 Required: none 1488 1489 Returns the 20 most recent retweets posted by the authenticating 1490 user's friends. 1491 1492 Returns: ArrayRef[Status] 1493 1494 retweeted_to_user 1495 1496 retweeted_to_user(id) 1497 1498 Parameters: id, user_id, screen_name 1499 1500 Required: id 1501 1502 Returns the 20 most recent retweets posted by users the specified 1503 user follows. The user is specified using the user_id or screen_name 1504 parameters. This method is identical to retweeted_to_me except you 1505 can choose the user to view. Does not require authentication, unless 1506 the user is protected. 1507 1508 Returns: ArrayRef 1509 1510 retweets 1511 1512 retweets(id) 1513 1514 Parameters: id, count, trim_user, include_entities 1515 1516 Required: id 1517 1518 Returns up to 100 of the first retweets of a given tweet. 1519 1520 Returns: Arrayref[Status] 1521 1522 retweets_of_me 1523 1524 alias: retweeted_of_me 1525 1526 Parameters: since_id, max_id, count, page, trim_user, 1527 include_entities 1528 1529 Required: none 1530 1531 Returns the 20 most recent tweets of the authenticated user that have 1532 been retweeted by others. 1533 1534 Returns: ArrayRef[Status] 1535 1536 reverse_geocode 1537 1538 reverse_geocode(lat, long) 1539 1540 Parameters: lat, long, accuracy, granularity, max_results 1541 1542 Required: lat, long 1543 1544 Search for places (cities and neighborhoods) that can be attached to 1545 a statuses/update. Given a latitude and a longitude, return a list of 1546 all the valid places that can be used as a place_id when updating a 1547 status. Conceptually, a query can be made from the user's location, 1548 retrieve a list of places, have the user validate the location he or 1549 she is at, and then send the ID of this location up with a call to 1550 statuses/update. 1551 1552 There are multiple granularities of places that can be returned -- 1553 "neighborhoods", "cities", etc. At this time, only United States data 1554 is available through this method. 1555 1556 lat 1557 1558 Required. The latitude to query about. Valid ranges are -90.0 to 1559 +90.0 (North is positive) inclusive. 1560 1561 long 1562 1563 Required. The longitude to query about. Valid ranges are -180.0 to 1564 +180.0 (East is positive) inclusive. 1565 1566 accuracy 1567 1568 Optional. A hint on the "region" in which to search. If a number, 1569 then this is a radius in meters, but it can also take a string that 1570 is suffixed with ft to specify feet. If this is not passed in, then 1571 it is assumed to be 0m. If coming from a device, in practice, this 1572 value is whatever accuracy the device has measuring its location 1573 (whether it be coming from a GPS, WiFi triangulation, etc.). 1574 1575 granularity 1576 1577 Optional. The minimal granularity of data to return. If this is not 1578 passed in, then neighborhood is assumed. city can also be passed. 1579 1580 max_results 1581 1582 Optional. A hint as to the number of results to return. This does 1583 not guarantee that the number of results returned will equal 1584 max_results, but instead informs how many "nearby" results to 1585 return. Ideally, only pass in the number of places you intend to 1586 display to the user here. 1587 1588 Returns: HashRef 1589 1590 saved_searches 1591 1592 Parameters: none 1593 1594 Required: none 1595 1596 Returns the authenticated user's saved search queries. 1597 1598 Returns: ArrayRef[SavedSearch] 1599 1600 sent_direct_messages 1601 1602 Parameters: since_id, max_id, page, count, include_entities 1603 1604 Required: none 1605 1606 Returns a list of the 20 most recent direct messages sent by the 1607 authenticating user including detailed information about the sending 1608 and recipient users. 1609 1610 Returns: ArrayRef[DirectMessage] 1611 1612 show_direct_message 1613 1614 show_direct_message(id) 1615 1616 Parameters: id, include_entities 1617 1618 Required: id 1619 1620 Returns a single direct message, specified by an id parameter. Like 1621 the direct_messages request, this method will include the user 1622 objects of the sender and recipient. Requires authentication. 1623 1624 Returns: HashRef 1625 1626 show_friendship 1627 1628 show_friendship(id) 1629 1630 alias: show_relationship 1631 1632 Parameters: source_id, source_screen_name, target_id, target_id_name 1633 1634 Required: id 1635 1636 Returns detailed information about the relationship between two 1637 users. 1638 1639 Returns: Relationship 1640 1641 show_saved_search 1642 1643 show_saved_search(id) 1644 1645 Parameters: id 1646 1647 Required: id 1648 1649 Retrieve the data for a saved search, by id, owned by the 1650 authenticating user. 1651 1652 Returns: SavedSearch 1653 1654 show_status 1655 1656 show_status(id) 1657 1658 Parameters: id, trim_user, include_entities 1659 1660 Required: id 1661 1662 Returns a single status, specified by the id parameter. The status's 1663 author will be returned inline. 1664 1665 Returns: Status 1666 1667 show_user 1668 1669 show_user(id) 1670 1671 Parameters: id, screen_name, include_entities 1672 1673 Required: id 1674 1675 Returns extended information of a given user, specified by ID or 1676 screen name as per the required id parameter. This information 1677 includes design settings, so third party developers can theme their 1678 widgets according to a given user's preferences. You must be properly 1679 authenticated to request the page of a protected user. 1680 1681 Returns: ExtendedUser 1682 1683 similar_places 1684 1685 similar_places(lat, long, name) 1686 1687 Parameters: lat, long, name, contained_within, 1688 attribute:street_address, callback 1689 1690 Required: lat, long, name 1691 1692 Locates places near the given coordinates which are similar in name. 1693 1694 Conceptually you would use this method to get a list of known places 1695 to choose from first. Then, if the desired place doesn't exist, make 1696 a request to add_place to create a new one. 1697 1698 The token contained in the response is the token needed to be able to 1699 create a new place. 1700 1701 Returns: HashRef 1702 1703 subscribe_list 1704 1705 Parameters: owner_screen_name, owner_id, list_id, slug 1706 1707 Required: none 1708 1709 Subscribes the authenticated user to the specified list. 1710 1711 Returns: List 1712 1713 subscriptions 1714 1715 Parameters: user_id, screen_name, count, cursor 1716 1717 Required: none 1718 1719 Obtain a collection of the lists the specified user is subscribed to, 1720 20 lists per page by default. Does not include the user's own lists. 1721 1722 Returns: ArrayRef[List] 1723 1724 suggestion_categories 1725 1726 Parameters: none 1727 1728 Required: none 1729 1730 Returns the list of suggested user categories. The category slug can 1731 be used in the user_suggestions API method get the users in that 1732 category . Does not require authentication. 1733 1734 Returns: ArrayRef 1735 1736 test 1737 1738 Parameters: none 1739 1740 Required: none 1741 1742 Returns the string "ok" status code. 1743 1744 Returns: Str 1745 1746 trends_available 1747 1748 Parameters: lat, long 1749 1750 Required: none 1751 1752 Returns the locations with trending topic information. The response 1753 is an array of "locations" that encode the location's WOEID (a Yahoo! 1754 Where On Earth ID http://developer.yahoo.com/geo/geoplanet/) and some 1755 other human-readable information such as a the location's canonical 1756 name and country. 1757 1758 When the optional lat and long parameters are passed, the available 1759 trend locations are sorted by distance from that location, nearest to 1760 farthest. 1761 1762 Use the WOEID returned in the location object to query trends for a 1763 specific location. 1764 1765 Returns: ArrayRef[Location] 1766 1767 trends_current 1768 1769 trends_current(exclude) 1770 1771 Parameters: exclude 1772 1773 Required: none 1774 1775 Returns the current top ten trending topics on Twitter. The response 1776 includes the time of the request, the name of each trending topic, 1777 and query used on Twitter Search results page for that topic. 1778 1779 Returns: HashRef 1780 1781 trends_daily 1782 1783 Parameters: date, exclude 1784 1785 Required: none 1786 1787 Returns the top 20 trending topics for each hour in a given day. 1788 1789 Returns: HashRef 1790 1791 trends_location 1792 1793 trends_location(woeid) 1794 1795 Parameters: woeid 1796 1797 Required: woeid 1798 1799 Returns the top 10 trending topics for a specific location. The 1800 response is an array of "trend" objects that encode the name of the 1801 trending topic, the query parameter that can be used to search for 1802 the topic on Search, and the direct URL that can be issued against 1803 Search. This information is cached for five minutes, and therefore 1804 users are discouraged from querying these endpoints faster than once 1805 every five minutes. Global trends information is also available from 1806 this API by using a WOEID of 1. 1807 1808 Returns: ArrayRef[Trend] 1809 1810 trends_weekly 1811 1812 Parameters: date, exclude 1813 1814 Required: none 1815 1816 Returns the top 30 trending topics for each day in a given week. 1817 1818 Returns: HashRef 1819 1820 unsubscribe_list 1821 1822 Parameters: list_id, slug, owner_screen_name, owner_id 1823 1824 Required: none 1825 1826 Unsubscribes the authenticated user from the specified list. 1827 1828 Returns: List 1829 1830 update 1831 1832 update(status) 1833 1834 Parameters: status, lat, long, place_id, display_coordinates, 1835 in_reply_to_status_id, trim_user, include_entities 1836 1837 Required: status 1838 1839 Updates the authenticating user's status. Requires the status 1840 parameter specified. A status update with text identical to the 1841 authenticating user's current status will be ignored. 1842 1843 status 1844 1845 Required. The text of your status update. URL encode as necessary. 1846 Statuses over 140 characters will cause a 403 error to be returned 1847 from the API. 1848 1849 in_reply_to_status_id 1850 1851 Optional. The ID of an existing status that the update is in reply 1852 to. o Note: This parameter will be ignored unless the author of the 1853 tweet this parameter references is mentioned within the status 1854 text. Therefore, you must include @username, where username is the 1855 author of the referenced tweet, within the update. 1856 1857 lat 1858 1859 Optional. The location's latitude that this tweet refers to. The 1860 valid ranges for latitude is -90.0 to +90.0 (North is positive) 1861 inclusive. This parameter will be ignored if outside that range, if 1862 it is not a number, if geo_enabled is disabled, or if there not a 1863 corresponding long parameter with this tweet. 1864 1865 long 1866 1867 Optional. The location's longitude that this tweet refers to. The 1868 valid ranges for longitude is -180.0 to +180.0 (East is positive) 1869 inclusive. This parameter will be ignored if outside that range, if 1870 it is not a number, if geo_enabled is disabled, or if there not a 1871 corresponding lat parameter with this tweet. 1872 1873 place_id 1874 1875 Optional. The place to attach to this status update. Valid 1876 place_ids can be found by querying reverse_geocode. 1877 1878 display_coordinates 1879 1880 Optional. By default, geo-tweets will have their coordinates 1881 exposed in the status object (to remain backwards compatible with 1882 existing API applications). To turn off the display of the precise 1883 latitude and longitude (but keep the contextual location 1884 information), pass display_coordinates = 0> on the status update. 1885 1886 Returns: Status 1887 1888 update_delivery_device 1889 1890 update_delivery_device(device) 1891 1892 Parameters: device 1893 1894 Required: device 1895 1896 Sets which device Twitter delivers updates to for the authenticating 1897 user. Sending none as the device parameter will disable IM or SMS 1898 updates. 1899 1900 Returns: BasicUser 1901 1902 update_friendship 1903 1904 update_friendship(id) 1905 1906 Parameters: id, user_id, screen_name, device, retweets 1907 1908 Required: id 1909 1910 Allows you enable or disable retweets and device notifications from 1911 the specified user. All other values are assumed to be false. 1912 Requires authentication. 1913 1914 Returns: HashRef 1915 1916 update_list 1917 1918 Parameters: list_id, slug, name, mode, description, 1919 owner_screen_name, owner_id 1920 1921 Required: none 1922 1923 Updates the specified list. The authenticated user must own the list 1924 to be able to update it. 1925 1926 Returns: List 1927 1928 update_profile 1929 1930 Parameters: name, email, url, location, description, include_entities 1931 1932 Required: none 1933 1934 Sets values that users are able to set under the "Account" tab of 1935 their settings page. Only the parameters specified will be updated; 1936 to only update the "name" attribute, for example, only include that 1937 parameter in your request. 1938 1939 Returns: ExtendedUser 1940 1941 update_profile_background_image 1942 1943 update_profile_background_image(image) 1944 1945 Parameters: image, use 1946 1947 Required: image 1948 1949 Updates the authenticating user's profile background image. The image 1950 parameter must be an arrayref with the same interpretation as the 1951 image parameter in the update_profile_image method. The use parameter 1952 allows you to specify whether to use the uploaded profile background 1953 or not. See that method's documentation for details. 1954 1955 Returns: ExtendedUser 1956 1957 update_profile_colors 1958 1959 Parameters: profile_background_color, profile_text_color, 1960 profile_link_color, profile_sidebar_fill_color, 1961 profile_sidebar_border_color 1962 1963 Required: none 1964 1965 Sets one or more hex values that control the color scheme of the 1966 authenticating user's profile page on twitter.com. These values are 1967 also returned in the /users/show API method. 1968 1969 Returns: ExtendedUser 1970 1971 update_profile_image 1972 1973 update_profile_image(image) 1974 1975 Parameters: image 1976 1977 Required: image 1978 1979 Updates the authenticating user's profile image. The image parameter 1980 is an arrayref with the following interpretation: 1981 1982 [ $file ] 1983 [ $file, $filename ] 1984 [ $file, $filename, Content_Type => $mime_type ] 1985 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ] 1986 1987 The first value of the array ($file) is the name of a file to open. 1988 The second value ($filename) is the name given to Twitter for the 1989 file. If $filename is not provided, the basename portion of $file is 1990 used. If $mime_type is not provided, it will be provided 1991 automatically using LWP::MediaTypes::guess_media_type(). 1992 1993 $raw_image_data can be provided, rather than opening a file, by 1994 passing undef as the first array value. 1995 1996 Returns: ExtendedUser 1997 1998 update_with_media 1999 2000 update_with_media(status, media) 2001 2002 Parameters: status, media[], possibly_sensitive, 2003 in_reply_to_status_id, lat, long, place_id, display_coordinates 2004 2005 Required: status, media 2006 2007 Updates the authenticating user's status and attaches media for 2008 upload. 2009 2010 The media[] parameter is an arrayref with the following 2011 interpretation: 2012 2013 [ $file ] 2014 [ $file, $filename ] 2015 [ $file, $filename, Content_Type => $mime_type ] 2016 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ] 2017 2018 The first value of the array ($file) is the name of a file to open. 2019 The second value ($filename) is the name given to Twitter for the 2020 file. If $filename is not provided, the basename portion of $file is 2021 used. If $mime_type is not provided, it will be provided 2022 automatically using LWP::MediaTypes::guess_media_type(). 2023 2024 $raw_image_data can be provided, rather than opening a file, by 2025 passing undef as the first array value. 2026 2027 The Tweet text will be rewritten to include the media URL(s), which 2028 will reduce the number of characters allowed in the Tweet text. If 2029 the URL(s) cannot be appended without text truncation, the tweet will 2030 be rejected and this method will return an HTTP 403 error. 2031 2032 Returns: Status 2033 2034 user_suggestions 2035 2036 user_suggestions(category) 2037 2038 alias: follow_suggestions 2039 2040 Parameters: category, lang 2041 2042 Required: category 2043 2044 Access the users in a given category of the Twitter suggested user 2045 list and return their most recent status if they are not a protected 2046 user. Currently supported values for optional parameter lang are en, 2047 fr, de, es, it. Does not require authentication. 2048 2049 Returns: ArrayRef 2050 2051 user_timeline 2052 2053 Parameters: id, user_id, screen_name, since_id, max_id, count, page, 2054 skip_user, trim_user, include_entities, include_rts 2055 2056 Required: none 2057 2058 Returns the 20 most recent statuses posted from the authenticating 2059 user. It's also possible to request another user's timeline via the 2060 id parameter. This is the equivalent of the Web /archive page for 2061 your own user, or the profile page for a third party. 2062 2063 Returns: ArrayRef[Status] 2064 2065 users_search 2066 2067 users_search(q) 2068 2069 alias: find_people 2070 2071 alias: search_users 2072 2073 Parameters: q, per_page, page, include_entities 2074 2075 Required: q 2076 2077 Run a search for users similar to Find People button on Twitter.com; 2078 the same results returned by people search on Twitter.com will be 2079 returned by using this API (about being listed in the People Search). 2080 It is only possible to retrieve the first 1000 matches from this API. 2081 2082 Returns: ArrayRef[Users] 2083 2084 verify_credentials 2085 2086 verify_credentials(include_entities) 2087 2088 Parameters: include_entities 2089 2090 Required: none 2091 2092 Returns an HTTP 200 OK response code and a representation of the 2093 requesting user if authentication was successful; returns a 401 2094 status code and an error message if not. Use this method to test if 2095 supplied user credentials are valid. 2096 2097 Returns: ExtendedUser 2098 2099Search API Methods 2100 2101 search 2102 2103 search(q) 2104 2105 Parameters: q, callback, lang, locale, rpp, page, since_id, until, 2106 geocode, show_user, result_type 2107 2108 Required: q 2109 2110 Returns a HASH reference with some meta-data about the query 2111 including the next_page, refresh_url, and max_id. The statuses are 2112 returned in results. To iterate over the results, use something 2113 similar to: 2114 2115 my $r = $nt->search($searh_term); 2116 for my $status ( @{$r->{results}} ) { 2117 print "$status->{text}\n"; 2118 } 2119 2120 Returns: HashRef 2121 2122ERROR HANDLING 2123 2124 When Net::Twitter::Lite encounters a Twitter API error or a network 2125 error, it throws a Net::Twitter::Lite::Error object. You can catch and 2126 process these exceptions by using eval blocks and testing $@: 2127 2128 eval { 2129 my $statuses = $nt->friends_timeline(); # this might die! 2130 2131 for my $status ( @$statuses ) { 2132 #... 2133 } 2134 }; 2135 if ( $@ ) { 2136 # friends_timeline encountered an error 2137 2138 if ( blessed $@ && $@->isa('Net::Twitter::Lite::Error' ) { 2139 #... use the thrown error obj 2140 warn $@->error; 2141 } 2142 else { 2143 # something bad happened! 2144 die $@; 2145 } 2146 } 2147 2148 Net::Twitter::Lite::Error stringifies to something reasonable, so if 2149 you don't need detailed error information, you can simply treat $@ as a 2150 string: 2151 2152 eval { $nt->update($status) }; 2153 if ( $@ ) { 2154 warn "update failed because: $@\n"; 2155 } 2156 2157AUTHENTICATION 2158 2159 Net::Twitter::Lite currently supports both Basic Authentication and 2160 OAuth. The choice of authentication strategies is determined by the 2161 options passed to new or the use of the credentials method. An error 2162 will be thrown if options for both strategies are provided. 2163 2164 BASIC AUTHENTICATION 2165 2166 To use Basic Authentication, pass the username and password options to 2167 new, or call credentials to set them. When Basic Authentication is 2168 used, the Authorization header is set on each authenticated API call. 2169 2170 OAUTH AUTHENTICATION 2171 2172 To use OAuth authentication, pass the consumer_key and consumer_secret 2173 options to new. 2174 2175 Net::OAuth::Simple must be installed in order to use OAuth and an error 2176 will be thrown if OAuth is attempted without it. Net::Twitter::Lite 2177 does not require Net::OAuth::Simple, making OAuth an optional feature. 2178 2179 OAUTH EXAMPLES 2180 2181 See the examples directory included in this distribution for full 2182 working examples using OAuth. 2183 2184 Here's how to authorize users as a desktop app mode: 2185 2186 use Net::Twitter::Lite; 2187 2188 my $nt = Net::Twitter::Lite->new( 2189 consumer_key => "YOUR-CONSUMER-KEY", 2190 consumer_secret => "YOUR-CONSUMER-SECRET", 2191 ); 2192 2193 # You'll save the token and secret in cookie, config file or session database 2194 my($access_token, $access_token_secret) = restore_tokens(); 2195 if ($access_token && $access_token_secret) { 2196 $nt->access_token($access_token); 2197 $nt->access_token_secret($access_token_secret); 2198 } 2199 2200 unless ( $nt->authorized ) { 2201 # The client is not yet authorized: Do it now 2202 print "Authorize this app at ", $nt->get_authorization_url, " and enter the PIN#\n"; 2203 2204 my $pin = <STDIN>; # wait for input 2205 chomp $pin; 2206 2207 my($access_token, $access_token_secret, $user_id, $screen_name) = 2208 $nt->request_access_token(verifier => $pin); 2209 save_tokens($access_token, $access_token_secret); # if necessary 2210 } 2211 2212 # Everything's ready 2213 2214 In a web application mode, you need to save the oauth_token and 2215 oauth_token_secret somewhere when you redirect the user to the OAuth 2216 authorization URL. 2217 2218 sub twitter_authorize : Local { 2219 my($self, $c) = @_; 2220 2221 my $nt = Net::Twitter::Lite->new(%param); 2222 my $url = $nt->get_authorization_url(callback => $callbackurl); 2223 2224 $c->response->cookies->{oauth} = { 2225 value => { 2226 token => $nt->request_token, 2227 token_secret => $nt->request_token_secret, 2228 }, 2229 }; 2230 2231 $c->response->redirect($url); 2232 } 2233 2234 And when the user returns back, you'll reset those request token and 2235 secret to upgrade the request token to access token. 2236 2237 sub twitter_auth_callback : Local { 2238 my($self, $c) = @_; 2239 2240 my %cookie = $c->request->cookies->{oauth}->value; 2241 2242 my $nt = Net::Twitter::Lite->new(%param); 2243 $nt->request_token($cookie{token}); 2244 $nt->request_token_secret($cookie{token_secret}); 2245 my $verifier = $c->req->param->{oauth_verifier}; 2246 2247 my($access_token, $access_token_secret, $user_id, $screen_name) = 2248 $nt->request_access_token(verifier => $verifier); 2249 2250 # Save $access_token and $access_token_secret in the database associated with $c->user 2251 } 2252 2253 Later on, you can retrieve and reset those access token and secret 2254 before calling any Twitter API methods. 2255 2256 sub make_tweet : Local { 2257 my($self, $c) = @_; 2258 2259 my($access_token, $access_token_secret) = ...; 2260 2261 my $nt = Net::Twitter::Lite->new(%param); 2262 $nt->access_token($access_token); 2263 $nt->access_token_secret($access_token_secret); 2264 2265 # Now you can call any Net::Twitter::Lite API methods on $nt 2266 my $status = $c->req->param('status'); 2267 my $res = $nt->update({ status => $status }); 2268 } 2269 2270SEE ALSO 2271 2272 Net::Twitter::Lite::WithAPIv1_1 2273 2274 With support for Twitter API v1.1 2275 2276 Net::Twitter::Lite::Error 2277 2278 The Net::Twitter::Lite exception object. 2279 2280 http://apiwiki.twitter.com/Twitter-API-Documentation 2281 2282 This is the official Twitter API documentation. It describes the 2283 methods and their parameters in more detail and may be more current 2284 than the documentation provided with this module. 2285 2286 LWP::UserAgent::POE 2287 2288 This LWP::UserAgent compatible class can be used in POE based 2289 application along with Net::Twitter::Lite to provide concurrent, 2290 non-blocking requests. 2291 2292SUPPORT 2293 2294 Please report bugs to bug-net-twitter@rt.cpan.org, or through the web 2295 interface at https://rt.cpan.org/Dist/Display.html?Queue=Net-Twitter. 2296 2297 Join the Net::Twitter IRC channel at irc://irc.perl.org/net-twitter. 2298 2299 Follow perl_api: http://twitter.com/perl_api. 2300 2301 Track Net::Twitter::Lite development at 2302 http://github.com/semifor/net-twitter-lite. 2303 2304AUTHOR 2305 2306 Marc Mims <marc@questright.com> 2307 2308CONTRIBUTORS 2309 2310 Chris Page <chris@starforge.co.uk> 2311 2312LICENSE 2313 2314 Copyright (c) 2013 Marc Mims 2315 2316 This library is free software; you can redistribute it and/or modify it 2317 under the same terms as Perl itself. 2318 2319