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