1NAME 2 Net::Twitter - A perl interface to the Twitter API 3 4SYNOPSIS 5 use Net::Twitter; 6 use Scalar::Util 'blessed'; 7 8 # When no authentication is required: 9 my $nt = Net::Twitter->new(legacy => 0); 10 11 # As of 13-Aug-2010, Twitter requires OAuth for authenticated requests 12 my $nt = Net::Twitter->new( 13 traits => [qw/API::RESTv1_1/], 14 consumer_key => $consumer_key, 15 consumer_secret => $consumer_secret, 16 access_token => $token, 17 access_token_secret => $token_secret, 18 ); 19 20 my $result = $nt->update('Hello, world!'); 21 22 eval { 23 my $statuses = $nt->friends_timeline({ since_id => $high_water, count => 100 }); 24 for my $status ( @$statuses ) { 25 print "$status->{created_at} <$status->{user}{screen_name}> $status->{text}\n"; 26 } 27 }; 28 if ( my $err = $@ ) { 29 die $@ unless blessed $err && $err->isa('Net::Twitter::Error'); 30 31 warn "HTTP Response Code: ", $err->code, "\n", 32 "HTTP Message......: ", $err->message, "\n", 33 "Twitter error.....: ", $err->error, "\n"; 34 } 35 36TWITTER API V1.1 SUPPORT 37 This version of Net::Twitter provides Twitter API v1.1 support. Enable 38 it by including the "API::RESTv1_1" trait instead of "API::REST". Using 39 Twitter API v1.1 may require changes to you code! It is not completely 40 backwards compatible with v1. 41 42 For help migrating your application to Twitter API v1.1, see 43 Net::Twitter::Manual::MigratingToV1_1. 44 45DESCRIPTION 46 This module has been superseded by Twitter::API. Please update as soon 47 as you possibly can to use new features and the new API versions. This 48 module will no longer be supported. 49 50 This module provides a perl interface to the Twitter APIs. See 51 <http://dev.twitter.com/docs> for a full description of the Twitter 52 APIs. 53 54TWITTER API VERSION 1.1 55 Twitter will (perhaps has by the time you read this) deprecated version 56 1 of the API. Documentation, here, assumes version 1.1 of the API. For 57 version 1 documentation, see Net::Twitter::Role::API::REST. 58 59 To use Twitter API version 1.1, simply replace "API::REST" in the 60 "traits" argument to "new" with "API::RESTv1_1". The "Net::Twitter" API 61 is backwards compatible to the extent possible. If Twitter does not 62 provide a 1.1 endpoint for a version 1 call, "Net::Twitter" cannot 63 support it, of course. 64 65 Twitter API version 1.1 requires OAuth authentication for all calls. 66 There is no longer an IP address limit and a per-user limit. Each API 67 call has it's own rate limit. Most are 15 calls reset every 15 minutes. 68 Others are 180 calls, reset every 15 minutes. These limits may change. 69 For current rate limits, see 70 <https://dev.twitter.com/docs/rate-limiting/1.1/limits>. 71 72OMG! THE MOOSE! 73 Net::Twitter is Moose based. Moose provides some advantages, including 74 the ability for the maintainer of this module to respond quickly to 75 Twitter API changes. 76 77 See Net::Twitter::Lite if you need an alternative without Moose and its 78 dependencies. 79 80 Net::Twitter::Lite's API method definitions and documentation are 81 generated from Net::Twitter. It is a related module, but does not depend 82 on Net::Twitter or Moose for installation. 83 84RETURN VALUES 85 Net::Twitter decodes the data structures returned by the Twitter API 86 into native perl data structures (HASH references and ARRAY references). 87 The full layout of those data structures are not documented, here. They 88 change often, usually with the addition of new elements, and documenting 89 all of those changes would be a significant challenge. 90 91 Instead, rely on the online Twitter API documentation and inspection of 92 the returned data. 93 94 The Twitter API online documentation is located at 95 <http://dev.twitter.com/doc>. 96 97 To inspect the data, use Data::Dumper or similar module of your choice. 98 Here's a simple example using Data::Dumper: 99 100 use Data::Dumper; 101 102 my $r = $nt->search($search_term); 103 print Dumper $r; 104 105 For more information on perl data structures, see perlreftut, perldsc, 106 and perllol. 107 108METHODS AND ARGUMENTS 109 new This constructs a "Net::Twitter" object. It takes several named 110 parameters, all of them optional: 111 112 traits 113 An ARRAY ref of traits used to control which APIs the 114 constructed "Net::Twitter" object will support and how it 115 handles errors. Possible values are: 116 117 API::RESTv1_1 118 Provides support for the Twitter REST API version 1.1 119 methods. 120 121 API::Search 122 Deprecated. Use "search" in API::RESTv1_1 instead. 123 124 AppAuth 125 Provides Application-Only Authentication 126 <https://dev.twitter.com/oauth/application-only> with 127 methods, "request_access_token" and "invalidate_token". See 128 Net::Twitter::Role::AppAuth. 129 130 Example: 131 132 my $nt = Net::Twitter->new( 133 traits => [ qw/AppAuth API::RESTv1_1/ ], 134 consumer_key => 'my-consumer-key', 135 consumer_secret => 'my-consumer-secret', 136 ); 137 138 $nt->request_access_token; 139 say 'token: ', $nt->access_token; 140 my $r = $nt->followers_ids({ 141 screen_name => 'timtoady', 142 cursor => -1, 143 }); 144 145 # good until invalidated, with ... 146 $nt->invalidate_token 147 148 AutoCursor 149 "AutoCursor" is a parameterized trait that provides an 150 automatic loop for cursored calls, returning an ARRAY 151 reference to the combined results. By default, it handles 152 "friends_ids" and "followers_ids". See 153 Net::Twitter::Role::AutoCursor for details. 154 155 InflateObjects 156 When this optional trait is included, Net::Twitter inflates 157 HASH refs returned by Twitter into objects with read 158 accessors for each element. In addition, it inflates dates 159 to DateTime objects and URLs to URI objects. Objects that 160 include a "created_at" attribute also have a 161 "relative_created_at" method. 162 163 For example, with "InflateObjects" applied, the 164 <friends_timeline> method returns an array of status 165 objects: 166 167 $r = $nt->friends_timeline; 168 for my $status ( @$r ) { 169 $r->user->screen_name; # same as $r->{user}{screen_name} 170 171 # $created_at is a DateTime; $age is a DateTime::Duration 172 my $age = DateTime->now - $r->created_at; 173 174 # print an age in a similar style to the Twitter web site, e.g.: 175 # less than a minute ago 176 # about a minute ago 177 # 6 minutes ago 178 # 1 day ago 179 # etc. 180 print $r->relative_created_at; 181 182 Legacy 183 This trait provides backwards compatibility to 184 "Net::Twitter" versions prior to 3.00. It implies the traits 185 "API::REST", "API::Search", "API::TwitterVision", and 186 "API::WrapError". It also provides additional functionality 187 to ensure consistent behavior for applications written for 188 use with legacy versions of "Net::Twitter". 189 190 In the current version, this trait is automatically included 191 if the "traits" option is not specified. This ensures 192 backwards compatibility for existing applications using 193 "Net::Twitter" versions prior to 3.00. See section "LEGACY 194 COMPATIBILITY" for more details. 195 196 OAuth 197 The "OAuth" trait provides OAuth authentication rather than 198 the default Basic Authentication for Twitter API method 199 calls. See the "Authentication" section and 200 Net::Twitter::Role::OAuth for full documentation. 201 202 RateLimit 203 The "RateLimit" trait adds utility methods that return 204 information about the current rate limit status. See 205 Net::Twitter::Role::RateLimit for details. 206 207 RetryOnError 208 The "RetryOnError" trait automatically retries Twitter API 209 calls with temporary failures. See 210 Net::Twitter::Role::RetryOnError for details. 211 212 WrapError 213 "Net::Twitter" normally throws exceptions on error. When 214 this trait is included, "Net::Twitter" returns undef when a 215 method fails and makes the error available through method 216 "get_error". This is the way all errors were handled in 217 Net::Twitter versions prior to version 3.00. 218 219 Some examples of using the "traits" parameter in "new": 220 221 # provide support for *only* the REST API; throw exceptions on error 222 $nt = Net::Twitter->new(traits => ['API::RESTv1_1']); 223 224 # provide support for both the REST and Search APIs; wrap errors 225 $nt = Net::Twitter->new(traits => [qw/API::RESTv1_1 API::Search WrapError/]); 226 227 # Provide legacy support for applications written with Net::Twitter 228 # prior to version 3.0. 229 $nt = Net::Twitter->new(traits => ['Legacy']); 230 231 legacy 232 A boolean. If set to 0, "new" constructs a "Net::Twitter" object 233 implementing the REST API and throws exceptions on API method 234 errors. 235 236 Net::Twitter->new(legacy => 0); 237 238 is a shortcut for: 239 240 Net::Twitter->new(traits => ['API::RESTv1_1']); 241 242 If set to 1, "new" constructs a "Net::Twitter" object with the 243 "Legacy" trait. 244 245 Net::Twitter->new(legacy => 1); 246 247 is a shortcut for: 248 249 Net::Twitter->new(traits => ['Legacy']); 250 251 username 252 This is the username for Basic Authentication. NOTE: as of 253 31-Aug-2010, Twitter no longer supports Basic Authentication. 254 Use OAuth instead. Other Twitter compatible services may, 255 however, accept Basic Authentication, so support for it remains 256 in "Net::Twitter". 257 258 password 259 This is the password used for Basic Authentication. 260 261 clientname 262 The value for the "X-Twitter-Client-Name" HTTP header. It 263 defaults to "Perl Net::Twitter". Note: This option has nothing 264 to do with the "via" application byline. 265 266 clientver 267 The value for the "X-Twitter-Client-Version" HTTP header. It 268 defaults to current version of the "Net::Twitter" module. 269 270 clienturl 271 The value for the "X-Twitter-Client-URL" HTTP header. It 272 defaults to the search.cpan.org page for the "Net::Twitter" 273 distribution. 274 275 useragent_class 276 The "LWP::UserAgent" compatible class used internally by 277 "Net::Twitter". It defaults to "LWP::UserAgent". For POE based 278 applications, consider using "LWP::UserAgent::POE". 279 280 useragent_args 281 An HASH ref of arguments to pass to constructor of the class 282 specified with "useragent_class", above. It defaults to {} (an 283 empty HASH ref). 284 285 useragent 286 The value for "User-Agent" HTTP header. It defaults to 287 "Net::Twitter/4.01043 (Perl)". 288 289 source 290 Twitter on longer uses the "source" parameter. Support for it 291 remains in "Net::Twitter" for any compatible services that may 292 use it. It was originally used by Twitter to provide an "via" 293 application byline. 294 295 apiurl 296 The URL for the Twitter API. This defaults to 297 "http://api.twitter.com/1". This option is available when the 298 "API::RESTv1_1" trait is included. 299 300 apihost 301 DEPRECATED - Setting the "apiurl" is sufficient. 302 303 apirealm 304 A string containing the Twitter API realm used for Basic 305 Authentication. It defaults to "Twitter API". This option is 306 available when the "API::RESTv1_1" trait is included. 307 308 identica 309 If set to 1, "Net::Twitter" overrides the defaults for "apiurl", 310 "apihost", and "apirealm" to "http://identi.ca/api", 311 "identi.ca:80", and "Laconica API" respectively. It defaults to 312 0. This option is available when the "API::RESTv1_1" trait is 313 included. 314 315 consumer_key 316 A string containing the OAuth consumer key provided by Twitter 317 when an application is registered. This option is available when 318 the "OAuth" trait is included. 319 320 consumer_secret 321 A string containing the OAuth consumer secret. This option is 322 available when the "OAuth" trait is included. 323 324 ssl If set to 1, an SSL connection will be used for all API calls. 325 Defaults to 1. 326 327 netrc 328 (Optional) Sets the *machine* key to look up in ".netrc" to 329 obtain credentials. If set to 1, Net::Twitter will use the value 330 of the "netrc_machine" option (below). 331 332 # in .netrc 333 machine api.twitter.com 334 login YOUR_TWITTER_USER_NAME 335 password YOUR_TWITTER_PASSWORD 336 machine semifor.twitter.com 337 login semifor 338 password SUPERSECRET 339 340 # in your perl program 341 $nt = Net::Twitter->new(netrc => 1); 342 $nt = Net::Twitter->new(netrc => 'semifor.twitter.com'); 343 344 netrc_machine 345 (Optional) Sets the "machine" entry to look up in ".netrc" when 346 "<netrc =" 1>> is used. Defaults to "api.twitter.com". 347 348 decode_html_entities 349 Twitter encodes HTML entities in the "text" field of statuses. 350 Set this option to 1 to have them automatically decoded. Default 351 0. 352 353 credentials($username, $password) 354 Set the credentials for Basic Authentication. This is helpful for 355 managing multiple accounts. 356 357 ua Provides access to the constructed user agent object used internally 358 by "Net::Twitter". Use it with caution. 359 360AUTHENTICATION 361 With REST API version 1.1, all API calls require OAuth. Since 362 31-Aug-2010, version 1 required OAuth requests requiring authentication. 363 Other Twitter compatible services, like Identi.ca, accept Basic 364 Authentication. So, "Net::Twitter" provides support for both. 365 366 To set up OAuth, include the "consumer_key" and "consumer_secret" 367 options to "new". When they are provided, the "OAuth" trait will be 368 automatically included. See Net::Twitter::Role::OAuth for more 369 information on using OAuth, including examples. 370 371 To set up Basic Authentication in "Net::Twitter", provide the "username" 372 and "password" options to "new" or call the "credentials" method. 373 374 In addition to the arguments specified for each API method described 375 below, an additional "-authenticate" parameter can be passed. To request 376 an "Authorization" header, pass "-authenticate => 1"; to suppress an 377 authentication header, pass "-authenticate => 0". Even if requested, an 378 Authorization header will not be added if there are no user credentials 379 (username and password for Basic Authentication; access tokens for 380 OAuth). 381 382 This is probably only useful for non-Twitter sites that use the Twitter 383 API and support unauthenticated calls. 384 385API METHODS AND ARGUMENTS 386 Most Twitter API methods take parameters. All Net::Twitter API methods 387 will accept a HASH ref of named parameters as specified in the Twitter 388 API documentation. For convenience, many Net::Twitter methods accept 389 simple positional arguments. The positional parameter passing style is 390 optional; you can always use the named parameters in a HASH reference if 391 you prefer. 392 393 You may pass any number of required parameters as positional parameters. 394 You must pass them in the order specified in the documentation for each 395 method. Optional parameters must be passed as named parameters in a HASH 396 reference. The HASH reference containing the named parameters must be 397 the final parameter to the method call. Any required parameters not 398 passed as positional parameters, must be included in the named parameter 399 HASH reference. 400 401 For example, the REST API method "update" has one required parameter, 402 "status". You can call "update" with a HASH ref argument: 403 404 $nt->update({ status => 'Hello world!' }); 405 406 Or, you can use the convenient, positional parameter form: 407 408 $nt->update('Hello world!'); 409 410 The "update" method also has an optional parameter, 411 "in_reply_to_status_id". To use it, you must use the HASH ref form: 412 413 $nt->update({ status => 'Hello world!', in_reply_to_status_id => $reply_to }); 414 415 You may use the convenient positional form for the required "status" 416 parameter with the optional parameters specified in the named parameter 417 HASH reference: 418 419 $nt->update('Hello world!', { in_reply_to_status_id => $reply_to }); 420 421 Convenience form is provided for the required parameters of all API 422 methods. So, these two calls are equivalent: 423 424 $nt->friendship_exists({ user_a => $fred, user_b => $barney }); 425 $nt->friendship_exists($fred, $barney); 426 427 Many API methods have aliases. You can use the API method name, or any 428 of its aliases, as you prefer. For example, these calls are all 429 equivalent: 430 431 $nt->friendship_exists($fred, $barney); 432 $nt->relationship_exists($fred, $barney); 433 $nt->follows($fred, $barney); 434 435 Aliases support both the HASH ref and convenient forms: 436 437 $nt->follows({ user_a => $fred, user_b => $barney }); 438 439 Cursors and Paging 440 Some methods return partial results a page at a time. Originally, 441 methods that returned partial results used a "page" parameter. A more 442 recent addition to the Twitter API for retrieving multiple pages uses 443 the "cursor" parameter. Usually, a method uses either the "page" 444 parameter or the "cursor" parameter, but not both. There have been 445 exceptions to this rule when Twitter deprecates the use of "page" for a 446 method in favor of "cursor". In that case, both methods may work during 447 a transition period. So, if a method supports both, you should always 448 use the "cursor" parameter. 449 450 Paging 451 For methods that support paging, the first page is returned by passing 452 "page => 1", the second page by passing "page => 2", etc. If no "page" 453 parameter is passed, the first page is returned. 454 455 Here's an example that demonstrates how to obtain all favorites in a 456 loop: 457 458 my @favs; 459 for ( my $page = 1; ; ++$page ) { 460 my $r = $nt->favorites({ page => $page }); 461 last unless @$r; 462 463 push @favs, @$r; 464 } 465 466 Cursors 467 Cursoring employs a different strategy. To obtain the first page of 468 results, pass "cursor => -1". Twitter returns a reference to a hash that 469 includes entries "next_cursor", "previous_cursor", and an entry with a 470 reference to an array containing a page of the requested items. The key 471 for the array reference will be named "users", "ids", or something 472 similar depending upon the type of returned items. For example, when 473 "cursor" parameter is used with the "followers_ids" method, the returned 474 in hash entry "ids". 475 476 The "next_cursor" value can be used in a subsequent call to obtain the 477 next page of results. When you have obtained the last page of results, 478 "next_cursor" will be 0. Likewise, you can use the value for 479 "previous_cursor" to obtain the previous page of results. When you have 480 obtained the first page, "previous_cursor" will be 0. 481 482 Here's an example that demonstrates how to obtain all follower IDs in a 483 loop using the "cursor" parameter: 484 485 my @ids; 486 for ( my $cursor = -1, my $r; $cursor; $cursor = $r->{next_cursor} ) { 487 $r = $nt->followers_ids({ cursor => $cursor }); 488 push @ids, @{ $r->{ids} }; 489 } 490 491 Synthetic Arguments 492 In addition to the arguments described in the Twitter API Documentation 493 for each API method, Net::Twitter supports additional *synthetic* 494 arguments. 495 496 -authenticate 497 When set to 1, Net::Twitter will provide an Authorization header for 498 the API call; when set to 0, it will suppress the Authentication 499 header. This argument overrides the defined authentication behavior 500 for the API method. It is probably only useful for the 501 "rate_limit_status" method which returns different values for 502 authenticated and unauthenticated calls. See "AUTHENTICATION" for 503 more details. 504 505 -since 506 API methods that accept the "since_id" argument will also accept the 507 synthetic "-since" argument, instead. "-since" may be a "Date::Time" 508 object, an epoch time (the number of seconds since the system 509 epoch), or a string in the same format returned by Twitter for the 510 "created_at" attribute. Only statuses with a "created_at" time 511 greater than "-since" will be returned by the API call. 512 513 -legacy_lists_api 514 This option is only effective when the legacy "API::Lists" trait is 515 applied. Passing "-legacy_lists_api" set to 0 for lists methods will 516 use the new lists endpoints and semantics. This will facilitate 517 upgrading an application to use the new lists api methods. When the 518 "API::Lists" trait is not applied, this option is ignored. 519 520REST API Methods 521 These methods are provided when trait "API::RESTv1_1" is included in the 522 "traits" option to "new". 523 524 Common Parameters 525 id Several of these methods accept a user ID as the "id" parameter. The 526 user ID can be either a screen name, or the users numeric ID. To 527 disambiguate, use the "screen_name" or "user_id" parameters, 528 instead. 529 530 For example, These calls are equivalent: 531 532 $nt->create_friend('perl_api'); # screen name 533 $nt->create_friend(1564061); # numeric ID 534 $nt->create_friend({ id => 'perl_api' }); 535 $nt->create_friend({ screen_name => 'perl_api' }); 536 $nt->create_friend({ user_id => 1564061 }); 537 538 However user_id 911 and screen_name 911 are separate Twitter 539 accounts. These calls are NOT equivalent: 540 541 $nt->create_friend(911); # interpreted as screen name 542 $nt->create_friend({ user_id => 911 }); # screen name: richellis 543 544 Whenever the "id" parameter is required and "user_id" and 545 "screen_name" are also parameters, using any one of them satisfies 546 the requirement. 547 548 skip_user 549 The timeline methods all accept an optional "skip_user" parameter. 550 When set to a true value, the statuses returned in a timeline will 551 not contain an entire embedded user HASH. Instead, the user node 552 will contain only an "id" element to indicate the numerical ID of 553 the Twitter user that sent the status. 554 555 Methods 556 account_settings 557 558 Parameters: *none* 559 Required: *none* 560 561 Returns the current trend, geo and sleep time information for the 562 authenticating user. 563 564 Returns: HashRef 565 566 Twitter API documentation: GET account/settings 567 <https://dev.twitter.com/rest/reference/get/account/settings> 568 569 account_totals DEPRECATED 570 571 Parameters: *none* 572 Required: *none* 573 574 Returns the current count of friends, followers, updates (statuses) 575 and favorites of the authenticating user. 576 577 Returns: HashRef 578 579 add_list_member 580 581 Parameters: list_id, slug, user_id, screen_name, owner_screen_name, 582 owner_id 583 Required: *none* 584 585 Add a member to a list. The authenticated user must own the list to 586 be able to add members to it. Note that lists can't have more than 587 500 members. 588 589 Returns: User 590 591 Twitter API documentation: POST lists/members/create 592 <https://dev.twitter.com/rest/reference/post/lists/members/create> 593 594 add_place 595 add_place(name, contained_within, token, lat, long) 596 597 Parameters: name, contained_within, token, lat, long, 598 attribute:street_address, callback 599 Required: name, contained_within, token, lat, long 600 601 Creates a new place object at the given latitude and longitude. 602 603 Before creating a place you need to query "similar_places" with the 604 latitude, longitude and name of the place you wish to create. The 605 query will return an array of places which are similar to the one 606 you wish to create, and a token. If the place you wish to create 607 isn't in the returned array you can use the token with this method 608 to create a new one. 609 610 Returns: Place 611 612 Twitter API documentation: POST geo/place 613 <https://dev.twitter.com/rest/reference/post/geo/place> 614 615 block_exists DEPRECATED 616 block_exists(id) 617 618 Parameters: id, user_id, screen_name, include_entities 619 Required: id 620 621 Returns if the authenticating user is blocking a target user. Will 622 return the blocked user's object if a block exists, and error with 623 HTTP 404 response code otherwise. 624 625 Returns: BasicUser 626 627 blocking 628 alias: blocks_list 629 630 Parameters: cursor, include_entities, skip_status 631 Required: *none* 632 633 Returns an array of user objects that the authenticating user is 634 blocking. 635 636 Returns: ArrayRef[BasicUser] 637 638 Twitter API documentation: GET blocks/list 639 <https://dev.twitter.com/rest/reference/get/blocks/list> 640 641 blocking_ids 642 alias: blocks_ids 643 644 Parameters: cursor, stringify_ids 645 Required: *none* 646 647 Returns an array of numeric user ids the authenticating user is 648 blocking. 649 650 Returns: ArrayRef[Int] 651 652 Twitter API documentation: GET blocks/ids 653 <https://dev.twitter.com/rest/reference/get/blocks/ids> 654 655 contributees DEPRECATED 656 657 Parameters: user_id, screen_name, include_entities, skip_satus 658 Required: *none* 659 660 Returns an array of users that the specified user can contribute to. 661 662 Returns: ArrayRef[User] 663 664 contributors DEPRECATED 665 666 Parameters: user_id, screen_name, include_entities, skip_satus 667 Required: *none* 668 669 Returns an array of users who can contribute to the specified 670 account. 671 672 Returns: ArrayRef[User] 673 674 create_block 675 create_block(id) 676 677 Parameters: user_id, screen_name, include_entities, skip_status 678 Required: id 679 680 Blocks the user specified in the "user_id" or "screen_name" 681 parameter as the authenticating user. Returns the blocked user when 682 successful. You can find out more about blocking in the Twitter 683 Support Knowledge Base. 684 685 Returns: BasicUser 686 687 Twitter API documentation: POST blocks/create 688 <https://dev.twitter.com/rest/reference/post/blocks/create> 689 690 create_favorite 691 create_favorite(id) 692 693 Parameters: id, include_entities 694 Required: id 695 696 Favorites the status specified in the ID parameter as the 697 authenticating user. Returns the favorite status when successful. 698 699 Returns: Status 700 701 Twitter API documentation: POST favorites/create 702 <https://dev.twitter.com/rest/reference/post/favorites/create> 703 704 create_friend 705 alias: follow 706 alias: follow_new 707 alias: create_friendship 708 709 Parameters: user_id, screen_name, follow 710 Required: *none* 711 712 Follows the user specified in the "user_id" or "screen_name" 713 parameter as the authenticating user. Returns the befriended user 714 when successful. Returns a string describing the failure condition 715 when unsuccessful. 716 717 Returns: BasicUser 718 719 Twitter API documentation: POST friendships/create 720 <https://dev.twitter.com/rest/reference/post/friendships/create> 721 722 create_list 723 create_list(name) 724 725 Parameters: list_id, slug, name, mode, description, 726 owner_screen_name, owner_id 727 Required: name 728 729 Creates a new list for the authenticated user. Note that you can't 730 create more than 20 lists per account. 731 732 Returns: List 733 734 Twitter API documentation: POST lists/create 735 <https://dev.twitter.com/rest/reference/post/lists/create> 736 737 create_media_metadata 738 create_media_metadata(media_id) 739 740 Parameters: media_id, alt_text 741 Required: media_id 742 743 Adds metadata -- alt text, in particular -- to a previously uploaded 744 media object, specified by its ID. (One knows this ID via the return 745 value of the preceding "upload" call.) 746 747 The "alt_text" parameter must have as its value a hashref containing 748 a single key-value pair. The key must be "text", and the value is 749 the alt text to assign to the media object. The text must be 400 750 characters or fewer in length. 751 752 Returns: HashRef 753 754 Twitter API documentation: POST media/metadata/create 755 <https://dev.twitter.com/rest/reference/post/media/metadata/create> 756 757 create_mute 758 create_mute(id) 759 760 Parameters: user_id, screen_name 761 Required: id 762 763 Mutes the user specified in the "user_id" or "screen_name" parameter 764 as the authenticating user. Returns the muted user when successful. 765 You can find out more about muting in the Twitter Support Knowledge 766 Base. 767 768 Returns: BasicUser 769 770 Twitter API documentation: POST mutes/users/create 771 <https://dev.twitter.com/rest/reference/post/mutes/users/create> 772 773 create_saved_search 774 create_saved_search(query) 775 776 Parameters: query 777 Required: query 778 779 Creates a saved search for the authenticated user. 780 781 Returns: SavedSearch 782 783 Twitter API documentation: POST saved_searches/create 784 <https://dev.twitter.com/rest/reference/post/saved_searches/create> 785 786 delete_list 787 788 Parameters: owner_screen_name, owner_id, list_id, slug 789 Required: *none* 790 791 Deletes the specified list. The authenticated user must own the list 792 to be able to destroy it. 793 794 Returns: List 795 796 Twitter API documentation: POST lists/destroy 797 <https://dev.twitter.com/rest/reference/post/lists/destroy> 798 799 delete_list_member 800 alias: remove_list_member 801 802 Parameters: list_id, slug, user_id, screen_name, owner_screen_name, 803 owner_id 804 Required: *none* 805 806 Removes the specified member from the list. The authenticated user 807 must be the list's owner to remove members from the list. 808 809 Returns: User 810 811 Twitter API documentation: POST lists/members/destroy 812 <https://dev.twitter.com/rest/reference/post/lists/members/destroy> 813 814 destroy_block 815 destroy_block(id) 816 817 Parameters: user_id, screen_name, include_entities, skip_status 818 Required: id 819 820 Un-blocks the user specified in the "user_id" or "screen_name" 821 parameter as the authenticating user. Returns the un-blocked user 822 when successful. 823 824 Returns: BasicUser 825 826 Twitter API documentation: POST blocks/destroy 827 <https://dev.twitter.com/rest/reference/post/blocks/destroy> 828 829 destroy_direct_message 830 destroy_direct_message(id) 831 832 Parameters: id, include_entities 833 Required: id 834 835 Destroys the direct message specified in the required ID parameter. 836 The authenticating user must be the recipient of the specified 837 direct message. 838 839 Important: this method requires an access token with RWD (read, 840 write, and direct message) permissions. 841 842 Returns: DirectMessage 843 844 Twitter API documentation: POST direct_messages/destroy 845 <https://dev.twitter.com/rest/reference/post/direct_messages/destroy 846 > 847 848 destroy_favorite 849 destroy_favorite(id) 850 851 Parameters: id, include_entities 852 Required: id 853 854 Un-favorites the status specified in the ID parameter as the 855 authenticating user. Returns the un-favorited status. 856 857 Returns: Status 858 859 Twitter API documentation: POST favorites/destroy 860 <https://dev.twitter.com/rest/reference/post/favorites/destroy> 861 862 destroy_friend 863 destroy_friend(id) 864 alias: unfollow 865 alias: destroy_friendship 866 867 Parameters: user_id, screen_name 868 Required: id 869 870 Discontinues friendship with the user specified in the "user_id" or 871 "screen_name" parameter as the authenticating user. Returns the 872 un-friended user when successful. Returns a string describing the 873 failure condition when unsuccessful. 874 875 Returns: BasicUser 876 877 Twitter API documentation: POST friendships/destroy 878 <https://dev.twitter.com/rest/reference/post/friendships/destroy> 879 880 destroy_mute 881 destroy_mute(id) 882 883 Parameters: user_id, screen_name 884 Required: id 885 886 Un-mutes the user specified in the "user_id" or "screen_name" 887 parameter as the authenticating user. Returns the un-muted user when 888 successful. 889 890 Returns: BasicUser 891 892 Twitter API documentation: POST mutes/users/destroy 893 <https://dev.twitter.com/rest/reference/post/mutes/users/destroy> 894 895 destroy_saved_search 896 destroy_saved_search(id) 897 alias: delete_saved_search 898 899 Parameters: id 900 Required: id 901 902 Destroys a saved search. The search, specified by "id", must be 903 owned by the authenticating user. 904 905 Returns: SavedSearch 906 907 Twitter API documentation: POST saved_searches/destroy/:id 908 <https://dev.twitter.com/rest/reference/post/saved_searches/destroy/ 909 :id> 910 911 destroy_status 912 destroy_status(id) 913 914 Parameters: id, trim_user 915 Required: id 916 917 Destroys the status specified by the required ID parameter. The 918 authenticating user must be the author of the specified status. 919 920 Returns: Status 921 922 Twitter API documentation: POST statuses/destroy/:id 923 <https://dev.twitter.com/rest/reference/post/statuses/destroy/:id> 924 925 direct_messages 926 927 Parameters: since_id, max_id, count, page, include_entities, 928 skip_status 929 Required: *none* 930 931 Returns a list of the 20 most recent direct messages sent to the 932 authenticating user including detailed information about the sending 933 and recipient users. 934 935 Important: this method requires an access token with RWD (read, 936 write, and direct message) permissions. 937 938 Returns: ArrayRef[DirectMessage] 939 940 Twitter API documentation: GET direct_messages 941 <https://dev.twitter.com/rest/reference/get/direct_messages> 942 943 disable_notifications DEPRECATED 944 disable_notifications(id) 945 946 Parameters: id, screen_name, include_entities 947 Required: id 948 949 Disables notifications for updates from the specified user to the 950 authenticating user. Returns the specified user when successful. 951 952 Returns: BasicUser 953 954 enable_notifications DEPRECATED 955 enable_notifications(id) 956 957 Parameters: id, screen_name, include_entities 958 Required: id 959 960 Enables notifications for updates from the specified user to the 961 authenticating user. Returns the specified user when successful. 962 963 Returns: BasicUser 964 965 end_session DEPRECATED 966 967 Parameters: *none* 968 Required: *none* 969 970 Ends the session of the authenticating user, returning a null 971 cookie. Use this method to sign users out of client-facing 972 applications like widgets. 973 974 Returns: Error 975 976 favorites 977 978 Parameters: user_id, screen_name, count, since_id, max_id, 979 include_entities 980 Required: *none* 981 982 Returns the 20 most recent favorite statuses for the authenticating 983 user or user specified by the ID parameter. 984 985 Returns: ArrayRef[Status] 986 987 Twitter API documentation: GET favorites/list 988 <https://dev.twitter.com/rest/reference/get/favorites/list> 989 990 followers 991 alias: followers_list 992 993 Parameters: user_id, screen_name, cursor 994 Required: *none* 995 996 Returns a cursored collection of user objects for users following 997 the specified user. 998 999 Returns: HashRef 1000 1001 Twitter API documentation: GET followers/list 1002 <https://dev.twitter.com/rest/reference/get/followers/list> 1003 1004 followers_ids 1005 1006 Parameters: user_id, screen_name, cursor, stringify_ids 1007 Required: *none* 1008 1009 Returns a reference to an array of numeric IDs for every user 1010 following the specified user. The order of the IDs may change from 1011 call to call. To obtain the screen names, pass the arrayref to 1012 "lookup_users". 1013 1014 Use the optional "cursor" parameter to retrieve IDs in pages of 1015 5000. When the "cursor" parameter is used, the return value is a 1016 reference to a hash with keys "previous_cursor", "next_cursor", and 1017 "ids". The value of "ids" is a reference to an array of IDS of the 1018 user's followers. Set the optional "cursor" parameter to -1 to get 1019 the first page of IDs. Set it to the prior return's value of 1020 "previous_cursor" or "next_cursor" to page forward or backwards. 1021 When there are no prior pages, the value of "previous_cursor" will 1022 be 0. When there are no subsequent pages, the value of "next_cursor" 1023 will be 0. 1024 1025 Returns: HashRef|ArrayRef[Int] 1026 1027 Twitter API documentation: GET followers/ids 1028 <https://dev.twitter.com/rest/reference/get/followers/ids> 1029 1030 friends 1031 alias: friends_list 1032 1033 Parameters: user_id, screen_name, cursor 1034 Required: *none* 1035 1036 Returns a cursored collection of user objects for users followed by 1037 the specified user. 1038 1039 Returns: HashRef 1040 1041 Twitter API documentation: GET friends/list 1042 <https://dev.twitter.com/rest/reference/get/friends/list> 1043 1044 friends_ids 1045 alias: following_ids 1046 1047 Parameters: user_id, screen_name, cursor, stringify_ids 1048 Required: *none* 1049 1050 Returns a reference to an array of numeric IDs for every user 1051 followed by the specified user. The order of the IDs is reverse 1052 chronological. 1053 1054 Use the optional "cursor" parameter to retrieve IDs in pages of 1055 5000. When the "cursor" parameter is used, the return value is a 1056 reference to a hash with keys "previous_cursor", "next_cursor", and 1057 "ids". The value of "ids" is a reference to an array of IDS of the 1058 user's friends. Set the optional "cursor" parameter to -1 to get the 1059 first page of IDs. Set it to the prior return's value of 1060 "previous_cursor" or "next_cursor" to page forward or backwards. 1061 When there are no prior pages, the value of "previous_cursor" will 1062 be 0. When there are no subsequent pages, the value of "next_cursor" 1063 will be 0. 1064 1065 Returns: HashRef|ArrayRef[Int] 1066 1067 Twitter API documentation: GET friends/ids 1068 <https://dev.twitter.com/rest/reference/get/friends/ids> 1069 1070 friends_timeline DEPRECATED 1071 alias: following_timeline 1072 1073 Parameters: since_id, max_id, count, exclude_replies, 1074 contributor_details, include_entities, trim_user 1075 Required: *none* 1076 1077 Returns the 20 most recent statuses, including retweets, posted by 1078 the authenticating user and that user's friends. 1079 1080 Returns: ArrayRef[Status] 1081 1082 friendship_exists DEPRECATED 1083 friendship_exists(user_a, user_b) 1084 alias: relationship_exists 1085 alias: follows 1086 1087 Parameters: user_id_a, user_id_b, screen_name_a, screen_name_b, 1088 user_a, user_b 1089 Required: user_a, user_b 1090 1091 This method is provided for backwards compatibility with Twitter API 1092 V1.0. Twitter API V1.1 does not provide an endpoint for this call. 1093 Instead, "show_friendship" is called, the result is inspected, and 1094 an appropriate value is returned which can be evaluated in a boolean 1095 context. 1096 1097 Tests for the existence of friendship between two users. Will return 1098 true if user_a follows user_b, otherwise will return false. 1099 1100 Use of "user_a" and "user_b" is deprecated. It has been preserved 1101 for backwards compatibility, and is used for the two-argument 1102 positional form: 1103 1104 $nt->friendship_exists($user_a, $user_b); 1105 1106 Instead, you should use one of the named argument forms: 1107 1108 $nt->friendship_exists({ user_id_a => $id1, user_id_b => $id2 }); 1109 $nt->friendship_exists({ screen_name_a => $name1, screen_name_b => $name2 }); 1110 1111 Consider using "show_friendship" instead. 1112 1113 Returns: Bool 1114 1115 friendships_incoming 1116 alias: incoming_friendships 1117 1118 Parameters: cursor, stringify_ids 1119 Required: *none* 1120 1121 Returns an HASH ref with an array of numeric IDs in the "ids" 1122 element for every user who has a pending request to follow the 1123 authenticating user. 1124 1125 Returns: HashRef 1126 1127 Twitter API documentation: GET friendships/incoming 1128 <https://dev.twitter.com/rest/reference/get/friendships/incoming> 1129 1130 friendships_outgoing 1131 alias: outgoing_friendships 1132 1133 Parameters: cursor, stringify_ids 1134 Required: *none* 1135 1136 Returns an HASH ref with an array of numeric IDs in the "ids" 1137 element for every protected user for whom the authenticating user 1138 has a pending follow request. 1139 1140 Returns: HashRef 1141 1142 Twitter API documentation: GET friendships/outgoing 1143 <https://dev.twitter.com/rest/reference/get/friendships/outgoing> 1144 1145 geo_id 1146 geo_id(place_id) 1147 1148 Parameters: place_id 1149 Required: place_id 1150 1151 Returns details of a place returned from the "reverse_geocode" 1152 method. 1153 1154 Returns: HashRef 1155 1156 Twitter API documentation: GET geo/id/:place_id 1157 <https://dev.twitter.com/rest/reference/get/geo/id/:place_id> 1158 1159 geo_search 1160 1161 Parameters: lat, long, query, ip, granularity, accuracy, 1162 max_results, contained_within, attribute:street_address, callback 1163 Required: *none* 1164 1165 Search for places that can be attached to a statuses/update. Given a 1166 latitude and a longitude pair, an IP address, or a name, this 1167 request will return a list of all the valid places that can be used 1168 as the place_id when updating a status. 1169 1170 Conceptually, a query can be made from the user's location, retrieve 1171 a list of places, have the user validate the location he or she is 1172 at, and then send the ID of this location with a call to 1173 statuses/update. 1174 1175 This is the recommended method to use find places that can be 1176 attached to statuses/update. Unlike geo/reverse_geocode which 1177 provides raw data access, this endpoint can potentially re-order 1178 places with regards to the user who is authenticated. This approach 1179 is also preferred for interactive place matching with the user. 1180 1181 Returns: HashRef 1182 1183 Twitter API documentation: GET geo/search 1184 <https://dev.twitter.com/rest/reference/get/geo/search> 1185 1186 get_configuration 1187 1188 Parameters: *none* 1189 Required: *none* 1190 1191 Returns the current configuration used by Twitter including 1192 twitter.com slugs which are not usernames, maximum photo 1193 resolutions, and t.co URL lengths. 1194 1195 It is recommended applications request this endpoint when they are 1196 loaded, but no more than once a day. 1197 1198 Returns: HashRef 1199 1200 Twitter API documentation: GET help/configuration 1201 <https://dev.twitter.com/rest/reference/get/help/configuration> 1202 1203 get_languages 1204 1205 Parameters: *none* 1206 Required: *none* 1207 1208 Returns the list of languages supported by Twitter along with their 1209 ISO 639-1 code. The ISO 639-1 code is the two letter value to use if 1210 you include lang with any of your requests. 1211 1212 Returns: ArrayRef[Lanugage] 1213 1214 Twitter API documentation: GET help/languages 1215 <https://dev.twitter.com/rest/reference/get/help/languages> 1216 1217 get_list 1218 alias: show_list 1219 1220 Parameters: list_id, slug, owner_screen_name, owner_id 1221 Required: *none* 1222 1223 Returns the specified list. Private lists will only be shown if the 1224 authenticated user owns the specified list. 1225 1226 Returns: List 1227 1228 Twitter API documentation: GET lists/show 1229 <https://dev.twitter.com/rest/reference/get/lists/show> 1230 1231 get_lists 1232 alias: list_lists 1233 alias: all_subscriptions 1234 1235 Parameters: user_id, screen_name, reverse 1236 Required: *none* 1237 1238 Returns all lists the authenticating or specified user subscribes 1239 to, including their own. The user is specified using the user_id or 1240 screen_name parameters. If no user is given, the authenticating user 1241 is used. 1242 1243 A maximum of 100 results will be returned by this call. Subscribed 1244 lists are returned first, followed by owned lists. This means that 1245 if a user subscribes to 90 lists and owns 20 lists, this method 1246 returns 90 subscriptions and 10 owned lists. The reverse method 1247 returns owned lists first, so with "reverse =" 1>, 20 owned lists 1248 and 80 subscriptions would be returned. If your goal is to obtain 1249 every list a user owns or subscribes to, use <list_ownerships> 1250 and/or "list_subscriptions" instead. 1251 1252 Returns: Hashref 1253 1254 Twitter API documentation: GET lists/list 1255 <https://dev.twitter.com/rest/reference/get/lists/list> 1256 1257 get_privacy_policy 1258 1259 Parameters: *none* 1260 Required: *none* 1261 1262 Returns Twitter's privacy policy. 1263 1264 Returns: HashRef 1265 1266 Twitter API documentation: GET help/privacy 1267 <https://dev.twitter.com/rest/reference/get/help/privacy> 1268 1269 get_tos 1270 1271 Parameters: *none* 1272 Required: *none* 1273 1274 Returns the Twitter Terms of Service. These are not the same as the 1275 Developer Rules of the Road. 1276 1277 Returns: HashRef 1278 1279 Twitter API documentation: GET help/tos 1280 <https://dev.twitter.com/rest/reference/get/help/tos> 1281 1282 home_timeline 1283 1284 Parameters: since_id, max_id, count, exclude_replies, 1285 contributor_details, include_entities, trim_user 1286 Required: *none* 1287 1288 Returns the 20 most recent statuses, including retweets, posted by 1289 the authenticating user and that user's friends. 1290 1291 Returns: ArrayRef[Status] 1292 1293 Twitter API documentation: GET statuses/home_timeline 1294 <https://dev.twitter.com/rest/reference/get/statuses/home_timeline> 1295 1296 list_members 1297 1298 Parameters: list_id, slug, owner_screen_name, owner_id, cursor, 1299 include_entities, skip_status 1300 Required: *none* 1301 1302 Returns the members of the specified list. Private list members will 1303 only be shown if the authenticated user owns the specified list. 1304 1305 Returns: Hashref 1306 1307 Twitter API documentation: GET lists/members 1308 <https://dev.twitter.com/rest/reference/get/lists/members> 1309 1310 list_memberships 1311 1312 Parameters: user_id, screen_name, cursor, filter_to_owned_lists 1313 Required: *none* 1314 1315 Returns the lists the specified user has been added to. If user_id 1316 or screen_name are not provided the memberships for the 1317 authenticating user are returned. 1318 1319 Returns: Hashref 1320 1321 Twitter API documentation: GET lists/memberships 1322 <https://dev.twitter.com/rest/reference/get/lists/memberships> 1323 1324 list_ownerships 1325 1326 Parameters: user_id, screen_name, count, cursor 1327 Required: *none* 1328 1329 Obtain a collection of the lists owned by the specified Twitter 1330 user. Private lists will only be shown if the authenticated user is 1331 also the owner of the lists. 1332 1333 Returns: ArrayRef[List] 1334 1335 Twitter API documentation: GET lists/ownerships 1336 <https://dev.twitter.com/rest/reference/get/lists/ownerships> 1337 1338 list_statuses 1339 1340 Parameters: list_id, slug, owner_screen_name, owner_id, since_id, 1341 max_id, count, include_entities, include_rts 1342 Required: *none* 1343 1344 Returns tweet timeline for members of the specified list. 1345 Historically, retweets were not available in list timeline responses 1346 but you can now use the include_rts=true parameter to additionally 1347 receive retweet objects. 1348 1349 Returns: ArrayRef[Status] 1350 1351 Twitter API documentation: GET lists/statuses 1352 <https://dev.twitter.com/rest/reference/get/lists/statuses> 1353 1354 list_subscribers 1355 1356 Parameters: list_id, slug, owner_screen_name, owner_id, cursor, 1357 include_entities, skip_status 1358 Required: *none* 1359 1360 Returns the subscribers of the specified list. Private list 1361 subscribers will only be shown if the authenticated user owns the 1362 specified list. 1363 1364 Returns: Hashref 1365 1366 Twitter API documentation: GET lists/subscribers 1367 <https://dev.twitter.com/rest/reference/get/lists/subscribers> 1368 1369 list_subscriptions 1370 alias: subscriptions 1371 1372 Parameters: user_id, screen_name, count, cursor 1373 Required: *none* 1374 1375 Obtain a collection of the lists the specified user is subscribed 1376 to, 20 lists per page by default. Does not include the user's own 1377 lists. 1378 1379 Returns: ArrayRef[List] 1380 1381 Twitter API documentation: GET lists/subscriptions 1382 <https://dev.twitter.com/rest/reference/get/lists/subscriptions> 1383 1384 lookup_friendships 1385 1386 Parameters: user_id, screen_name 1387 Required: *none* 1388 1389 Returns the relationship of the authenticating user to the comma 1390 separated list or ARRAY ref of up to 100 screen_names or user_ids 1391 provided. Values for connections can be: following, 1392 following_requested, followed_by, none. Requires authentication. 1393 1394 Returns: ArrayRef 1395 1396 Twitter API documentation: GET friendships/lookup 1397 <https://dev.twitter.com/rest/reference/get/friendships/lookup> 1398 1399 lookup_statuses 1400 lookup_statuses(id) 1401 1402 Parameters: id, include_entities, trim_user, map 1403 Required: id 1404 1405 Returns a hash reference of tweets from an arbitrary set of ids. 1406 1407 Returns: HashRef 1408 1409 Twitter API documentation: GET statuses/lookup 1410 <https://dev.twitter.com/rest/reference/get/statuses/lookup> 1411 1412 lookup_users 1413 1414 Parameters: user_id, screen_name, include_entities 1415 Required: *none* 1416 1417 Return up to 100 users worth of extended information, specified by 1418 either ID, screen name, or combination of the two. The author's most 1419 recent status (if the authenticating user has permission) will be 1420 returned inline. This method is rate limited to 1000 calls per hour. 1421 1422 This method will accept user IDs or screen names as either a comma 1423 delimited string, or as an ARRAY ref. It will also accept arguments 1424 in the normal HASHREF form or as a simple list of named arguments. 1425 I.e., any of the following forms are acceptable: 1426 1427 $nt->lookup_users({ user_id => '1234,6543,3333' }); 1428 $nt->lookup_users(user_id => '1234,6543,3333'); 1429 $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] }); 1430 $nt->lookup_users({ screen_name => 'fred,barney,wilma' }); 1431 $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']); 1432 1433 $nt->lookup_users( 1434 screen_name => ['fred', 'barney' ], 1435 user_id => '4321,6789', 1436 ); 1437 1438 Returns: ArrayRef[User] 1439 1440 Twitter API documentation: GET users/lookup 1441 <https://dev.twitter.com/rest/reference/get/users/lookup> 1442 1443 members_create_all 1444 alias: add_list_members 1445 1446 Parameters: list_id, slug, owner_screen_name, owner_id 1447 Required: *none* 1448 1449 Adds multiple members to a list, by specifying a reference to an 1450 array or a comma-separated list of member ids or screen names. The 1451 authenticated user must own the list to be able to add members to 1452 it. Note that lists can't have more than 500 members, and you are 1453 limited to adding up to 100 members to a list at a time with this 1454 method. 1455 1456 Returns: List 1457 1458 Twitter API documentation: POST lists/members/create_all 1459 <https://dev.twitter.com/rest/reference/post/lists/members/create_al 1460 l> 1461 1462 members_destroy_all 1463 alias: remove_list_members 1464 1465 Parameters: list_id, slug, user_id, screen_name, owner_screen_name, 1466 owner_id 1467 Required: *none* 1468 1469 Removes multiple members from a list, by specifying a reference to 1470 an array of member ids or screen names, or a string of comma 1471 separated user ids or screen names. The authenticated user must own 1472 the list to be able to remove members from it. Note that lists can't 1473 have more than 500 members, and you are limited to removing up to 1474 100 members to a list at a time with this method. 1475 1476 Please note that there can be issues with lists that rapidly remove 1477 and add memberships. Take care when using these methods such that 1478 you are not too rapidly switching between removals and adds on the 1479 same list. 1480 1481 Returns: List 1482 1483 Twitter API documentation: POST lists/members/destroy_all 1484 <https://dev.twitter.com/rest/reference/post/lists/members/destroy_a 1485 ll> 1486 1487 mentions 1488 alias: replies 1489 alias: mentions_timeline 1490 1491 Parameters: since_id, max_id, count, trim_user, include_entities, 1492 contributor_details 1493 Required: *none* 1494 1495 Returns the 20 most recent mentions (statuses containing @username) 1496 for the authenticating user. 1497 1498 Returns: ArrayRef[Status] 1499 1500 Twitter API documentation: GET statuses/mentions_timeline 1501 <https://dev.twitter.com/rest/reference/get/statuses/mentions_timeli 1502 ne> 1503 1504 mutes 1505 mutes(cursor) 1506 alias: muting_ids 1507 alias: muted_ids 1508 1509 Parameters: cursor 1510 Required: *none* 1511 1512 Returns an array of numeric user ids the authenticating user has 1513 muted. 1514 1515 Returns: ArrayRef[Int] 1516 1517 Twitter API documentation: GET mutes/users/ids 1518 <https://dev.twitter.com/rest/reference/get/mutes/users/ids> 1519 1520 muting 1521 alias: mutes_list 1522 1523 Parameters: cursor, include_entities, skip_status 1524 Required: *none* 1525 1526 Returns an array of user objects that the authenticating user is 1527 muting. 1528 1529 Returns: ArrayRef[BasicUser] 1530 1531 Twitter API documentation: GET mutes/users/list 1532 <https://dev.twitter.com/rest/reference/get/mutes/users/list> 1533 1534 new_direct_message 1535 new_direct_message(text) 1536 1537 Parameters: user_id, screen_name, text 1538 Required: text 1539 1540 Sends a new direct message to the specified user from the 1541 authenticating user. Requires both the user and text parameters. 1542 Returns the sent message when successful. In order to support 1543 numeric screen names, the "screen_name" or "user_id" parameters may 1544 be used instead of "user". 1545 1546 Important: this method requires an access token with RWD (read, 1547 write, and direct message) permissions. 1548 1549 Returns: DirectMessage 1550 1551 Twitter API documentation: POST direct_messages/new 1552 <https://dev.twitter.com/rest/reference/post/direct_messages/new> 1553 1554 no_retweet_ids 1555 alias: no_retweets_ids 1556 1557 Parameters: *none* 1558 Required: *none* 1559 1560 Returns an ARRAY ref of user IDs for which the authenticating user 1561 does not want to receive retweets. 1562 1563 Returns: ArrayRef[UserIDs] 1564 1565 Twitter API documentation: GET friendships/no_retweets/ids 1566 <https://dev.twitter.com/rest/reference/get/friendships/no_retweets/ 1567 ids> 1568 1569 oembed 1570 1571 Parameters: id, url, maxwidth, hide_media, hide_thread, omit_script, 1572 align, related, lang 1573 Required: *none* 1574 1575 Returns information allowing the creation of an embedded 1576 representation of a Tweet on third party sites. See the oEmbed 1577 <http://oembed.com/> specification for information about the 1578 response format. 1579 1580 While this endpoint allows a bit of customization for the final 1581 appearance of the embedded Tweet, be aware that the appearance of 1582 the rendered Tweet may change over time to be consistent with 1583 Twitter's Display Requirements 1584 <https://dev.twitter.com/terms/display-requirements>. Do not rely on 1585 any class or id parameters to stay constant in the returned markup. 1586 1587 Returns: Status 1588 1589 Twitter API documentation: GET statuses/oembed 1590 <https://dev.twitter.com/rest/reference/get/statuses/oembed> 1591 1592 profile_banner 1593 1594 Parameters: user_id, screen_name 1595 Required: *none* 1596 1597 Returns a hash reference mapping available size variations to URLs 1598 that can be used to retrieve each variation of the banner. 1599 1600 Returns: HashRef 1601 1602 Twitter API documentation: GET users/profile_banner 1603 <https://dev.twitter.com/rest/reference/get/users/profile_banner> 1604 1605 rate_limit_status 1606 rate_limit_status(resources) 1607 1608 Parameters: resources 1609 Required: *none* 1610 1611 Returns the remaining number of API requests available to the 1612 authenticated user before the API limit is reached for the current 1613 hour. 1614 1615 Use "->rate_limit_status({ authenticate => 0 })" to force an 1616 unauthenticated call, which will return the status for the IP 1617 address rather than the authenticated user. (Note: for a web 1618 application, this is the server's IP address.) 1619 1620 Returns: RateLimitStatus 1621 1622 Twitter API documentation: GET application/rate_limit_status 1623 <https://dev.twitter.com/rest/reference/get/application/rate_limit_s 1624 tatus> 1625 1626 related_results DEPRECATED 1627 related_results(id) 1628 1629 Parameters: id 1630 Required: id 1631 1632 If available, returns an array of replies and mentions related to 1633 the specified status. There is no guarantee there will be any 1634 replies or mentions in the response. This method is only available 1635 to users who have access to #newtwitter. Requires authentication. 1636 1637 Returns: ArrayRef[Status] 1638 1639 remove_profile_banner 1640 1641 Parameters: *none* 1642 Required: *none* 1643 1644 Removes the uploaded profile banner for the authenticating user. 1645 1646 Returns: Nothing 1647 1648 Twitter API documentation: POST account/remove_profile_banner 1649 <https://dev.twitter.com/rest/reference/post/account/remove_profile_ 1650 banner> 1651 1652 report_spam 1653 report_spam(id) 1654 1655 Parameters: user_id, screen_name 1656 Required: id 1657 1658 The user specified in the id is blocked by the authenticated user 1659 and reported as a spammer. 1660 1661 Returns: User 1662 1663 Twitter API documentation: POST users/report_spam 1664 <https://dev.twitter.com/rest/reference/post/users/report_spam> 1665 1666 retweet 1667 retweet(id) 1668 1669 Parameters: idtrim_user 1670 Required: id 1671 1672 Retweets a tweet. 1673 1674 Returns: Status 1675 1676 Twitter API documentation: POST statuses/retweet/:id 1677 <https://dev.twitter.com/rest/reference/post/statuses/retweet/:id> 1678 1679 retweeted_by DEPRECATED 1680 retweeted_by(id) 1681 1682 Parameters: id, count, page, trim_user, include_entities 1683 Required: id 1684 1685 Returns up to 100 users who retweeted the status identified by "id". 1686 1687 Returns: ArrayRef[User] 1688 1689 retweeted_by_ids DEPRECATED 1690 retweeted_by_ids(id) 1691 1692 Parameters: id, count, page, trim_user, include_entities 1693 Required: id 1694 1695 Returns the IDs of up to 100 users who retweeted the status 1696 identified by "id". 1697 1698 Returns: ArrayRef[User] 1699 1700 retweeted_by_me DEPRECATED 1701 1702 Parameters: since_id, max_id, count, page, trim_user, 1703 include_entities 1704 Required: *none* 1705 1706 Returns the 20 most recent retweets posted by the authenticating 1707 user. 1708 1709 Returns: ArrayRef[Status] 1710 1711 retweeted_by_user DEPRECATED 1712 retweeted_by_user(id) 1713 1714 Parameters: id, user_id, screen_name 1715 Required: id 1716 1717 Returns the 20 most recent retweets posted by the specified user. 1718 The user is specified using the user_id or screen_name parameters. 1719 This method is identical to "retweeted_by_me" except you can choose 1720 the user to view. Does not require authentication, unless the user 1721 is protected. 1722 1723 Returns: ArrayRef 1724 1725 retweeted_to_me DEPRECATED 1726 1727 Parameters: since_id, max_id, count, page 1728 Required: *none* 1729 1730 Returns the 20 most recent retweets posted by the authenticating 1731 user's friends. 1732 1733 Returns: ArrayRef[Status] 1734 1735 retweeted_to_user DEPRECATED 1736 retweeted_to_user(id) 1737 1738 Parameters: id, user_id, screen_name 1739 Required: id 1740 1741 Returns the 20 most recent retweets posted by users the specified 1742 user follows. The user is specified using the user_id or screen_name 1743 parameters. This method is identical to "retweeted_to_me" except you 1744 can choose the user to view. Does not require authentication, unless 1745 the user is protected. 1746 1747 Returns: ArrayRef 1748 1749 retweeters_ids 1750 retweeters_ids(id) 1751 1752 Parameters: id, cursor, stringify_ids 1753 Required: id 1754 1755 Returns a collection of up to 100 user IDs belonging to users who 1756 have retweeted the tweet specified by the id parameter. 1757 1758 This method offers similar data to "retweets" and replaces API v1's 1759 "retweeted_by_ids" method. 1760 1761 Returns: HashRef 1762 1763 Twitter API documentation: GET statuses/retweeters/ids 1764 <https://dev.twitter.com/rest/reference/get/statuses/retweeters/ids> 1765 1766 retweets 1767 retweets(id) 1768 1769 Parameters: id, count, trim_user 1770 Required: id 1771 1772 Returns up to 100 of the first retweets of a given tweet. 1773 1774 Returns: Arrayref[Status] 1775 1776 Twitter API documentation: GET statuses/retweets/:id 1777 <https://dev.twitter.com/rest/reference/get/statuses/retweets/:id> 1778 1779 retweets_of_me 1780 alias: retweeted_of_me 1781 1782 Parameters: since_id, max_id, count, trim_user, include_entities, 1783 include_user_entities 1784 Required: *none* 1785 1786 Returns the 20 most recent tweets of the authenticated user that 1787 have been retweeted by others. 1788 1789 Returns: ArrayRef[Status] 1790 1791 Twitter API documentation: GET statuses/retweets_of_me 1792 <https://dev.twitter.com/rest/reference/get/statuses/retweets_of_me> 1793 1794 reverse_geocode 1795 reverse_geocode(lat, long) 1796 1797 Parameters: lat, long, accuracy, granularity, max_results, callback 1798 Required: lat, long 1799 1800 Search for places (cities and neighborhoods) that can be attached to 1801 a statuses/update. Given a latitude and a longitude, return a list 1802 of all the valid places that can be used as a place_id when updating 1803 a status. Conceptually, a query can be made from the user's 1804 location, retrieve a list of places, have the user validate the 1805 location he or she is at, and then send the ID of this location up 1806 with a call to statuses/update. 1807 1808 There are multiple granularities of places that can be returned -- 1809 "neighborhoods", "cities", etc. At this time, only United States 1810 data is available through this method. 1811 1812 lat Required. The latitude to query about. Valid ranges are -90.0 to 1813 +90.0 (North is positive) inclusive. 1814 1815 long 1816 Required. The longitude to query about. Valid ranges are -180.0 1817 to +180.0 (East is positive) inclusive. 1818 1819 accuracy 1820 Optional. A hint on the "region" in which to search. If a 1821 number, then this is a radius in meters, but it can also take a 1822 string that is suffixed with ft to specify feet. If this is not 1823 passed in, then it is assumed to be 0m. If coming from a device, 1824 in practice, this value is whatever accuracy the device has 1825 measuring its location (whether it be coming from a GPS, WiFi 1826 triangulation, etc.). 1827 1828 granularity 1829 Optional. The minimal granularity of data to return. If this is 1830 not passed in, then "neighborhood" is assumed. "city" can also 1831 be passed. 1832 1833 max_results 1834 Optional. A hint as to the number of results to return. This 1835 does not guarantee that the number of results returned will 1836 equal max_results, but instead informs how many "nearby" results 1837 to return. Ideally, only pass in the number of places you intend 1838 to display to the user here. 1839 1840 Returns: HashRef 1841 1842 Twitter API documentation: GET geo/reverse_geocode 1843 <https://dev.twitter.com/rest/reference/get/geo/reverse_geocode> 1844 1845 saved_searches 1846 1847 Parameters: *none* 1848 Required: *none* 1849 1850 Returns the authenticated user's saved search queries. 1851 1852 Returns: ArrayRef[SavedSearch] 1853 1854 Twitter API documentation: GET saved_searches/list 1855 <https://dev.twitter.com/rest/reference/get/saved_searches/list> 1856 1857 search 1858 search(q) 1859 1860 Parameters: q, count, callback, lang, locale, rpp, since_id, max_id, 1861 until, geocode, result_type, include_entities 1862 Required: q 1863 1864 Returns a HASH reference with some meta-data about the query 1865 including the "next_page", "refresh_url", and "max_id". The statuses 1866 are returned in "results". To iterate over the results, use 1867 something similar to: 1868 1869 my $r = $nt->search($search_term); 1870 for my $status ( @{$r->{statuses}} ) { 1871 print "$status->{text}\n"; 1872 } 1873 1874 Returns: HashRef 1875 1876 Twitter API documentation: GET search/tweets 1877 <https://dev.twitter.com/rest/reference/get/search/tweets> 1878 1879 sent_direct_messages 1880 alias: direct_messages_sent 1881 1882 Parameters: since_id, max_id, page, count, include_entities 1883 Required: *none* 1884 1885 Returns a list of the 20 most recent direct messages sent by the 1886 authenticating user including detailed information about the sending 1887 and recipient users. 1888 1889 Important: this method requires an access token with RWD (read, 1890 write, and direct message) permissions. 1891 1892 Returns: ArrayRef[DirectMessage] 1893 1894 Twitter API documentation: GET direct_messages/sent 1895 <https://dev.twitter.com/rest/reference/get/direct_messages/sent> 1896 1897 show_direct_message 1898 show_direct_message(id) 1899 1900 Parameters: id 1901 Required: id 1902 1903 Returns a single direct message, specified by an id parameter. Like 1904 the "direct_messages" request, this method will include the user 1905 objects of the sender and recipient. Requires authentication. 1906 1907 Important: this method requires an access token with RWD (read, 1908 write, and direct message) permissions. 1909 1910 Returns: HashRef 1911 1912 Twitter API documentation: GET direct_messages/show 1913 <https://dev.twitter.com/rest/reference/get/direct_messages/show> 1914 1915 show_friendship 1916 alias: show_relationship 1917 1918 Parameters: source_id, source_screen_name, target_id, 1919 target_screen_name 1920 Required: *none* 1921 1922 Returns detailed information about the relationship between two 1923 users. 1924 1925 Returns: Relationship 1926 1927 Twitter API documentation: GET friendships/show 1928 <https://dev.twitter.com/rest/reference/get/friendships/show> 1929 1930 show_list_member 1931 alias: is_list_member 1932 1933 Parameters: owner_screen_name, owner_id, list_id, slug, user_id, 1934 screen_name, include_entities, skip_status 1935 Required: *none* 1936 1937 Check if the specified user is a member of the specified list. 1938 Returns the user or undef. 1939 1940 Returns: Maybe[User] 1941 1942 Twitter API documentation: GET lists/members/show 1943 <https://dev.twitter.com/rest/reference/get/lists/members/show> 1944 1945 show_list_subscriber 1946 alias: is_list_subscriber 1947 alias: is_subscriber_lists 1948 1949 Parameters: owner_screen_name, owner_id, list_id, slug, user_id, 1950 screen_name, include_entities, skip_status 1951 Required: *none* 1952 1953 Returns the user if they are a subscriber. 1954 1955 Returns: User 1956 1957 Twitter API documentation: GET lists/subscribers/show 1958 <https://dev.twitter.com/rest/reference/get/lists/subscribers/show> 1959 1960 show_saved_search 1961 show_saved_search(id) 1962 1963 Parameters: id 1964 Required: id 1965 1966 Retrieve the data for a saved search, by "id", owned by the 1967 authenticating user. 1968 1969 Returns: SavedSearch 1970 1971 Twitter API documentation: GET saved_searches/show/:id 1972 <https://dev.twitter.com/rest/reference/get/saved_searches/show/:id> 1973 1974 show_status 1975 show_status(id) 1976 1977 Parameters: id, trim_user, include_entities, include_my_retweet 1978 Required: id 1979 1980 Returns a single status, specified by the id parameter. The status's 1981 author will be returned inline. 1982 1983 Returns: Status 1984 1985 Twitter API documentation: GET statuses/show/:id 1986 <https://dev.twitter.com/rest/reference/get/statuses/show/:id> 1987 1988 show_user 1989 1990 Parameters: user_id, screen_name, include_entities 1991 Required: *none* 1992 1993 Returns extended information of a given user, specified by ID or 1994 screen name as per the required id parameter. This information 1995 includes design settings, so third party developers can theme their 1996 widgets according to a given user's preferences. You must be 1997 properly authenticated to request the page of a protected user. 1998 1999 Returns: ExtendedUser 2000 2001 Twitter API documentation: GET users/show 2002 <https://dev.twitter.com/rest/reference/get/users/show> 2003 2004 similar_places 2005 similar_places(lat, long, name) 2006 2007 Parameters: lat, long, name, contained_within, 2008 attribute:street_address, callback 2009 Required: lat, long, name 2010 2011 Locates places near the given coordinates which are similar in name. 2012 2013 Conceptually you would use this method to get a list of known places 2014 to choose from first. Then, if the desired place doesn't exist, make 2015 a request to "add_place" to create a new one. 2016 2017 The token contained in the response is the token needed to be able 2018 to create a new place. 2019 2020 Returns: HashRef 2021 2022 Twitter API documentation: GET geo/similar_places 2023 <https://dev.twitter.com/rest/reference/get/geo/similar_places> 2024 2025 subscribe_list 2026 2027 Parameters: owner_screen_name, owner_id, list_id, slug 2028 Required: *none* 2029 2030 Subscribes the authenticated user to the specified list. 2031 2032 Returns: List 2033 2034 Twitter API documentation: POST lists/subscribers/create 2035 <https://dev.twitter.com/rest/reference/post/lists/subscribers/creat 2036 e> 2037 2038 suggestion_categories 2039 2040 Parameters: *none* 2041 Required: *none* 2042 2043 Returns the list of suggested user categories. The category slug can 2044 be used in the "user_suggestions" API method get the users in that 2045 category . Does not require authentication. 2046 2047 Returns: ArrayRef 2048 2049 Twitter API documentation: GET users/suggestions 2050 <https://dev.twitter.com/rest/reference/get/users/suggestions> 2051 2052 test DEPRECATED 2053 2054 Parameters: *none* 2055 Required: *none* 2056 2057 Returns the string "ok" status code. 2058 2059 Returns: Hash 2060 2061 trends_available 2062 2063 Parameters: *none* 2064 Required: *none* 2065 2066 Returns the locations with trending topic information. The response 2067 is an array of "locations" that encode the location's WOEID (a 2068 Yahoo! Where On Earth ID 2069 <http://developer.yahoo.com/geo/geoplanet/>) and some other 2070 human-readable information such as a the location's canonical name 2071 and country. 2072 2073 For backwards compatibility, this method accepts optional "lat" and 2074 "long" parameters. You should call "trends_closest" directly, 2075 instead. 2076 2077 Use the WOEID returned in the location object to query trends for a 2078 specific location. 2079 2080 Returns: ArrayRef[Location] 2081 2082 Twitter API documentation: GET trends/available 2083 <https://dev.twitter.com/rest/reference/get/trends/available> 2084 2085 trends_closest 2086 2087 Parameters: lat, long 2088 Required: *none* 2089 2090 Returns the locations with trending topic information. The response 2091 is an array of "locations" that encode the location's WOEID (a 2092 Yahoo! Where On Earth ID 2093 <http://developer.yahoo.com/geo/geoplanet/>) and some other 2094 human-readable information such as a the location's canonical name 2095 and country. The results are sorted by distance from that location, 2096 nearest to farthest. 2097 2098 Use the WOEID returned in the location object to query trends for a 2099 specific location. 2100 2101 Returns: ArrayRef[Location] 2102 2103 Twitter API documentation: GET trends/closest 2104 <https://dev.twitter.com/rest/reference/get/trends/closest> 2105 2106 trends_current DEPRECATED 2107 trends_current(exclude) 2108 2109 Parameters: exclude 2110 Required: *none* 2111 2112 Returns the current top ten trending topics on Twitter. The response 2113 includes the time of the request, the name of each trending topic, 2114 and query used on Twitter Search results page for that topic. 2115 2116 Returns: HashRef 2117 2118 trends_daily DEPRECATED 2119 2120 Parameters: date, exclude 2121 Required: *none* 2122 2123 Returns the top 20 trending topics for each hour in a given day. 2124 2125 Returns: HashRef 2126 2127 trends_place 2128 trends_place(id) 2129 alias: trends_location 2130 2131 Parameters: id, exclude 2132 Required: id 2133 2134 Returns the top 10 trending topics for a specific WOEID. The 2135 response is an array of "trend" objects that encode the name of the 2136 trending topic, the query parameter that can be used to search for 2137 the topic on Search, and the direct URL that can be issued against 2138 Search. This information is cached for five minutes, and therefore 2139 users are discouraged from querying these endpoints faster than once 2140 every five minutes. Global trends information is also available from 2141 this API by using a WOEID of 1. 2142 2143 Returns: ArrayRef[Trend] 2144 2145 Twitter API documentation: GET trends/place 2146 <https://dev.twitter.com/rest/reference/get/trends/place> 2147 2148 trends_weekly DEPRECATED 2149 2150 Parameters: date, exclude 2151 Required: *none* 2152 2153 Returns the top 30 trending topics for each day in a given week. 2154 2155 Returns: HashRef 2156 2157 unsubscribe_list 2158 2159 Parameters: list_id, slug, owner_screen_name, owner_id 2160 Required: *none* 2161 2162 Unsubscribes the authenticated user from the specified list. 2163 2164 Returns: List 2165 2166 Twitter API documentation: POST lists/subscribers/destroy 2167 <https://dev.twitter.com/rest/reference/post/lists/subscribers/destr 2168 oy> 2169 2170 update 2171 update(status) 2172 2173 Parameters: attachment_url, display_coordinates, 2174 in_reply_to_status_id, lat, long, media_ids, place_id, status, 2175 trim_user 2176 Required: status 2177 2178 Updates the authenticating user's status. Requires the status 2179 parameter specified. A status update with text identical to the 2180 authenticating user's current status will be ignored. 2181 2182 status 2183 Required. The text of your status update. URL encode as 2184 necessary. Statuses over 140 characters will cause a 403 error 2185 to be returned from the API. 2186 2187 in_reply_to_status_id 2188 Optional. The ID of an existing status that the update is in 2189 reply to. o Note: This parameter will be ignored unless the 2190 author of the tweet this parameter references is mentioned 2191 within the status text. Therefore, you must include @username, 2192 where username is the author of the referenced tweet, within the 2193 update. 2194 2195 lat Optional. The location's latitude that this tweet refers to. The 2196 valid ranges for latitude is -90.0 to +90.0 (North is positive) 2197 inclusive. This parameter will be ignored if outside that range, 2198 if it is not a number, if geo_enabled is disabled, or if there 2199 not a corresponding long parameter with this tweet. 2200 2201 long 2202 Optional. The location's longitude that this tweet refers to. 2203 The valid ranges for longitude is -180.0 to +180.0 (East is 2204 positive) inclusive. This parameter will be ignored if outside 2205 that range, if it is not a number, if geo_enabled is disabled, 2206 or if there not a corresponding lat parameter with this tweet. 2207 2208 place_id 2209 Optional. The place to attach to this status update. Valid 2210 place_ids can be found by querying "reverse_geocode". 2211 2212 display_coordinates 2213 Optional. By default, geo-tweets will have their coordinates 2214 exposed in the status object (to remain backwards compatible 2215 with existing API applications). To turn off the display of the 2216 precise latitude and longitude (but keep the contextual location 2217 information), pass "display_coordinates =" 0> on the status 2218 update. 2219 2220 Returns: Status 2221 2222 Twitter API documentation: POST statuses/update 2223 <https://dev.twitter.com/rest/reference/post/statuses/update> 2224 2225 update_account_settings 2226 2227 Parameters: trend_location_woid, sleep_time_enabled, 2228 start_sleep_time, end_sleep_time, time_zone, lang 2229 Required: *none* 2230 2231 Updates the authenticating user's settings. 2232 2233 Returns: HashRef 2234 2235 Twitter API documentation: POST account/settings 2236 <https://dev.twitter.com/rest/reference/post/account/settings> 2237 2238 update_delivery_device 2239 update_delivery_device(device) 2240 2241 Parameters: device, include_entities 2242 Required: device 2243 2244 Sets which device Twitter delivers updates to for the authenticating 2245 user. Sending none as the device parameter will disable SMS updates. 2246 2247 Returns: BasicUser 2248 2249 Twitter API documentation: POST account/update_delivery_device 2250 <https://dev.twitter.com/rest/reference/post/account/update_delivery 2251 _device> 2252 2253 update_friendship 2254 2255 Parameters: user_id, screen_name, device, retweets 2256 Required: *none* 2257 2258 Allows you enable or disable retweets and device notifications from 2259 the specified user. All other values are assumed to be false. 2260 Requires authentication. 2261 2262 Returns: HashRef 2263 2264 Twitter API documentation: POST friendships/update 2265 <https://dev.twitter.com/rest/reference/post/friendships/update> 2266 2267 update_list 2268 2269 Parameters: list_id, slug, name, mode, description, 2270 owner_screen_name, owner_id 2271 Required: *none* 2272 2273 Updates the specified list. The authenticated user must own the list 2274 to be able to update it. 2275 2276 Returns: List 2277 2278 Twitter API documentation: POST lists/update 2279 <https://dev.twitter.com/rest/reference/post/lists/update> 2280 2281 update_location DEPRECATED 2282 update_location(location) 2283 2284 Parameters: location 2285 Required: location 2286 2287 This method has been deprecated in favor of the update_profile 2288 method. Its URL will continue to work, but please consider migrating 2289 to the newer and more comprehensive method of updating profile 2290 attributes. 2291 2292 Returns: BasicUser 2293 2294 update_profile 2295 2296 Parameters: name, url, location, description, include_entities, 2297 skip_status 2298 Required: *none* 2299 2300 Sets values that users are able to set under the "Account" tab of 2301 their settings page. Only the parameters specified will be updated; 2302 to only update the "name" attribute, for example, only include that 2303 parameter in your request. 2304 2305 Returns: ExtendedUser 2306 2307 Twitter API documentation: POST account/update_profile 2308 <https://dev.twitter.com/rest/reference/post/account/update_profile> 2309 2310 update_profile_background_image 2311 2312 Parameters: image, tile, include_entities, skip_status, use 2313 Required: *none* 2314 2315 Updates the authenticating user's profile background image. The 2316 "image" parameter must be an arrayref with the same interpretation 2317 as the "image" parameter in the "update_profile_image" method. See 2318 that method's documentation for details. The "use" parameter allows 2319 you to specify whether to use the uploaded profile background or 2320 not. 2321 2322 Returns: ExtendedUser 2323 2324 Twitter API documentation: POST 2325 account/update_profile_background_image 2326 <https://dev.twitter.com/rest/reference/post/account/update_profile_ 2327 background_image> 2328 2329 update_profile_banner 2330 update_profile_banner(banner) 2331 2332 Parameters: banner, width, height, offset_left, offset_top 2333 Required: banner 2334 2335 Uploads a profile banner on behalf of the authenticating user. The 2336 "image" parameter is an arrayref with the following interpretation: 2337 2338 [ $file ] 2339 [ $file, $filename ] 2340 [ $file, $filename, Content_Type => $mime_type ] 2341 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ] 2342 2343 The first value of the array ($file) is the name of a file to open. 2344 The second value ($filename) is the name given to Twitter for the 2345 file. If $filename is not provided, the basename portion of $file is 2346 used. If $mime_type is not provided, it will be provided 2347 automatically using LWP::MediaTypes::guess_media_type(). 2348 2349 $raw_image_data can be provided, rather than opening a file, by 2350 passing "undef" as the first array value. 2351 2352 Returns: Nothing 2353 2354 Twitter API documentation: POST account/update_profile_banner 2355 <https://dev.twitter.com/rest/reference/post/account/update_profile_ 2356 banner> 2357 2358 update_profile_colors 2359 2360 Parameters: profile_background_color, profile_text_color, 2361 profile_link_color, profile_sidebar_fill_color, 2362 profile_sidebar_border_color, include_entities, skip_status 2363 Required: *none* 2364 2365 Sets one or more hex values that control the color scheme of the 2366 authenticating user's profile page on twitter.com. These values are 2367 also returned in the /users/show API method. 2368 2369 Returns: ExtendedUser 2370 2371 Twitter API documentation: POST account/update_profile_colors 2372 <https://dev.twitter.com/rest/reference/post/account/update_profile_ 2373 colors> 2374 2375 update_profile_image 2376 update_profile_image(image) 2377 2378 Parameters: image, include_entities, skip_status 2379 Required: image 2380 2381 Updates the authenticating user's profile image. The "image" 2382 parameter is an arrayref with the following interpretation: 2383 2384 [ $file ] 2385 [ $file, $filename ] 2386 [ $file, $filename, Content_Type => $mime_type ] 2387 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ] 2388 2389 The first value of the array ($file) is the name of a file to open. 2390 The second value ($filename) is the name given to Twitter for the 2391 file. If $filename is not provided, the basename portion of $file is 2392 used. If $mime_type is not provided, it will be provided 2393 automatically using LWP::MediaTypes::guess_media_type(). 2394 2395 $raw_image_data can be provided, rather than opening a file, by 2396 passing "undef" as the first array value. 2397 2398 Returns: ExtendedUser 2399 2400 Twitter API documentation: POST account/update_profile_image 2401 <https://dev.twitter.com/rest/reference/post/account/update_profile_ 2402 image> 2403 2404 update_with_media DEPRECATED 2405 update_with_media(status, media[]) 2406 2407 Parameters: status, media[], possibly_sensitive, 2408 in_reply_to_status_id, lat, long, place_id, display_coordinates 2409 Required: status, media[] 2410 2411 Updates the authenticating user's status and attaches media for 2412 upload. 2413 2414 Note that Twitter has marked this endpoint as deprecated, and 2415 recommends instead calling "upload", then (optionally) 2416 "create_media_metadata", then "update". 2417 2418 The "media[]" parameter is an arrayref with the following 2419 interpretation: 2420 2421 [ $file ] 2422 [ $file, $filename ] 2423 [ $file, $filename, Content_Type => $mime_type ] 2424 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ] 2425 2426 The first value of the array ($file) is the name of a file to open. 2427 The second value ($filename) is the name given to Twitter for the 2428 file. If $filename is not provided, the basename portion of $file is 2429 used. If $mime_type is not provided, it will be provided 2430 automatically using LWP::MediaTypes::guess_media_type(). 2431 2432 $raw_image_data can be provided, rather than opening a file, by 2433 passing "undef" as the first array value. 2434 2435 The Tweet text will be rewritten to include the media URL(s), which 2436 will reduce the number of characters allowed in the Tweet text. If 2437 the URL(s) cannot be appended without text truncation, the tweet 2438 will be rejected and this method will return an HTTP 403 error. 2439 2440 Returns: Status 2441 2442 upload 2443 upload(media) 2444 2445 Parameters: media 2446 Required: media 2447 2448 Uploads an image to twitter without immediately posting it to the 2449 authenticating user's timeline. Its return-value hashref notably 2450 contains a "media_id" value that's useful as a parameter value in 2451 various other endpoint calls, such as "update" and 2452 "create_media_metadata". 2453 2454 Returns: HashRef 2455 2456 Twitter API documentation: POST media/upload 2457 <https://dev.twitter.com/rest/reference/post/media/upload> 2458 2459 upload_status 2460 upload_status(media_id, command) 2461 2462 Parameters: media_id, command 2463 Required: media_id, command 2464 2465 Check the status for async video uploads. 2466 2467 Returns: status 2468 2469 Twitter API documentation: GET media/upload 2470 <https://dev.twitter.com/rest/reference/get/media/upload> 2471 2472 user_suggestions 2473 user_suggestions(slug) 2474 alias: follow_suggestions 2475 2476 Parameters: slug, lang 2477 Required: slug 2478 2479 Access the users in a given slug (category) of the Twitter suggested 2480 user list and return their most recent status if they are not a 2481 protected user. Currently supported values for optional parameter 2482 "lang" are "en", "fr", "de", "es", "it". Does not require 2483 authentication. 2484 2485 Returns: ArrayRef 2486 2487 Twitter API documentation: GET users/suggestions/:slug/members 2488 <https://dev.twitter.com/rest/reference/get/users/suggestions/:slug/ 2489 members> 2490 2491 user_suggestions_for 2492 user_suggestions_for(slug) 2493 alias: follow_suggestions_for 2494 2495 Parameters: slug, lang 2496 Required: slug 2497 2498 Access the users in a given slug (category) of the Twitter suggested 2499 user list. 2500 2501 Returns: ArrayRef 2502 2503 Twitter API documentation: GET users/suggestions/:slug 2504 <https://dev.twitter.com/rest/reference/get/users/suggestions/:slug> 2505 2506 user_timeline 2507 2508 Parameters: user_id, screen_name, since_id, max_id, count, 2509 trim_user, exclude_replies, include_rts, contributor_details 2510 Required: *none* 2511 2512 Returns the 20 most recent statuses posted by the authenticating 2513 user, or the user specified by "screen_name" or "user_id". 2514 2515 Returns: ArrayRef[Status] 2516 2517 Twitter API documentation: GET statuses/user_timeline 2518 <https://dev.twitter.com/rest/reference/get/statuses/user_timeline> 2519 2520 users_search 2521 users_search(q) 2522 alias: find_people 2523 alias: search_users 2524 2525 Parameters: q, per_page, page, count, include_entities 2526 Required: q 2527 2528 Run a search for users similar to Find People button on Twitter.com; 2529 the same results returned by people search on Twitter.com will be 2530 returned by using this API (about being listed in the People 2531 Search). It is only possible to retrieve the first 1000 matches from 2532 this API. 2533 2534 Returns: ArrayRef[Users] 2535 2536 Twitter API documentation: GET users/search 2537 <https://dev.twitter.com/rest/reference/get/users/search> 2538 2539 verify_credentials 2540 2541 Parameters: include_entities, skip_status, include_email 2542 Required: *none* 2543 2544 Returns an HTTP 200 OK response code and a representation of the 2545 requesting user if authentication was successful; returns a 401 2546 status code and an error message if not. Use this method to test if 2547 supplied user credentials are valid. 2548 2549 Returns: ExtendedUser 2550 2551 Twitter API documentation: GET account/verify_credentials 2552 <https://dev.twitter.com/rest/reference/get/account/verify_credentia 2553 ls> 2554 2555 update_with_media 2556 update_with_media(status, media) 2557 2558 Parameters: status, media[], possibly_sensitive, 2559 in_reply_to_status_id, lat, long, place_id, display_coordinates 2560 Required: status, media 2561 2562 Updates the authenticating user's status and attaches media for 2563 upload. 2564 2565 The "media[]" parameter is an arrayref with the following 2566 interpretation: 2567 2568 [ $file ] 2569 [ $file, $filename ] 2570 [ $file, $filename, Content_Type => $mime_type ] 2571 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ] 2572 2573 The first value of the array ($file) is the name of a file to open. 2574 The second value ($filename) is the name given to Twitter for the 2575 file. If $filename is not provided, the basename portion of $file is 2576 used. If $mime_type is not provided, it will be provided 2577 automatically using LWP::MediaTypes::guess_media_type(). 2578 2579 $raw_image_data can be provided, rather than opening a file, by 2580 passing "undef" as the first array value. 2581 2582 The Tweet text will be rewritten to include the media URL(s), which 2583 will reduce the number of characters allowed in the Tweet text. If 2584 the URL(s) cannot be appended without text truncation, the tweet 2585 will be rejected and this method will return an HTTP 403 error. 2586 2587 Returns: Status 2588 2589 Twitter API documentation: POST statuses/update_with_media 2590 <https://dev.twitter.com/rest/reference/post/statuses/update_with_me 2591 dia> 2592 2593Search API Methods 2594 These methods are provided when trait "API::Search" is included in the 2595 "traits" option to "new". 2596 2597 search 2598 search(q) 2599 2600 Parameters: q, geocode, lang, locale, result_type, count, until, 2601 since_id, max_id, include_entities, callback 2602 Required: q 2603 2604 Returns a HASH reference with some meta-data about the query 2605 including the "next_page", "refresh_url", and "max_id". The statuses 2606 are returned in "results". To iterate over the results, use 2607 something similar to: 2608 2609 my $r = $nt->search($search_term); 2610 my $r = $nt->search({ q => $search_term, count => 10 }) 2611 2612 for my $status ( @{$r->{results}} ) { 2613 print "$status->{text}\n"; 2614 } 2615 2616 Returns: HashRef 2617 2618Lists API Methods 2619 The original Lists API methods have been deprecated. 2620 Net::Twitter::Role::API::Lists provides backwards compatibility for code 2621 written using those deprecated methods. If you're not already using the 2622 "API::Lists" trait, don't! Use the lists methods described above. 2623 2624 If you are using the "API::Lists" trait, you should remove it from your 2625 code and change the arguments in your list API method calls to match 2626 those described above. 2627 2628 Also, if using the "API::Lists" trait, you can pass synthetic argument 2629 "-legacy_lists_api" set to 0 for individual calls to use the new 2630 endpoints semantics. 2631 2632TwitterVision API Methods 2633 These methods are provided when trait "API::TwitterVision" is included 2634 in the "traits" option to "new". 2635 2636 current_status 2637 current_status(id) 2638 2639 Parameters: id, callback 2640 Required: id 2641 2642 Get the current location and status of a user. 2643 2644 Returns: HashRef 2645 2646 update_twittervision 2647 update_twittervision(location) 2648 2649 Parameters: location 2650 Required: location 2651 2652 Updates the location for the authenticated user. 2653 2654 Returns: HashRef 2655 2656LEGACY COMPATIBILITY 2657 This version of "Net::Twitter" automatically includes the "Legacy" trait 2658 if no "traits" option is provided to "new". Therefore, these 2 calls are 2659 currently equivalent: 2660 2661 $nt = Net::Twitter->new(username => $user, password => $passwd); 2662 $nt = Net::Twitter->new( 2663 username => $user, 2664 password => $passwd, 2665 traits => ['Legacy'], 2666 ); 2667 2668 Thus, existing applications written for a prior version of 2669 "Net::Twitter" should continue to run, without modification, with this 2670 version. 2671 2672 In a future release, the default traits may change. Prior to that 2673 change, however, a nearer future version will add a warning if no 2674 "traits" option is provided to "new". To avoid this warning, add an 2675 appropriate "traits" option to your existing application code. 2676 2677ERROR HANDLING 2678 There are currently two strategies for handling errors: throwing 2679 exceptions and wrapping errors. Exception handling is the newer, 2680 recommended strategy. 2681 2682 Wrapping Errors 2683 When trait "WrapError" is specified (or "Legacy", which includes trait 2684 "WrapError"), "Net::Twitter" returns undef on error. To retrieve 2685 information about the error, use methods "http_code", "http_message", 2686 and "get_error". These methods are described in the 2687 Net::Twitter::Role::WrapError. 2688 2689 if ( my $followers = $nt->followers ) { 2690 for my $follower ( @$followers ) { 2691 #... 2692 } 2693 } 2694 else { 2695 warn "HTTP message: ", $nt->http_message, "\n"; 2696 } 2697 2698 Since an error is stored in the object instance, this error handling 2699 strategy is problematic when using a user agent like 2700 "LWP::UserAgent::POE" that provides concurrent requests. The error for 2701 one request can be overwritten by a concurrent request before you have 2702 an opportunity to access it. 2703 2704 Exception Handling 2705 When "Net::Twitter" encounters a Twitter API error or a network error, 2706 it throws a "Net::Twitter::Error" object. You can catch and process 2707 these exceptions by using "eval" blocks and testing $@: 2708 2709 eval { 2710 my $statuses = $nt->friends_timeline(); # this might die! 2711 2712 for my $status ( @$statuses ) { 2713 #... 2714 } 2715 }; 2716 if ( $@ ) { 2717 # friends_timeline encountered an error 2718 2719 if ( blessed $@ && $@->isa('Net::Twitter::Error') ) { 2720 #... use the thrown error obj 2721 warn $@->error; 2722 } 2723 else { 2724 # something bad happened! 2725 die $@; 2726 } 2727 } 2728 2729 "Net::Twitter::Error" stringifies to something reasonable, so if you 2730 don't need detailed error information, you can simply treat $@ as a 2731 string: 2732 2733 eval { $nt->update($status) }; 2734 if ( $@ ) { 2735 warn "update failed because: $@\n"; 2736 } 2737 2738FAQ 2739 Why does "->followers({ screen_name => $friend })" return *my* followers 2740 instead of $friends's? 2741 First, check carefully to make sure you've spelled "screen_name" 2742 correctly. Twitter sometimes discards parameters it doesn't 2743 recognize. In this case, the result is a list of your own 2744 followers---the same thing that would happen if you called 2745 "followers" without the "screen_name" parameter. 2746 2747 How do I use the "geocode" parameter in the Search API? 2748 The "geocode" parameter value includes a latitude, longitude, and 2749 radius separated with commas. 2750 2751 $r = $nt->search({ geocode => "45.511795,-122.675629,25mi" }); 2752 2753 How do I get Twitter to display something other than "from Perl 2754 Net::Twitter"? 2755 If you set the source parameter to "api", twitter will display "from 2756 API", and if you set it to the empty string, twitter will display, 2757 "from web". 2758 2759 $nt = Net::Twitter->new(netrc => 1,legacy => 0,ssl => 1,source => 'api'); 2760 $nt->update('A post with the source parameter overridden.'); 2761 # result: http://twitter.com/semifor_test/status/6541105458 2762 2763 $nt = Net::Twitter->new(netrc => 1,legacy => 0,ssl => 1,source => ''); 2764 $nt->update('A post with the source parameter overridden.'); 2765 # result: http://twitter.com/semifor_test/status/6541257224 2766 2767 If you want something other than "Net::Twitter", "API", or "web", 2768 you need to register an application and use OAuth authentication. If 2769 you do that, you can have any name you choose for the application 2770 printed as the source. Since rolling out OAuth, Twitter has stopped 2771 issuing new registered source parameters, only existing register 2772 source parameters are valid. 2773 2774SEE ALSO 2775 Net::Twitter::Error 2776 The "Net::Twitter" exception object. 2777 2778 <http://dev.twitter.com/doc> 2779 This is the official Twitter API documentation. It describes the 2780 methods and their parameters in more detail and may be more current 2781 than the documentation provided with this module. 2782 2783 LWP::UserAgent::POE 2784 This LWP::UserAgent compatible class can be used in POE based 2785 application along with Net::Twitter to provide concurrent, 2786 non-blocking requests. 2787 2788 Catalyst::Authentication::Credential::Twitter 2789 This module, by Jesse Stay, provides Twitter OAuth authentication 2790 support for the popular Catalyst web application framework. 2791 2792SUPPORT 2793 Please report bugs to "bug-net-twitter@rt.cpan.org", or through the web 2794 interface at <https://rt.cpan.org/Dist/Display.html?Queue=Net-Twitter>. 2795 2796 Join the Net::Twitter IRC channel at <irc://irc.perl.org/net-twitter>. 2797 2798 Follow perl_api: <http://twitter.com/perl_api>. 2799 2800 Track Net::Twitter development at 2801 <http://github.com/semifor/Net-Twitter>. 2802 2803ACKNOWLEDGEMENTS 2804 Many thanks to Chris Thompson <cpan@cthompson.com>, the original author 2805 of "Net::Twitter" and all versions prior to 3.00. 2806 2807 Also, thanks to Chris Prather (perigrin) for answering many design and 2808 implementation questions, especially with regards to Moose. 2809 2810AUTHOR 2811 Marc Mims <marc@questright.com> (@semifor on Twitter) 2812 2813CONTRIBUTORS 2814 Roberto Etcheverry <retcheverry@gmail.com> (@retcheverry on Twitter) 2815 2816 KATOU Akira 2817 2818 Francisco Pecorella 2819 2820 Doug Bell <doug@plainblack.com> 2821 2822 Justin Hunter <justin.d.hunter@gmail.com> 2823 2824 Allen Haim <allen@netherrealm.net> 2825 2826 Joe Papperello (@antipasta on Github and Twitter) 2827 2828 Samuel Kaufman (ediblenergy on Github) 2829 2830 AnnMary Mathew (ammathew on Github) 2831 2832 Olaf Alders (oalders on Github) 2833 2834LICENSE 2835 Copyright (c) 2009-2016 Marc Mims 2836 2837 The Twitter API itself, and the description text used in this module is: 2838 2839 Copyright (c) 2016 Twitter 2840 2841 This library is free software; you can redistribute it and/or modify it 2842 under the same terms as Perl itself. 2843 2844DISCLAIMER OF WARRANTY 2845 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY 2846 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN 2847 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 2848 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 2849 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 2850 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE 2851 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH 2852 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 2853 NECESSARY SERVICING, REPAIR, OR CORRECTION. 2854 2855 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 2856 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 2857 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE 2858 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR 2859 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE 2860 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING 2861 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A 2862 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF 2863 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH 2864 DAMAGES. 2865 2866