1Net::Twitter::Lite(3pm)User Contributed Perl DocumentatioNnet::Twitter::Lite(3pm)
2
6 Net::Twitter::Lite - A perl interface to the Twitter API
7
9 version 0.12008
10
12 You probably want Net::Twitter::Lite::WithAPIv1_1 which has support for
13 Twitter API v1.1. If you're using a service with an API compatible with
14 Twitter's deprecated API v1, then you're in the right place.
15
17 use Net::Twitter::Lite;
18 my $nt = Net::Twitter::Lite->new(
20 username => $user,
21 password => $password
22 legacy_lists_api => 0,
23 );
24 my $result = eval { $nt->update('Hello, world!') };
26 eval {
28 my $statuses = $nt->friends_timeline({ since_id => $high_water, count => 100 });
29 for my $status ( @$statuses ) {
30 print "$status->{created_at} <$status->{user}{screen_name}> $status->{text}\n";
31 }
32 };
33 warn "$@\n" if $@;
34
36 This module provides a perl interface to the Twitter API v1.
37 It uses the same API definitions as Net::Twitter, but without the extra
39 bells and whistles and without the additional dependencies. Same great
40 taste, less filling.
41 This module is related to, but is not part of the "Net::Twitter"
43 distribution. It's API methods and API method documentation are
44 generated from "Net::Twitter"'s internals. It exists for those who
45 cannot, or prefer not to install Moose and its dependencies.
46 You should consider upgrading to "Net::Twitter" for additional
48 functionality, finer grained control over features, backwards
49 compatibility with older versions of "Net::Twitter", and additional
50 error handling options.
51
53 Legacy Lists API
54 Twitter re-implemented the Lists API using new endpoints and semantics.
55 For backwards compatibility, this version of "Net::Twitter::Lite"
56 defaults to the deprecated, legacy endpoints and semantics. It issues
57 a warning if the "legacy_lists_api" option to new is not provided.
58 To enable the new Lists endpoints and semantics, pass
60 "(legacy_lists_api =" 0)> to "new". To disable the warning, and keep
61 the backwards compatible endpoints and semantics, pass
62 "(legacy_lists_api =" 1)> to "new".
63 The "legacy_lists_api" option to "new" sets the default for all lists
65 API method calls. You can override the default an each API call by
66 passing a "-legacy_lists_api" option set to 1 or 0.
67 Support for "legacy_lists_api" option will be removed in a future
69 version and the option to "new" will be silently ignored.
70 netrc option
72 The default "apiurl" changed in version 0.08006. The change should be
73 transparent to client code, unless you're using the "netrc" option. If
74 so, you'll need to either update the ".netrc" entry and change the
75 "machine" value from "twitter.com" to "api.twitter.com", or set either
76 the "netrc" or "netrc_machine" options to "twitter.com".
77 $nt = Net::Twitter::Lite->new(netrc_machine => 'twitter.com', netrc => 1);
79 # -or-
80 $nt = Net::Twitter::Lite->new(netrc => 'twitter.com');
81 OAuth requires callback parameter
83 Beginning with version 0.03, it is necessary for web applications using
84 OAuth authentication to pass the "callback" parameter to
85 "get_authorization_url". In the absence of a callback parameter, when
86 the user authorizes the application a PIN number is displayed rather
87 than redirecting the user back to your site.
88
90 If you are migrating from Net::Twitter 2.12 (or an earlier version),
91 you may need to make some minor changes to your application code in
92 order to user Net::Twitter::Lite successfully.
93 The primary difference is in error handling. Net::Twitter::Lite throws
95 exceptions on error. It does not support the "get_error", "http_code",
96 and "http_message" methods used in Net::Twitter 2.12 and prior
97 versions.
98 Instead of
100 # DON'T!
102 my $friends = $nt->friends();
103 if ( $friends ) {
104 # process $friends
105 }
106 wrap the API call in an eval block:
108 # DO!
110 my $friends = eval { $nt->friends() };
111 if ( $friends ) {
112 # process $friends
113 }
114 Here's a much more complex example taken from application code using
116 Net::Twitter 2.12:
117 # DON'T!
119 my $friends = $nt->friends();
120 if ( $friends ) {
121 # process $friends
122 }
123 else {
124 my $error = $nt->get_error;
125 if ( ref $error ) {
126 if ( ref($error) eq 'HASH' && exists $error->{error} ) {
127 $error = $error->{error};
128 }
129 else {
130 $error = 'Unexpected error type ' . ref($error);
131 }
132 }
133 else {
134 $error = $nt->http_code() . ": " . $nt->http_message;
135 }
136 warn "$error\n";
137 }
138 The Net::Twitter::Lite equivalent is:
140 # DO!
142 eval {
143 my $friends = $nt->friends();
144 # process $friends
145 };
146 warn "$@\n" if $@;
147 return;
148 In Net::Twitter::Lite, an error can always be treated as a string. See
150 Net::Twitter::Lite::Error. The HTTP Status Code and HTTP Message are
151 both available. Rather than accessing them via the Net::Twitter::Lite
152 instance, you access them via the Net::Twitter::Lite::Error instance
153 thrown as an error.
154 For example:
156 # DO!
158 eval {
159 my $friends = $nt->friends();
160 # process $friends
161 };
162 if ( my $error = $@ ) {
163 if ( blessed $error && $error->isa("Net::Twitter::Lite::Error)
164 && $error->code() == 502 ) {
165 $error = "Fail Whale!";
166 }
167 warn "$error\n";
168 }
169 Unsupported Net::Twitter 2.12 options to "new"
171 Net::Twitter::Lite does not support the following Net::Twitter 2.12
172 options to "new". It silently ignores them:
173 no_fallback
175 If Net::Twitter::Lite is unable to create an instance of the class
176 specified in the "useragent_class" option to "new", it dies, rather
177 than falling back to an LWP::UserAgent object. You really don't
178 want a failure to create the "useragent_class" you specified to go
179 unnoticed.
180 twittervision
182 Net::Twitter::Lite does not support the TwitterVision API. Use
183 Net::Twitter, instead, if you need it.
184 skip_arg_validation
186 Net::Twitter::Lite does not API parameter validation. This is a
187 feature. If Twitter adds a new option to an API method, you can
188 use it immediately by passing it in the HASH ref to the API call.
189 Net::Twitter::Lite relies on Twitter to validate its own
191 parameters. An appropriate exception will be thrown if Twitter
192 reports a parameter error.
193 die_on_validation
195 See "skip_arg_validation". If Twitter returns an bad parameter
196 error, an appropriate exception will be thrown.
197 arrayref_on_error
199 This option allowed the following idiom in Net::Twitter 2.12:
200 # DON'T!
202 for my $friend ( @{ $nt->friends() } ) {
203 # process $friend
204 }
205 The equivalent Net::Twitter::Lite code is:
207 # DO!
209 eval {
210 for my $friend ( @{ $nt->friends() } ) {
211 # process $friend
212 }
213 };
214 Unsupported Net::Twitter 2.12 methods
216 clone
217 The "clone" method was added to Net::Twitter 2.x to allow safe
218 error handling in an environment where concurrent requests are
219 handled, for example, when using LWP::UserAgent::POE as the
220 "useragent_class". Since Net::Twitter::Lite throws exceptions
221 instead of stashing them in the Net::Twitter::Lite instance, it is
222 safe in a current request environment, obviating the need for
223 "clone".
224 get_error
226 http_code
227 http_message
228 These methods are replaced by Net::Twitter::Lite::Error. An
229 instance of that class is thrown errors are encountered.
230
232 new This constructs a "Net::Twitter::Lite" object. It takes several
233 named parameters, all of them optional:
234 username
236 This is the screen name or email used to authenticate with
237 Twitter. Use this option for Basic Authentication, only.
238 password
240 This is the password used to authenticate with Twitter. Use
241 this option for Basic Authentication, only.
242 consumer_key
244 A string containing the OAuth consumer key provided by Twitter
245 when an application is registered. Use this option for OAuth
246 authentication, only.
247 consumer_secret
249 A string containing the OAuth consumer secret. Use this option
250 for OAuth authentication, only. the "OAuth" trait is included.
251 oauth_urls
253 A HASH ref of URLs to be used with OAuth authentication.
254 Defaults to:
255 {
257 request_token_url => "http://twitter.com/oauth/request_token",
258 authorization_url => "http://twitter.com/oauth/authorize",
259 access_token_url => "http://twitter.com/oauth/access_token",
260 xauth_url => "https://twitter.com/oauth/access_token",
261 }
262 clientname
264 The value for the "X-Twitter-Client-Name" HTTP header. It
265 defaults to "Perl Net::Twitter::Lite".
266 clientver
268 The value for the "X-Twitter-Client-Version" HTTP header. It
269 defaults to current version of the "Net::Twitter::Lite" module.
270 clienturl
272 The value for the "X-Twitter-Client-URL" HTTP header. It
273 defaults to the search.cpan.org page for the
274 "Net::Twitter::Lite" distribution.
275 useragent_class
277 The "LWP::UserAgent" compatible class used internally by
278 "Net::Twitter::Lite". It defaults to "LWP::UserAgent". For
279 POE based applications, consider using "LWP::UserAgent::POE".
280 useragent_args
282 An HASH ref of arguments to pass to constructor of the class
283 specified with "useragent_class", above. It defaults to {} (an
284 empty HASH ref).
285 useragent
287 The value for "User-Agent" HTTP header. It defaults to
288 "Net::Twitter::Lite/0.11002 (Perl)".
289 source
291 The value used in the "source" parameter of API method calls.
292 It is currently only used in the "update" method in the REST
293 API. It defaults to "twitterpm". This results in the text
294 "from Net::Twitter" rather than "from web" for status messages
295 posted from "Net::Twitter::Lite" when displayed via the Twitter
296 web interface. The value for this parameter is provided by
297 Twitter when a Twitter application is registered. See
298 <http://apiwiki.twitter.com/FAQ#HowdoIget%E2%80%9CfromMyApp%E2%80%9DappendedtoupdatessentfrommyAPIapplication>.
299 apiurl
301 The URL for the Twitter API. This defaults to
302 "http://twitter.com".
303 identica
305 If set to 1 (or any value that evaluates to true), apiurl
306 defaults to "http://identi.ca/api".
307 ssl If set to 1, an SSL connection will be used for all API calls.
309 Defaults to 0.
310 netrc
312 (Optional) Sets the machine key to look up in ".netrc" to
313 obtain credentials. If set to 1, Net::Twitter::Lite will use
314 the value of the "netrc_machine" option (below).
315 # in .netrc
317 machine api.twitter.com
318 login YOUR_TWITTER_USER_NAME
319 password YOUR_TWITTER_PASSWORD
320 machine semifor.twitter.com
321 login semifor
322 password SUPERSECRET
323 # in your perl program
325 $nt = Net::Twitter::Lite->new(netrc => 1);
326 $nt = Net::Twitter::Lite->new(netrc => 'semifor.twitter.com');
327 netrc_machine
329 (Optional) Sets the "machine" entry to look up in ".netrc" when
330 "<netrc =" 1>> is used. Defaults to "api.twitter.com".
331 legacy_lists_api
333 If set to 1, this option enables backwards compatibility by
334 using the now deprecated endpoints and semantics for lists API
335 methods. If set to 0, the new endpoints and semantics will be
336 used. Only the new lists API methods are documented here.
337 If you do not provide this option to "new" a warning is issued.
339 Support for this option and the legacy lists API methods will
340 be removed in a future version.
341 wrap_result
343 (Optional) If set to 1, this option will return an
344 Net::Twitter::Lite::WrapResult object, which provides both the
345 Twitter API result and the HTTP::Response object for the API
346 call. See Net::Twitter::Lite::WrapResult for details.
347 BASIC AUTHENTICATION METHODS
349 credentials($username, $password)
350 Set the credentials for Basic Authentication. This is helpful for
351 managing multiple accounts.
352 OAUTH METHODS
354 authorized
355 Whether the client has the necessary credentials to be authorized.
356 Note that the credentials may be wrong and so the request may fail.
358 request_access_token
360 Returns list including the access token, access token secret,
361 user_id, and screen_name for this user. Takes a HASH of arguments.
362 The "verifier" argument is required. See "OAUTH EXAMPLES".
363 The user must have authorized this app at the url given by
365 "get_authorization_url" first.
366 For desktop applications, the Twitter authorization page will
368 present the user with a PIN number. Prompt the user for the PIN
369 number, and pass it as the "verifier" argument to
370 request_access_token.
371 Returns the access token and access token secret but also sets them
373 internally so that after calling this method, you can immediately
374 call API methods requiring authentication.
375 get_authorization_url(callback => $callback_url)
377 Get the URL used to authorize the user. Returns a "URI" object.
378 For web applications, pass your applications callback URL as the
379 "callback" parameter. No arguments are required for desktop
380 applications ("callback" defaults to "oob", out-of-band).
381 get_authentication_url(callback => $callback_url)
383 Get the URL used to authenticate the user with "Sign in with
384 Twitter" authentication flow. Returns a "URI" object. For web
385 applications, pass your applications callback URL as the "callback"
386 parameter. No arguments are required for desktop applications
387 ("callback" defaults to "oob", out-of-band).
388 xauth($username, $password)
390 Exchanges a username and password for OAuth tokens. Your
391 application must be approved for XAuth access by Twitter for this
392 method to work. Twitter does not grant XAuth access for web
393 applications except for a brief period of time to allow them to
394 switch form Basic authentication to OAuth authentication.
395 access_token
397 Get or set the access token.
398 access_token_secret
400 Get or set the access token secret.
401 request_token
403 Get or set the request token.
404 request_token_secret
406 Get or set the request token secret.
407 access_token_url
409 Get or set the access_token URL.
410 authentication_url
412 Get or set the authentication URL.
413 authorization_url
415 Get or set the authorization URL.
416 request_token_url
418 Get or set the request_token URL.
419 xauth_url
421 Get or set the XAuth access token request URL.
422
424 Most Twitter API methods take parameters. All Net::Twitter::Lite API
425 methods will accept a HASH ref of named parameters as specified in the
426 Twitter API documentation. For convenience, many Net::Twitter::Lite
427 methods accept simple positional arguments as documented, below. The
428 positional parameter passing style is optional; you can always use the
429 named parameters in a hash ref if you prefer.
430 For example, the REST API method "update" has one required parameter,
432 "status". You can call "update" with a HASH ref argument:
433 $nt->update({ status => 'Hello world!' });
435 Or, you can use the convenient form:
437 $nt->update('Hello world!');
439 The "update" method also has an optional parameter,
441 "in_reply_to_status_id". To use it, you must use the HASH ref form:
442 $nt->update({ status => 'Hello world!', in_reply_to_status_id => $reply_to });
444 Convenience form is provided for the required parameters of all API
446 methods. So, these two calls are equivalent:
447 $nt->friendship_exists({ user_a => $fred, user_b => $barney });
449 $nt->friendship_exists($fred, $barney);
450 Many API methods have aliases. You can use the API method name, or any
452 of its aliases, as you prefer. For example, these calls are all
453 equivalent:
454 $nt->friendship_exists($fred, $barney);
456 $nt->relationship_exists($fred, $barney);
457 $nt->follows($fred, $barney);
458 Aliases support both the HASH ref and convenient forms:
460 $nt->follows({ user_a => $fred, user_b => $barney });
462 Methods that support the "page" parameter expect page numbers > 0.
464 Twitter silently ignores invalid "page" values. So "{ page => 0 }"
465 produces the same result as "{ page => 1 }".
466 In addition to the arguments specified for each API method described
468 below, an additional "authenticate" parameter can be passed. To
469 request an "Authorization" header, pass "authenticated => 1"; to
470 suppress an authentication header, pass "authentication => 0". Even if
471 requested, an Authorization header will not be added if there are no
472 user credentials (username and password for Basic Authentication;
473 access tokens for OAuth).
474 This is probably only useful for the "rate_limit_status" method in the
476 REST API, since it returns different values for an authenticated and a
477 non-authenticated call.
478
480 Several of these methods accept a user ID as the "id" parameter. The
481 user ID can be either a screen name, or the users numeric ID. To
482 disambiguate, use the "screen_name" or "user_id" parameters, instead.
483 For example, These calls are equivalent:
485 $nt->create_friend('perl_api'); # screen name
487 $nt->create_friend(1564061); # numeric ID
488 $nt->create_friend({ id => 'perl_api' });
489 $nt->create_friend({ screen_name => 'perl_api' });
490 $nt->create_friend({ user_id => 1564061 });
491 However user_id 911 and screen_name 911 are separate Twitter accounts.
493 These calls are NOT equivalent:
494 $nt->create_friend(911); # interpreted as screen name
496 $nt->create_friend({ user_id => 911 }); # screen name: richellis
497 Whenever the "id" parameter is required and "user_id" and "screen_name"
499 are also parameters, using any one of them satisfies the requirement.
500 account_settings
502 Parameters: none
503 Required: none
504 Returns the current trend, geo and sleep time information for the
506 authenticating user.
507 Returns: HashRef
509 account_totals
511 Parameters: none
512 Required: none
513 Returns the current count of friends, followers, updates (statuses)
515 and favorites of the authenticating user.
516 Returns: HashRef
518 add_list_member
520 Parameters: list_id, slug, user_id, screen_name, owner_screen_name,
521 owner_id
522 Required: none
523 Add a member to a list. The authenticated user must own the list to
525 be able to add members to it. Note that lists can't have more than
526 500 members.
527 Returns: User
529 add_place
531 add_place(name, contained_within, token, lat, long)
532 Parameters: name, contained_within, token, lat, long,
533 attribute:street_address, callback
534 Required: name, contained_within, token, lat, long
535 Creates a new place object at the given latitude and longitude.
537 Before creating a place you need to query "similar_places" with the
539 latitude, longitude and name of the place you wish to create. The
540 query will return an array of places which are similar to the one
541 you wish to create, and a token. If the place you wish to create
542 isn't in the returned array you can use the token with this method
543 to create a new one.
544 Returns: Place
546 all_subscriptions
548 alias: all_lists
549 alias: list_subscriptions
550 Parameters: user_id, screen_name, count, cursor
551 Required: none
552 Returns all lists the authenticating or specified user subscribes
554 to, including their own. The user is specified using the user_id or
555 screen_name parameters. If no user is given, the authenticating
556 user is used.
557 Returns: ArrayRef[List]
559 block_exists
561 block_exists(id)
562 Parameters: id, user_id, screen_name, include_entities
563 Required: id
564 Returns if the authenticating user is blocking a target user. Will
566 return the blocked user's object if a block exists, and error with
567 HTTP 404 response code otherwise.
568 Returns: BasicUser
570 blocking
572 Parameters: page, include_entities
573 Required: none
574 Returns an array of user objects that the authenticating user is
576 blocking.
577 Returns: ArrayRef[BasicUser]
579 blocking_ids
581 Parameters: none
582 Required: none
583 Returns an array of numeric user ids the authenticating user is
585 blocking.
586 Returns: ArrayRef[Int]
588 contributees
590 Parameters: user_id, screen_name, include_entities, skip_satus
591 Required: none
592 Returns an array of users that the specified user can contribute
594 to.
595 Returns: ArrayRef[User]
597 contributors
599 Parameters: user_id, screen_name, include_entities, skip_satus
600 Required: none
601 Returns an array of users who can contribute to the specified
603 account.
604 Returns: ArrayRef[User]
606 create_block
608 create_block(id)
609 Parameters: id, user_id, screen_name, include_entities
610 Required: id
611 Blocks the user specified in the ID parameter as the authenticating
613 user. Returns the blocked user when successful. You can find out
614 more about blocking in the Twitter Support Knowledge Base.
615 Returns: BasicUser
617 create_favorite
619 create_favorite(id)
620 Parameters: id, include_entities
621 Required: id
622 Favorites the status specified in the ID parameter as the
624 authenticating user. Returns the favorite status when successful.
625 Returns: Status
627 create_friend
629 create_friend(id)
630 alias: follow_new
631 Parameters: id, user_id, screen_name, follow, include_entities
632 Required: id
633 Befriends the user specified in the ID parameter as the
635 authenticating user. Returns the befriended user when successful.
636 Returns a string describing the failure condition when
637 unsuccessful.
638 Returns: BasicUser
640 create_list
642 Parameters: list_id, slug, name, mode, description,
643 owner_screen_name, owner_id
644 Required: none
645 Creates a new list for the authenticated user. Note that you can't
647 create more than 20 lists per account.
648 Returns: List
650 create_saved_search
652 create_saved_search(query)
653 Parameters: query
654 Required: query
655 Creates a saved search for the authenticated user.
657 Returns: SavedSearch
659 delete_list
661 Parameters: owner_screen_name, owner_id, list_id, slug
662 Required: none
663 Deletes the specified list. The authenticated user must own the
665 list to be able to destroy it.
666 Returns: List
668 delete_list_member
670 alias: remove_list_member
671 Parameters: list_id, slug, user_id, screen_name, owner_screen_name,
672 owner_id
673 Required: none
674 Removes the specified member from the list. The authenticated user
676 must be the list's owner to remove members from the list.
677 Returns: User
679 destroy_block
681 destroy_block(id)
682 Parameters: id, user_id, screen_name
683 Required: id
684 Un-blocks the user specified in the ID parameter as the
686 authenticating user. Returns the un-blocked user when successful.
687 Returns: BasicUser
689 destroy_direct_message
691 destroy_direct_message(id)
692 Parameters: id, include_entities
693 Required: id
694 Destroys the direct message specified in the required ID parameter.
696 The authenticating user must be the recipient of the specified
697 direct message.
698 Returns: DirectMessage
700 destroy_favorite
702 destroy_favorite(id)
703 Parameters: id, include_entities
704 Required: id
705 Un-favorites the status specified in the ID parameter as the
707 authenticating user. Returns the un-favorited status.
708 Returns: Status
710 destroy_friend
712 destroy_friend(id)
713 alias: unfollow
714 Parameters: id, user_id, screen_name, include_entities
715 Required: id
716 Discontinues friendship with the user specified in the ID parameter
718 as the authenticating user. Returns the un-friended user when
719 successful. Returns a string describing the failure condition when
720 unsuccessful.
721 Returns: BasicUser
723 destroy_saved_search
725 destroy_saved_search(id)
726 Parameters: id
727 Required: id
728 Destroys a saved search. The search, specified by "id", must be
730 owned by the authenticating user.
731 Returns: SavedSearch
733 destroy_status
735 destroy_status(id)
736 Parameters: id, trim_user, include_entities
737 Required: id
738 Destroys the status specified by the required ID parameter. The
740 authenticating user must be the author of the specified status.
741 Returns: Status
743 direct_messages
745 direct_messages(include_entities)
746 Parameters: since_id, max_id, count, page, include_entities
747 Required: include_entities
748 Returns a list of the 20 most recent direct messages sent to the
750 authenticating user including detailed information about the
751 sending and recipient users.
752 Returns: ArrayRef[DirectMessage]
754 disable_notifications
756 disable_notifications(id)
757 Parameters: id, screen_name, include_entities
758 Required: id
759 Disables notifications for updates from the specified user to the
761 authenticating user. Returns the specified user when successful.
762 Returns: BasicUser
764 enable_notifications
766 enable_notifications(id)
767 Parameters: id, screen_name, include_entities
768 Required: id
769 Enables notifications for updates from the specified user to the
771 authenticating user. Returns the specified user when successful.
772 Returns: BasicUser
774 end_session
776 Parameters: none
777 Required: none
778 Ends the session of the authenticating user, returning a null
780 cookie. Use this method to sign users out of client-facing
781 applications like widgets.
782 Returns: Error
784 favorites
786 Parameters: id, page, include_entities
787 Required: none
788 Returns the 20 most recent favorite statuses for the authenticating
790 user or user specified by the ID parameter.
791 Returns: ArrayRef[Status]
793 followers_ids
795 followers_ids(id)
796 Parameters: id, user_id, screen_name, cursor
797 Required: id
798 Returns a reference to an array of numeric IDs for every user
800 following the specified user. The order of the IDs may change from
801 call to call. To obtain the screen names, pass the arrayref to
802 "lookup_users".
803 Use the optional "cursor" parameter to retrieve IDs in pages of
805 5000. When the "cursor" parameter is used, the return value is a
806 reference to a hash with keys "previous_cursor", "next_cursor", and
807 "ids". The value of "ids" is a reference to an array of IDS of the
808 user's followers. Set the optional "cursor" parameter to -1 to get
809 the first page of IDs. Set it to the prior return's value of
810 "previous_cursor" or "next_cursor" to page forward or backwards.
811 When there are no prior pages, the value of "previous_cursor" will
812 be 0. When there are no subsequent pages, the value of
813 "next_cursor" will be 0.
814 Returns: HashRef|ArrayRef[Int]
816 friends_ids
818 friends_ids(id)
819 alias: following_ids
820 Parameters: id, user_id, screen_name, cursor
821 Required: id
822 Returns a reference to an array of numeric IDs for every user
824 followed by the specified user. The order of the IDs is reverse
825 chronological.
826 Use the optional "cursor" parameter to retrieve IDs in pages of
828 5000. When the "cursor" parameter is used, the return value is a
829 reference to a hash with keys "previous_cursor", "next_cursor", and
830 "ids". The value of "ids" is a reference to an array of IDS of the
831 user's friends. Set the optional "cursor" parameter to -1 to get
832 the first page of IDs. Set it to the prior return's value of
833 "previous_cursor" or "next_cursor" to page forward or backwards.
834 When there are no prior pages, the value of "previous_cursor" will
835 be 0. When there are no subsequent pages, the value of
836 "next_cursor" will be 0.
837 Returns: HashRef|ArrayRef[Int]
839 friendship_exists
841 friendship_exists(user_a, user_b)
842 alias: relationship_exists
843 alias: follows
844 Parameters: user_id_a, user_id_b, screen_name_a, screen_name_b,
845 user_a, user_b
846 Required: user_a, user_b
847 Tests for the existence of friendship between two users. Will
849 return true if user_a follows user_b, otherwise will return false.
850 Use of "user_a" and "user_b" is deprecated. It has been preserved
852 for backwards compatibility, and is used for the two-argument
853 positional form:
854 $nt->friendship_exists($user_a, $user_b);
856 Instead, you should use one of the named argument forms:
858 $nt->friendship_exists({ user_id_a => $id1, user_id_b => $id2 });
860 $nt->friendship_exists({ screen_name_a => $name1, screen_name_b => $name2 });
861 Consider using "show_friendship" instead.
863 Returns: Bool
865 friendships_incoming
867 friendships_incoming(cursor)
868 Parameters: cursor
869 Required: cursor
870 Returns an HASH ref with an array of numeric IDs in the "ids"
872 element for every user who has a pending request to follow the
873 authenticating user.
874 Returns: HashRef
876 friendships_outgoing
878 friendships_outgoing(cursor)
879 Parameters: cursor
880 Required: cursor
881 Returns an HASH ref with an array of numeric IDs in the "ids"
883 element for every protected user for whom the authenticating user
884 has a pending follow request.
885 Returns: HashRef
887 geo_id
889 geo_id(id)
890 Parameters: id
891 Required: id
892 Returns details of a place returned from the "reverse_geocode"
894 method.
895 Returns: HashRef
897 geo_search
899 Parameters: lat, long, query, ip, granularity, accuracy,
900 max_results, contained_within, attribute:street_address, callback
901 Required: none
902 Search for places that can be attached to a statuses/update. Given
904 a latitude and a longitude pair, an IP address, or a name, this
905 request will return a list of all the valid places that can be used
906 as the place_id when updating a status.
907 Conceptually, a query can be made from the user's location,
909 retrieve a list of places, have the user validate the location he
910 or she is at, and then send the ID of this location with a call to
911 statuses/update.
912 This is the recommended method to use find places that can be
914 attached to statuses/update. Unlike geo/reverse_geocode which
915 provides raw data access, this endpoint can potentially re-order
916 places with regards to the user who is authenticated. This approach
917 is also preferred for interactive place matching with the user.
918 Returns: HashRef
920 get_configuration
922 Parameters: none
923 Required: none
924 Returns the current configuration used by Twitter including
926 twitter.com slugs which are not usernames, maximum photo
927 resolutions, and t.co URL lengths.
928 It is recommended applications request this endpoint when they are
930 loaded, but no more than once a day.
931 Returns: HashRef
933 get_languages
935 Parameters: none
936 Required: none
937 Returns the list of languages supported by Twitter along with their
939 ISO 639-1 code. The ISO 639-1 code is the two letter value to use
940 if you include lang with any of your requests.
941 Returns: ArrayRef[Lanugage]
943 get_list
945 Parameters: list_id, slug, owner_screen_name, owner_id
946 Required: none
947 Returns the specified list. Private lists will only be shown if the
949 authenticated user owns the specified list.
950 Returns: List
952 get_lists
954 alias: list_lists
955 Parameters: user_id, screen_name, cursor
956 Required: none
957 Returns the lists of the specified (or authenticated) user. Private
959 lists will be included if the authenticated user is the same as the
960 user whose lists are being returned.
961 Returns: Hashref
963 get_privacy_policy
965 Parameters: none
966 Required: none
967 Returns Twitter's privacy policy.
969 Returns: HashRef
971 get_tos
973 Parameters: none
974 Required: none
975 Returns the Twitter Terms of Service. These are not the same as the
977 Developer Rules of the Road.
978 Returns: HashRef
980 home_timeline
982 Parameters: since_id, max_id, count, page, skip_user,
983 exclude_replies, contributor_details, include_rts,
984 include_entities, trim_user, include_my_retweet
985 Required: none
986 Returns the 20 most recent statuses, including retweets, posted by
988 the authenticating user and that user's friends. This is the
989 equivalent of /timeline/home on the Web.
990 Returns: ArrayRef[Status]
992 is_list_member
994 Parameters: owner_screen_name, owner_id, list_id, slug, user_id,
995 screen_name, include_entities, skip_status
996 Required: none
997 Check if the specified user is a member of the specified list.
999 Returns the user or undef.
1000 Returns: Maybe[User]
1002 is_list_subscriber
1004 alias: is_subscribed_list
1005 Parameters: owner_screen_name, owner_id, list_id, slug, user_id,
1006 screen_name, include_entities, skip_status
1007 Required: none
1008 Check if the specified user is a subscriber of the specified list.
1010 Returns the user or undef.
1011 Returns: Maybe[User]
1013 list_members
1015 Parameters: list_id, slug, owner_screen_name, owner_id, cursor,
1016 include_entities, skip_status
1017 Required: none
1018 Returns the members of the specified list. Private list members
1020 will only be shown if the authenticated user owns the specified
1021 list.
1022 Returns: Hashref
1024 list_memberships
1026 Parameters: user_id, screen_name, cursor, filter_to_owned_lists
1027 Required: none
1028 Returns the lists the specified user has been added to. If user_id
1030 or screen_name are not provided the memberships for the
1031 authenticating user are returned.
1032 Returns: Hashref
1034 list_statuses
1036 Parameters: list_id, slug, owner_screen_name, owner_id, since_id,
1037 max_id, per_page, page, include_entities, include_rts
1038 Required: none
1039 Returns tweet timeline for members of the specified list.
1041 Historically, retweets were not available in list timeline
1042 responses but you can now use the include_rts=true parameter to
1043 additionally receive retweet objects.
1044 Returns: ArrayRef[Status]
1046 list_subscribers
1048 Parameters: list_id, slug, owner_screen_name, owner_id, cursor,
1049 include_entities, skip_status
1050 Required: none
1051 Returns the subscribers of the specified list. Private list
1053 subscribers will only be shown if the authenticated user owns the
1054 specified list.
1055 Returns: Hashref
1057 lookup_friendships
1059 Parameters: user_id, screen_name
1060 Required: none
1061 Returns the relationship of the authenticating user to the comma
1063 separated list or ARRAY ref of up to 100 screen_names or user_ids
1064 provided. Values for connections can be: following,
1065 following_requested, followed_by, none. Requires authentication.
1066 Returns: ArrayRef
1068 lookup_users
1070 Parameters: user_id, screen_name, include_entities
1071 Required: none
1072 Return up to 100 users worth of extended information, specified by
1074 either ID, screen name, or combination of the two. The author's
1075 most recent status (if the authenticating user has permission) will
1076 be returned inline. This method is rate limited to 1000 calls per
1077 hour.
1078 This method will accept user IDs or screen names as either a comma
1080 delimited string, or as an ARRAY ref. It will also accept
1081 arguments in the normal HASHREF form or as a simple list of named
1082 arguments. I.e., any of the following forms are acceptable:
1083 $nt->lookup_users({ user_id => '1234,6543,3333' });
1085 $nt->lookup_users(user_id => '1234,6543,3333');
1086 $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] });
1087 $nt->lookup_users({ screen_name => 'fred,barney,wilma' });
1088 $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']);
1089 $nt->lookup_users(
1091 screen_name => ['fred', 'barney' ],
1092 user_id => '4321,6789',
1093 );
1094 Returns: ArrayRef[User]
1096 members_create_all
1098 alias: add_list_members
1099 Parameters: list_id, slug, owner_screen_name, owner_id
1100 Required: none
1101 Adds multiple members to a list, by specifying a reference to an
1103 array or a comma-separated list of member ids or screen names. The
1104 authenticated user must own the list to be able to add members to
1105 it. Note that lists can't have more than 500 members, and you are
1106 limited to adding up to 100 members to a list at a time with this
1107 method.
1108 Returns: List
1110 members_destroy_all
1112 alias: remove_list_members
1113 Parameters: list_id, slug, user_id, screen_name, owner_screen_name,
1114 owner_id
1115 Required: none
1116 Removes multiple members from a list, by specifying a reference to
1118 an array of member ids or screen names, or a string of comma
1119 separated user ids or screen names. The authenticated user must
1120 own the list to be able to remove members from it. Note that lists
1121 can't have more than 500 members, and you are limited to removing
1122 up to 100 members to a list at a time with this method.
1123 Please note that there can be issues with lists that rapidly remove
1125 and add memberships. Take care when using these methods such that
1126 you are not too rapidly switching between removals and adds on the
1127 same list.
1128 Returns: List
1130 mentions
1132 alias: replies
1133 Parameters: since_id, max_id, count, page, trim_user, include_rts,
1134 include_entities
1135 Required: none
1136 Returns the 20 most recent mentions (statuses containing @username)
1138 for the authenticating user.
1139 Returns: ArrayRef[Status]
1141 new_direct_message
1143 new_direct_message(user, text)
1144 Parameters: user, text, screen_name, user_id, include_entities
1145 Required: user, text
1146 Sends a new direct message to the specified user from the
1148 authenticating user. Requires both the user and text parameters.
1149 Returns the sent message when successful. In order to support
1150 numeric screen names, the "screen_name" or "user_id" parameters may
1151 be used instead of "user".
1152 Returns: DirectMessage
1154 no_retweet_ids
1156 Parameters: none
1157 Required: none
1158 Returns an ARRAY ref of user IDs for which the authenticating user
1160 does not want to receive retweets.
1161 Returns: ArrayRef[UserIDs]
1163 public_timeline
1165 Parameters: skip_user, trim_user, include_entities
1166 Required: none
1167 Returns the 20 most recent statuses from non-protected users who
1169 have set a custom user icon. Does not require authentication.
1170 Note that the public timeline is cached for 60 seconds so
1171 requesting it more often than that is a waste of resources.
1172 If user credentials are provided, "public_timeline" calls are
1174 authenticated, so they count against the authenticated user's rate
1175 limit. Use "->public_timeline({ authenticate => 0 })" to make an
1176 unauthenticated call which will count against the calling IP
1177 address' rate limit, instead.
1178 Returns: ArrayRef[Status]
1180 rate_limit_status
1182 Parameters: none
1183 Required: none
1184 Returns the remaining number of API requests available to the
1186 authenticated user before the API limit is reached for the current
1187 hour.
1188 Use "->rate_limit_status({ authenticate => 0 })" to force an
1190 unauthenticated call, which will return the status for the IP
1191 address rather than the authenticated user. (Note: for a web
1192 application, this is the server's IP address.)
1193 Returns: RateLimitStatus
1195 related_results
1197 related_results(id)
1198 Parameters: id
1199 Required: id
1200 If available, returns an array of replies and mentions related to
1202 the specified status. There is no guarantee there will be any
1203 replies or mentions in the response. This method is only available
1204 to users who have access to #newtwitter. Requires authentication.
1205 Returns: ArrayRef[Status]
1207 report_spam
1209 report_spam(id)
1210 Parameters: id, user_id, screen_name, include_entities
1211 Required: id
1212 The user specified in the id is blocked by the authenticated user
1214 and reported as a spammer.
1215 Returns: User
1217 retweet
1219 retweet(id)
1220 Parameters: id, include_entities, trim_user
1221 Required: id
1222 Retweets a tweet. Requires the id parameter of the tweet you are
1224 retweeting. Returns the original tweet with retweet details
1225 embedded.
1226 Returns: Status
1228 retweeted_by
1230 retweeted_by(id)
1231 Parameters: id, count, page, trim_user, include_entities
1232 Required: id
1233 Returns up to 100 users who retweeted the status identified by
1235 "id".
1236 Returns: ArrayRef[User]
1238 retweeted_by_ids
1240 retweeted_by_ids(id)
1241 Parameters: id, count, page, trim_user, include_entities
1242 Required: id
1243 Returns the IDs of up to 100 users who retweeted the status
1245 identified by "id".
1246 Returns: ArrayRef[User]
1248 retweeted_by_me
1250 Parameters: since_id, max_id, count, page, trim_user,
1251 include_entities
1252 Required: none
1253 Returns the 20 most recent retweets posted by the authenticating
1255 user.
1256 Returns: ArrayRef[Status]
1258 retweeted_by_user
1260 retweeted_by_user(id)
1261 Parameters: id, user_id, screen_name
1262 Required: id
1263 Returns the 20 most recent retweets posted by the specified user.
1265 The user is specified using the user_id or screen_name parameters.
1266 This method is identical to "retweeted_by_me" except you can choose
1267 the user to view. Does not require authentication, unless the user
1268 is protected.
1269 Returns: ArrayRef
1271 retweeted_to_me
1273 Parameters: since_id, max_id, count, page
1274 Required: none
1275 Returns the 20 most recent retweets posted by the authenticating
1277 user's friends.
1278 Returns: ArrayRef[Status]
1280 retweeted_to_user
1282 retweeted_to_user(id)
1283 Parameters: id, user_id, screen_name
1284 Required: id
1285 Returns the 20 most recent retweets posted by users the specified
1287 user follows. The user is specified using the user_id or
1288 screen_name parameters. This method is identical to
1289 "retweeted_to_me" except you can choose the user to view. Does not
1290 require authentication, unless the user is protected.
1291 Returns: ArrayRef
1293 retweets
1295 retweets(id)
1296 Parameters: id, count, trim_user, include_entities
1297 Required: id
1298 Returns up to 100 of the first retweets of a given tweet.
1300 Returns: Arrayref[Status]
1302 retweets_of_me
1304 alias: retweeted_of_me
1305 Parameters: since_id, max_id, count, page, trim_user,
1306 include_entities
1307 Required: none
1308 Returns the 20 most recent tweets of the authenticated user that
1310 have been retweeted by others.
1311 Returns: ArrayRef[Status]
1313 reverse_geocode
1315 reverse_geocode(lat, long)
1316 Parameters: lat, long, accuracy, granularity, max_results
1317 Required: lat, long
1318 Search for places (cities and neighborhoods) that can be attached
1320 to a statuses/update. Given a latitude and a longitude, return a
1321 list of all the valid places that can be used as a place_id when
1322 updating a status. Conceptually, a query can be made from the
1323 user's location, retrieve a list of places, have the user validate
1324 the location he or she is at, and then send the ID of this location
1325 up with a call to statuses/update.
1326 There are multiple granularities of places that can be returned --
1328 "neighborhoods", "cities", etc. At this time, only United States
1329 data is available through this method.
1330 lat Required. The latitude to query about. Valid ranges are -90.0
1332 to +90.0 (North is positive) inclusive.
1333 long
1335 Required. The longitude to query about. Valid ranges are
1336 -180.0 to +180.0 (East is positive) inclusive.
1337 accuracy
1339 Optional. A hint on the "region" in which to search. If a
1340 number, then this is a radius in meters, but it can also take a
1341 string that is suffixed with ft to specify feet. If this is
1342 not passed in, then it is assumed to be 0m. If coming from a
1343 device, in practice, this value is whatever accuracy the device
1344 has measuring its location (whether it be coming from a GPS,
1345 WiFi triangulation, etc.).
1346 granularity
1348 Optional. The minimal granularity of data to return. If this
1349 is not passed in, then "neighborhood" is assumed. "city" can
1350 also be passed.
1351 max_results
1353 Optional. A hint as to the number of results to return. This
1354 does not guarantee that the number of results returned will
1355 equal max_results, but instead informs how many "nearby"
1356 results to return. Ideally, only pass in the number of places
1357 you intend to display to the user here.
1358 Returns: HashRef
1360 saved_searches
1362 Parameters: none
1363 Required: none
1364 Returns the authenticated user's saved search queries.
1366 Returns: ArrayRef[SavedSearch]
1368 sent_direct_messages
1370 Parameters: since_id, max_id, page, count, include_entities
1371 Required: none
1372 Returns a list of the 20 most recent direct messages sent by the
1374 authenticating user including detailed information about the
1375 sending and recipient users.
1376 Returns: ArrayRef[DirectMessage]
1378 show_direct_message
1380 show_direct_message(id)
1381 Parameters: id, include_entities
1382 Required: id
1383 Returns a single direct message, specified by an id parameter. Like
1385 the "direct_messages" request, this method will include the user
1386 objects of the sender and recipient. Requires authentication.
1387 Returns: HashRef
1389 show_friendship
1391 show_friendship(id)
1392 alias: show_relationship
1393 Parameters: source_id, source_screen_name, target_id,
1394 target_id_name
1395 Required: id
1396 Returns detailed information about the relationship between two
1398 users.
1399 Returns: Relationship
1401 show_saved_search
1403 show_saved_search(id)
1404 Parameters: id
1405 Required: id
1406 Retrieve the data for a saved search, by "id", owned by the
1408 authenticating user.
1409 Returns: SavedSearch
1411 show_status
1413 show_status(id)
1414 Parameters: id, trim_user, include_entities
1415 Required: id
1416 Returns a single status, specified by the id parameter. The
1418 status's author will be returned inline.
1419 Returns: Status
1421 show_user
1423 show_user(id)
1424 Parameters: id, screen_name, include_entities
1425 Required: id
1426 Returns extended information of a given user, specified by ID or
1428 screen name as per the required id parameter. This information
1429 includes design settings, so third party developers can theme their
1430 widgets according to a given user's preferences. You must be
1431 properly authenticated to request the page of a protected user.
1432 Returns: ExtendedUser
1434 similar_places
1436 similar_places(lat, long, name)
1437 Parameters: lat, long, name, contained_within,
1438 attribute:street_address, callback
1439 Required: lat, long, name
1440 Locates places near the given coordinates which are similar in
1442 name.
1443 Conceptually you would use this method to get a list of known
1445 places to choose from first. Then, if the desired place doesn't
1446 exist, make a request to "add_place" to create a new one.
1447 The token contained in the response is the token needed to be able
1449 to create a new place.
1450 Returns: HashRef
1452 subscribe_list
1454 Parameters: owner_screen_name, owner_id, list_id, slug
1455 Required: none
1456 Subscribes the authenticated user to the specified list.
1458 Returns: List
1460 subscriptions
1462 Parameters: user_id, screen_name, count, cursor
1463 Required: none
1464 Obtain a collection of the lists the specified user is subscribed
1466 to, 20 lists per page by default. Does not include the user's own
1467 lists.
1468 Returns: ArrayRef[List]
1470 suggestion_categories
1472 Parameters: none
1473 Required: none
1474 Returns the list of suggested user categories. The category slug
1476 can be used in the "user_suggestions" API method get the users in
1477 that category . Does not require authentication.
1478 Returns: ArrayRef
1480 test
1482 Parameters: none
1483 Required: none
1484 Returns the string "ok" status code.
1486 Returns: Str
1488 trends_available
1490 Parameters: lat, long
1491 Required: none
1492 Returns the locations with trending topic information. The response
1494 is an array of "locations" that encode the location's WOEID (a
1495 Yahoo! Where On Earth ID
1496 <http://developer.yahoo.com/geo/geoplanet/>) and some other human-
1497 readable information such as a the location's canonical name and
1498 country.
1499 When the optional "lat" and "long" parameters are passed, the
1501 available trend locations are sorted by distance from that
1502 location, nearest to farthest.
1503 Use the WOEID returned in the location object to query trends for a
1505 specific location.
1506 Returns: ArrayRef[Location]
1508 trends_current
1510 trends_current(exclude)
1511 Parameters: exclude
1512 Required: none
1513 Returns the current top ten trending topics on Twitter. The
1515 response includes the time of the request, the name of each
1516 trending topic, and query used on Twitter Search results page for
1517 that topic.
1518 Returns: HashRef
1520 trends_daily
1522 Parameters: date, exclude
1523 Required: none
1524 Returns the top 20 trending topics for each hour in a given day.
1526 Returns: HashRef
1528 trends_location
1530 trends_location(woeid)
1531 Parameters: woeid
1532 Required: woeid
1533 Returns the top 10 trending topics for a specific location. The
1535 response is an array of "trend" objects that encode the name of the
1536 trending topic, the query parameter that can be used to search for
1537 the topic on Search, and the direct URL that can be issued against
1538 Search. This information is cached for five minutes, and therefore
1539 users are discouraged from querying these endpoints faster than
1540 once every five minutes. Global trends information is also
1541 available from this API by using a WOEID of 1.
1542 Returns: ArrayRef[Trend]
1544 trends_weekly
1546 Parameters: date, exclude
1547 Required: none
1548 Returns the top 30 trending topics for each day in a given week.
1550 Returns: HashRef
1552 unsubscribe_list
1554 Parameters: list_id, slug, owner_screen_name, owner_id
1555 Required: none
1556 Unsubscribes the authenticated user from the specified list.
1558 Returns: List
1560 update
1562 update(status)
1563 Parameters: status, lat, long, place_id, display_coordinates,
1564 in_reply_to_status_id, trim_user, include_entities
1565 Required: status
1566 Updates the authenticating user's status. Requires the status
1568 parameter specified. A status update with text identical to the
1569 authenticating user's current status will be ignored.
1570 status
1572 Required. The text of your status update. URL encode as
1573 necessary. Statuses over 140 characters will cause a 403 error
1574 to be returned from the API.
1575 in_reply_to_status_id
1577 Optional. The ID of an existing status that the update is in
1578 reply to. o Note: This parameter will be ignored unless the
1579 author of the tweet this parameter references is mentioned
1580 within the status text. Therefore, you must include @username,
1581 where username is the author of the referenced tweet, within
1582 the update.
1583 lat Optional. The location's latitude that this tweet refers to.
1585 The valid ranges for latitude is -90.0 to +90.0 (North is
1586 positive) inclusive. This parameter will be ignored if outside
1587 that range, if it is not a number, if geo_enabled is disabled,
1588 or if there not a corresponding long parameter with this tweet.
1589 long
1591 Optional. The location's longitude that this tweet refers to.
1592 The valid ranges for longitude is -180.0 to +180.0 (East is
1593 positive) inclusive. This parameter will be ignored if outside
1594 that range, if it is not a number, if geo_enabled is disabled,
1595 or if there not a corresponding lat parameter with this tweet.
1596 place_id
1598 Optional. The place to attach to this status update. Valid
1599 place_ids can be found by querying "reverse_geocode".
1600 display_coordinates
1602 Optional. By default, geo-tweets will have their coordinates
1603 exposed in the status object (to remain backwards compatible
1604 with existing API applications). To turn off the display of
1605 the precise latitude and longitude (but keep the contextual
1606 location information), pass "display_coordinates =" 0> on the
1607 status update.
1608 Returns: Status
1610 update_delivery_device
1612 update_delivery_device(device)
1613 Parameters: device
1614 Required: device
1615 Sets which device Twitter delivers updates to for the
1617 authenticating user. Sending none as the device parameter will
1618 disable IM or SMS updates.
1619 Returns: BasicUser
1621 update_friendship
1623 update_friendship(id)
1624 Parameters: id, user_id, screen_name, device, retweets
1625 Required: id
1626 Allows you enable or disable retweets and device notifications from
1628 the specified user. All other values are assumed to be false.
1629 Requires authentication.
1630 Returns: HashRef
1632 update_list
1634 Parameters: list_id, slug, name, mode, description,
1635 owner_screen_name, owner_id
1636 Required: none
1637 Updates the specified list. The authenticated user must own the
1639 list to be able to update it.
1640 Returns: List
1642 update_profile
1644 Parameters: name, email, url, location, description,
1645 include_entities
1646 Required: none
1647 Sets values that users are able to set under the "Account" tab of
1649 their settings page. Only the parameters specified will be updated;
1650 to only update the "name" attribute, for example, only include that
1651 parameter in your request.
1652 Returns: ExtendedUser
1654 update_profile_background_image
1656 update_profile_background_image(image)
1657 Parameters: image, use
1658 Required: image
1659 Updates the authenticating user's profile background image. The
1661 "image" parameter must be an arrayref with the same interpretation
1662 as the "image" parameter in the "update_profile_image" method. The
1663 "use" parameter allows you to specify whether to use the uploaded
1664 profile background or not. See that method's documentation for
1665 details.
1666 Returns: ExtendedUser
1668 update_profile_colors
1670 Parameters: profile_background_color, profile_text_color,
1671 profile_link_color, profile_sidebar_fill_color,
1672 profile_sidebar_border_color
1673 Required: none
1674 Sets one or more hex values that control the color scheme of the
1676 authenticating user's profile page on twitter.com. These values
1677 are also returned in the /users/show API method.
1678 Returns: ExtendedUser
1680 update_profile_image
1682 update_profile_image(image)
1683 Parameters: image
1684 Required: image
1685 Updates the authenticating user's profile image. The "image"
1687 parameter is an arrayref with the following interpretation:
1688 [ $file ]
1690 [ $file, $filename ]
1691 [ $file, $filename, Content_Type => $mime_type ]
1692 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
1693 The first value of the array ($file) is the name of a file to open.
1695 The second value ($filename) is the name given to Twitter for the
1696 file. If $filename is not provided, the basename portion of $file
1697 is used. If $mime_type is not provided, it will be provided
1698 automatically using LWP::MediaTypes::guess_media_type().
1699 $raw_image_data can be provided, rather than opening a file, by
1701 passing "undef" as the first array value.
1702 Returns: ExtendedUser
1704 update_with_media
1706 update_with_media(status, media)
1707 Parameters: status, media[], possibly_sensitive,
1708 in_reply_to_status_id, lat, long, place_id, display_coordinates
1709 Required: status, media
1710 Updates the authenticating user's status and attaches media for
1712 upload.
1713 The "media[]" parameter is an arrayref with the following
1715 interpretation:
1716 [ $file ]
1718 [ $file, $filename ]
1719 [ $file, $filename, Content_Type => $mime_type ]
1720 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
1721 The first value of the array ($file) is the name of a file to open.
1723 The second value ($filename) is the name given to Twitter for the
1724 file. If $filename is not provided, the basename portion of $file
1725 is used. If $mime_type is not provided, it will be provided
1726 automatically using LWP::MediaTypes::guess_media_type().
1727 $raw_image_data can be provided, rather than opening a file, by
1729 passing "undef" as the first array value.
1730 The Tweet text will be rewritten to include the media URL(s), which
1732 will reduce the number of characters allowed in the Tweet text. If
1733 the URL(s) cannot be appended without text truncation, the tweet
1734 will be rejected and this method will return an HTTP 403 error.
1735 Returns: Status
1737 user_suggestions
1739 user_suggestions(category)
1740 alias: follow_suggestions
1741 Parameters: category, lang
1742 Required: category
1743 Access the users in a given category of the Twitter suggested user
1745 list and return their most recent status if they are not a
1746 protected user. Currently supported values for optional parameter
1747 "lang" are "en", "fr", "de", "es", "it". Does not require
1748 authentication.
1749 Returns: ArrayRef
1751 user_timeline
1753 Parameters: id, user_id, screen_name, since_id, max_id, count,
1754 page, skip_user, trim_user, include_entities, include_rts
1755 Required: none
1756 Returns the 20 most recent statuses posted from the authenticating
1758 user. It's also possible to request another user's timeline via the
1759 id parameter. This is the equivalent of the Web /archive page for
1760 your own user, or the profile page for a third party.
1761 Returns: ArrayRef[Status]
1763 users_search
1765 users_search(q)
1766 alias: find_people
1767 alias: search_users
1768 Parameters: q, per_page, page, include_entities
1769 Required: q
1770 Run a search for users similar to Find People button on
1772 Twitter.com; the same results returned by people search on
1773 Twitter.com will be returned by using this API (about being listed
1774 in the People Search). It is only possible to retrieve the first
1775 1000 matches from this API.
1776 Returns: ArrayRef[Users]
1778 verify_credentials
1780 verify_credentials(include_entities)
1781 Parameters: include_entities
1782 Required: none
1783 Returns an HTTP 200 OK response code and a representation of the
1785 requesting user if authentication was successful; returns a 401
1786 status code and an error message if not. Use this method to test
1787 if supplied user credentials are valid.
1788 Returns: ExtendedUser
1790
1792 search
1793 search(q)
1794 Parameters: q, callback, lang, locale, rpp, page, since_id, until,
1795 geocode, show_user, result_type
1796 Required: q
1797 Returns a HASH reference with some meta-data about the query
1799 including the "next_page", "refresh_url", and "max_id". The
1800 statuses are returned in "results". To iterate over the results,
1801 use something similar to:
1802 my $r = $nt->search($searh_term);
1804 for my $status ( @{$r->{results}} ) {
1805 print "$status->{text}\n";
1806 }
1807 Returns: HashRef
1809
1811 When "Net::Twitter::Lite" encounters a Twitter API error or a network
1812 error, it throws a "Net::Twitter::Lite::Error" object. You can catch
1813 and process these exceptions by using "eval" blocks and testing $@:
1814 eval {
1816 my $statuses = $nt->friends_timeline(); # this might die!
1817 for my $status ( @$statuses ) {
1819 #...
1820 }
1821 };
1822 if ( $@ ) {
1823 # friends_timeline encountered an error
1824 if ( blessed $@ && $@->isa('Net::Twitter::Lite::Error' ) {
1826 #... use the thrown error obj
1827 warn $@->error;
1828 }
1829 else {
1830 # something bad happened!
1831 die $@;
1832 }
1833 }
1834 "Net::Twitter::Lite::Error" stringifies to something reasonable, so if
1836 you don't need detailed error information, you can simply treat $@ as a
1837 string:
1838 eval { $nt->update($status) };
1840 if ( $@ ) {
1841 warn "update failed because: $@\n";
1842 }
1843
1845 Net::Twitter::Lite currently supports both Basic Authentication and
1846 OAuth. The choice of authentication strategies is determined by the
1847 options passed to "new" or the use of the "credentials" method. An
1848 error will be thrown if options for both strategies are provided.
1849 BASIC AUTHENTICATION
1851 To use Basic Authentication, pass the "username" and "password" options
1852 to "new", or call "credentials" to set them. When Basic Authentication
1853 is used, the "Authorization" header is set on each authenticated API
1854 call.
1855 OAUTH AUTHENTICATION
1857 To use OAuth authentication, pass the "consumer_key" and
1858 "consumer_secret" options to new.
1859 Net::OAuth::Simple must be installed in order to use OAuth and an error
1861 will be thrown if OAuth is attempted without it. Net::Twitter::Lite
1862 does not require Net::OAuth::Simple, making OAuth an optional feature.
1863 OAUTH EXAMPLES
1865 See the "examples" directory included in this distribution for full
1866 working examples using OAuth.
1867 Here's how to authorize users as a desktop app mode:
1869 use Net::Twitter::Lite;
1871 my $nt = Net::Twitter::Lite->new(
1873 consumer_key => "YOUR-CONSUMER-KEY",
1874 consumer_secret => "YOUR-CONSUMER-SECRET",
1875 );
1876 # You'll save the token and secret in cookie, config file or session database
1878 my($access_token, $access_token_secret) = restore_tokens();
1879 if ($access_token && $access_token_secret) {
1880 $nt->access_token($access_token);
1881 $nt->access_token_secret($access_token_secret);
1882 }
1883 unless ( $nt->authorized ) {
1885 # The client is not yet authorized: Do it now
1886 print "Authorize this app at ", $nt->get_authorization_url, " and enter the PIN#\n";
1887 my $pin = <STDIN>; # wait for input
1889 chomp $pin;
1890 my($access_token, $access_token_secret, $user_id, $screen_name) =
1892 $nt->request_access_token(verifier => $pin);
1893 save_tokens($access_token, $access_token_secret); # if necessary
1894 }
1895 # Everything's ready
1897 In a web application mode, you need to save the oauth_token and
1899 oauth_token_secret somewhere when you redirect the user to the OAuth
1900 authorization URL.
1901 sub twitter_authorize : Local {
1903 my($self, $c) = @_;
1904 my $nt = Net::Twitter::Lite->new(%param);
1906 my $url = $nt->get_authorization_url(callback => $callbackurl);
1907 $c->response->cookies->{oauth} = {
1909 value => {
1910 token => $nt->request_token,
1911 token_secret => $nt->request_token_secret,
1912 },
1913 };
1914 $c->response->redirect($url);
1916 }
1917 And when the user returns back, you'll reset those request token and
1919 secret to upgrade the request token to access token.
1920 sub twitter_auth_callback : Local {
1922 my($self, $c) = @_;
1923 my %cookie = $c->request->cookies->{oauth}->value;
1925 my $nt = Net::Twitter::Lite->new(%param);
1927 $nt->request_token($cookie{token});
1928 $nt->request_token_secret($cookie{token_secret});
1929 my $verifier = $c->req->param->{oauth_verifier};
1930 my($access_token, $access_token_secret, $user_id, $screen_name) =
1932 $nt->request_access_token(verifier => $verifier);
1933 # Save $access_token and $access_token_secret in the database associated with $c->user
1935 }
1936 Later on, you can retrieve and reset those access token and secret
1938 before calling any Twitter API methods.
1939 sub make_tweet : Local {
1941 my($self, $c) = @_;
1942 my($access_token, $access_token_secret) = ...;
1944 my $nt = Net::Twitter::Lite->new(%param);
1946 $nt->access_token($access_token);
1947 $nt->access_token_secret($access_token_secret);
1948 # Now you can call any Net::Twitter::Lite API methods on $nt
1950 my $status = $c->req->param('status');
1951 my $res = $nt->update({ status => $status });
1952 }
1953
1955 Net::Twitter::Lite::WithAPIv1_1
1956 With support for Twitter API v1.1
1957 Net::Twitter::Lite::Error
1959 The "Net::Twitter::Lite" exception object.
1960 <http://apiwiki.twitter.com/Twitter-API-Documentation>
1962 This is the official Twitter API documentation. It describes the
1963 methods and their parameters in more detail and may be more current
1964 than the documentation provided with this module.
1965 LWP::UserAgent::POE
1967 This LWP::UserAgent compatible class can be used in POE based
1968 application along with Net::Twitter::Lite to provide concurrent,
1969 non-blocking requests.
1970
1972 Please report bugs to "bug-net-twitter@rt.cpan.org", or through the web
1973 interface at <https://rt.cpan.org/Dist/Display.html?Queue=Net-Twitter>.
1974 Join the Net::Twitter IRC channel at <irc://irc.perl.org/net-twitter>.
1976 Follow perl_api: <http://twitter.com/perl_api>.
1978 Track Net::Twitter::Lite development at
1980 <http://github.com/semifor/net-twitter-lite>.
1981
1983 Marc Mims <marc@questright.com>
1984
1986 Chris Page <chris@starforge.co.uk>
1987
1989 Copyright (c) 2013 Marc Mims
1990 This library is free software; you can redistribute it and/or modify it
1992 under the same terms as Perl itself.
1993perl v5.36.0 2023-01-20 Net::Twitter::Lite(3pm)