1Net::Twitter::Lite::WitUhsAePrIvC1o_n1t(r3ipbmu)ted PerlNeDto:c:uTmweintttaetri:o:nLite::WithAPIv1_1(3pm)
2
6 Net::Twitter::Lite::WithAPIv1_1 - A perl interface to the Twitter API
7 v1.1
8
10 version 0.12008
11
13 use Net::Twitter::Lite::WithAPIv1_1;
14 use Scalar::Util 'blessed';
15 my $nt = Net::Twitter::Lite::WithAPIv1_1->new(
17 consumer_key => $consumer_key,
18 consumer_secret => $consumer_secret,
19 access_token => $token,
20 access_token_secret => $token_secret,
21 );
22 my $result = $nt->update('Hello, world!');
24 eval {
26 my $statuses = $nt->home_timeline({ since_id => $high_water, count => 100 });
27 for my $status ( @$statuses ) {
28 print "$status->{created_at} <$status->{user}{screen_name}> $status->{text}\n";
29 }
30 };
31 if ( my $err = $@ ) {
32 die $@ unless blessed $err && $err->isa('Net::Twitter::Lite::Error');
33 warn "HTTP Response Code: ", $err->code, "\n",
35 "HTTP Message......: ", $err->message, "\n",
36 "Twitter error.....: ", $err->error, "\n";
37 }
38
40 This module provides a perl interface to the Twitter APIs. See
41 <https://dev.twitter.com/docs/api/1.1/overview> for a full description
42 of the Twitter APIs.
43
45 Net::Twitter::Lite decodes the data structures returned by the Twitter
46 API into native perl data structures (HASH references and ARRAY
47 references). The full layout of those data structures are not
48 documented, here. They change often, usually with the addition of new
49 elements, and documenting all of those changes would be a significant
50 challenge.
51 Instead, rely on the online Twitter API documentation and inspection of
53 the returned data.
54 The Twitter API online documentation is located at
56 <https://dev.twitter.com/docs/api/1.1/overview>.
57 To inspect the data, use Data::Dumper or similar module of your choice.
59 Here's a simple example using Data::Dumper:
60 use Data::Dumper;
62 my $r = $nt->search($search_term);
64 print Dumper $r;
65 For more information on perl data structures, see perlreftut, perldsc,
67 and perllol.
68
70 new This constructs a "Net::Twitter::Lite::WithAPIv1_1" object. It
71 takes several named parameters, all of them optional:
72 clientname
74 The value for the "X-Twitter-Client-Name" HTTP header. It
75 defaults to "Perl Net::Twitter::Lite::WithAPIv1_1". Note: This
76 option has nothing to do with the "via" application byline.
77 clientver
79 The value for the "X-Twitter-Client-Version" HTTP header. It
80 defaults to current version of this module.
81 clienturl
83 The value for the "X-Twitter-Client-URL" HTTP header. It
84 defaults to the search.cpan.org page for the
85 "Net::Twitter::Lite" distribution.
86 useragent_class
88 The "LWP::UserAgent" compatible class used internally to make
89 HTTP requests. It defaults to "LWP::UserAgent". For POE based
90 applications, consider using "LWP::UserAgent::POE".
91 useragent_args
93 An HASH ref of arguments to pass to constructor of the class
94 specified with "useragent_class", above. It defaults to {} (an
95 empty HASH ref).
96 useragent
98 The value for "User-Agent" HTTP header. It defaults to
99 "Net::Twitter::Lite::WithAPIv1_1/$VERSION (Perl)", where
100 $VERSION is the current version of this module.
101 source
103 Twitter on longer uses the "source" parameter. Support for it
104 remains in this module for any compatible services that may use
105 it. It was originally used by Twitter to provide an "via"
106 application byline.
107 apiurl
109 The URL for the Twitter API. This defaults to
110 "http://api.twitter.com/1.1". This option is available when
111 the "API::RESTv1_1" trait is included.
112 upload_url
114 Base URL for media uploads. Defaults to
115 "https://upload.twitter.com/1.1".
116 apirealm
118 A string containing the Twitter API realm used for Basic
119 Authentication. It defaults to "Twitter API". This option is
120 available when the "API::RESTv1_1" trait is included.
121 identica
123 If set to 1, "Net::Twitter::Lite::WithAPIv1_1" overrides the
124 defaults for "apiurl", "apihost", and "apirealm" to
125 "http://identi.ca/api", "identi.ca:80", and "Laconica API"
126 respectively. It defaults to 0.
127 consumer_key
129 A string containing the OAuth consumer key provided by Twitter
130 when an application is registered. This option is available
131 when the "OAuth" trait is included.
132 consumer_secret
134 A string containing the OAuth consumer secret. This option is
135 available when the "OAuth" trait is included.
136 ssl If set to 1, an SSL connection will be used for all API calls.
138 Defaults to 1.
139 netrc
141 (Optional) Sets the machine key to look up in ".netrc" to
142 obtain credentials. If set to 1, will use the value of the
143 "netrc_machine" option (below).
144 # in .netrc
146 machine api.twitter.com
147 login YOUR_TWITTER_USER_NAME
148 password YOUR_TWITTER_PASSWORD
149 machine semifor.twitter.com
150 login semifor
151 password SUPERSECRET
152 # in your perl program
154 $nt = Net::Twitter::Lite::WithAPIv1_1->new(netrc => 1);
155 $nt = Net::Twitter::Lite::WithAPIv1_1->new(netrc => 'semifor.twitter.com');
156 netrc_machine
158 (Optional) Sets the "machine" entry to look up in ".netrc" when
159 "<netrc =" 1>> is used. Defaults to "api.twitter.com".
160 wrap_result
162 (Optional) If set to 1, this option will return an
163 Net::Twitter::Lite::WrapResult object, which provides both the
164 Twitter API result and the HTTP::Response object for the API
165 call. See Net::Twitter::Lite::WrapResult for details.
166 credentials($username, $password)
168 Set the credentials for Basic Authentication. This is helpful for
169 managing multiple accounts.
170
172 With Twitter API version 1.1, all API calls require OAuth. Other
173 Twitter compatible services, like Identi.ca, accept Basic
174 Authentication. So, this module provides support for both.
175 For OAuth authentication, provide "consumer_key" and "consumer_secret"
177 arguments to "new". Set "access_token" and "access_token_secret" for
178 each call, or provide them as arguments to "new".
179 For Basic Authentication, provide the "username" and "password" options
181 to "new" or call the "credentials" method.
182 In addition to the arguments specified for each API method described
184 below, an additional "authenticate" parameter can be passed. To
185 request an "Authorization" header, pass "authenticate => 1"; to
186 suppress an authentication header, pass "authenticate => 0". Even if
187 requested, an Authorization header will not be added if there are no
188 user credentials (username and password for Basic Authentication;
189 access tokens for OAuth).
190 This is probably only useful for non-Twitter sites that use the Twitter
192 API and support unauthenticated calls.
193
195 Most Twitter API methods take parameters. All API methods will accept
196 a HASH ref of named parameters as specified in the Twitter API
197 documentation. For convenience, many methods accept simple positional
198 arguments. The positional parameter passing style is optional; you can
199 always use the named parameters in a HASH reference if you prefer.
200 You may pass any number of required parameters as positional
202 parameters. You must pass them in the order specified in the
203 documentation for each method. Optional parameters must be passed as
204 named parameters in a HASH reference. The HASH reference containing
205 the named parameters must be the final parameter to the method call.
206 Any required parameters not passed as positional parameters, must be
207 included in the named parameter HASH reference.
208 For example, the REST API method "update" has one required parameter,
210 "status". You can call "update" with a HASH ref argument:
211 $nt->update({ status => 'Hello world!' });
213 Or, you can use the convenient, positional parameter form:
215 $nt->update('Hello world!');
217 The "update" method also has an optional parameter,
219 "in_reply_to_status_id". To use it, you must use the HASH ref form:
220 $nt->update({ status => 'Hello world!', in_reply_to_status_id => $reply_to });
222 You may use the convenient positional form for the required "status"
224 parameter with the optional parameters specified in the named parameter
225 HASH reference:
226 $nt->update('Hello world!', { in_reply_to_status_id => $reply_to });
228 Convenience form is provided for the required parameters of all API
230 methods. So, these two calls are equivalent:
231 $nt->friendship_exists({ user_a => $fred, user_b => $barney });
233 $nt->friendship_exists($fred, $barney);
234 Many API methods have aliases. You can use the API method name, or any
236 of its aliases, as you prefer. For example, these calls are all
237 equivalent:
238 $nt->friendship_exists($fred, $barney);
240 $nt->relationship_exists($fred, $barney);
241 $nt->follows($fred, $barney);
242 Aliases support both the HASH ref and convenient forms:
244 $nt->follows({ user_a => $fred, user_b => $barney });
246 Synthetic Arguments
248 In addition to the arguments described in the Twitter API Documentation
249 for each API method, these additional synthetic arguments are
250 supported.
251 authenticate
253 When set to 1, an Authorization header for the API call will be
254 provided; when set to 0, it will suppress the Authentication
255 header. This argument overrides the defined authentication
256 behavior for the API method. It is probably only useful for the
257 "rate_limit_satus" method which returns different values for
258 authenticated and unauthenticated calls. See "AUTHENTICATION" for
259 more details.
260
262 account_settings
263 Parameters: none
264 Required: none
265 Returns the current trend, geo and sleep time information for the
267 authenticating user.
268 Returns: HashRef
270 add_list_member
272 Parameters: list_id, slug, user_id, screen_name, owner_screen_name,
273 owner_id
274 Required: none
275 Add a member to a list. The authenticated user must own the list to
277 be able to add members to it. Note that lists can't have more than
278 500 members.
279 Returns: User
281 add_place
283 add_place(name, contained_within, token, lat, long)
284 Parameters: name, contained_within, token, lat, long,
285 attribute:street_address, callback
286 Required: name, contained_within, token, lat, long
287 Creates a new place object at the given latitude and longitude.
289 Before creating a place you need to query "similar_places" with the
291 latitude, longitude and name of the place you wish to create. The
292 query will return an array of places which are similar to the one
293 you wish to create, and a token. If the place you wish to create
294 isn't in the returned array you can use the token with this method
295 to create a new one.
296 Returns: Place
298 blocking
300 alias: blocks_list
301 Parameters: cursor, include_entities, skip_status
302 Required: none
303 Returns an array of user objects that the authenticating user is
305 blocking.
306 Returns: ArrayRef[BasicUser]
308 blocking_ids
310 alias: blocks_ids
311 Parameters: cursor, stringify_ids
312 Required: none
313 Returns an array of numeric user ids the authenticating user is
315 blocking.
316 Returns: ArrayRef[Int]
318 contributees
320 Parameters: user_id, screen_name, include_entities, skip_satus
321 Required: none
322 Returns an array of users that the specified user can contribute
324 to.
325 Returns: ArrayRef[User]
327 contributors
329 Parameters: user_id, screen_name, include_entities, skip_satus
330 Required: none
331 Returns an array of users who can contribute to the specified
333 account.
334 Returns: ArrayRef[User]
336 create_block
338 create_block(id)
339 Parameters: user_id, screen_name, include_entities, skip_status
340 Required: id
341 Blocks the user specified in the "user_id" or "screen_name"
343 parameter as the authenticating user. Returns the blocked user
344 when successful. You can find out more about blocking in the
345 Twitter Support Knowledge Base.
346 Returns: BasicUser
348 create_favorite
350 create_favorite(id)
351 Parameters: id, include_entities
352 Required: id
353 Favorites the status specified in the ID parameter as the
355 authenticating user. Returns the favorite status when successful.
356 Returns: Status
358 create_friend
360 alias: follow
361 alias: follow_new
362 alias: create_friendship
363 Parameters: user_id, screen_name, follow
364 Required: none
365 Follows the user specified in the "user_id" or "screen_name"
367 parameter as the authenticating user. Returns the befriended user
368 when successful. Returns a string describing the failure condition
369 when unsuccessful.
370 Returns: BasicUser
372 create_list
374 create_list(name)
375 Parameters: list_id, slug, name, mode, description,
376 owner_screen_name, owner_id
377 Required: name
378 Creates a new list for the authenticated user. Note that you can't
380 create more than 20 lists per account.
381 Returns: List
383 create_saved_search
385 create_saved_search(query)
386 Parameters: query
387 Required: query
388 Creates a saved search for the authenticated user.
390 Returns: SavedSearch
392 delete_list
394 Parameters: owner_screen_name, owner_id, list_id, slug
395 Required: none
396 Deletes the specified list. The authenticated user must own the
398 list to be able to destroy it.
399 Returns: List
401 delete_list_member
403 alias: remove_list_member
404 Parameters: list_id, slug, user_id, screen_name, owner_screen_name,
405 owner_id
406 Required: none
407 Removes the specified member from the list. The authenticated user
409 must be the list's owner to remove members from the list.
410 Returns: User
412 destroy_block
414 destroy_block(id)
415 Parameters: user_id, screen_name, include_entities, skip_status
416 Required: id
417 Un-blocks the user specified in the "user_id" or "screen_name"
419 parameter as the authenticating user. Returns the un-blocked user
420 when successful.
421 Returns: BasicUser
423 destroy_direct_message
425 destroy_direct_message(id)
426 Parameters: id, include_entities
427 Required: id
428 Destroys the direct message specified in the required ID parameter.
430 The authenticating user must be the recipient of the specified
431 direct message.
432 Important: this method requires an access token with RWD (read,
434 write, and direct message) permissions.
435 Returns: DirectMessage
437 destroy_favorite
439 destroy_favorite(id)
440 Parameters: id, include_entities
441 Required: id
442 Un-favorites the status specified in the ID parameter as the
444 authenticating user. Returns the un-favorited status.
445 Returns: Status
447 destroy_friend
449 destroy_friend(id)
450 alias: unfollow
451 alias: destroy_friendship
452 Parameters: user_id, screen_name
453 Required: id
454 Discontinues friendship with the user specified in the "user_id" or
456 "screen_name" parameter as the authenticating user. Returns the
457 un-friended user when successful. Returns a string describing the
458 failure condition when unsuccessful.
459 Returns: BasicUser
461 destroy_saved_search
463 destroy_saved_search(id)
464 alias: delete_saved_search
465 Parameters: id
466 Required: id
467 Destroys a saved search. The search, specified by "id", must be
469 owned by the authenticating user.
470 Returns: SavedSearch
472 destroy_status
474 destroy_status(id)
475 Parameters: id, trim_user
476 Required: id
477 Destroys the status specified by the required ID parameter. The
479 authenticating user must be the author of the specified status.
480 Returns: Status
482 direct_messages
484 Parameters: since_id, max_id, count, page, include_entities,
485 skip_status
486 Required: none
487 Returns a list of the 20 most recent direct messages sent to the
489 authenticating user including detailed information about the
490 sending and recipient users.
491 Important: this method requires an access token with RWD (read,
493 write, and direct message) permissions.
494 Returns: ArrayRef[DirectMessage]
496 favorites
498 Parameters: user_id, screen_name, count, since_id, max_id,
499 include_entities
500 Required: none
501 Returns the 20 most recent favorite statuses for the authenticating
503 user or user specified by the ID parameter.
504 Returns: ArrayRef[Status]
506 followers
508 alias: followers_list
509 Parameters: user_id, screen_name, cursor
510 Required: none
511 Returns a cursored collection of user objects for users following
513 the specified user.
514 Returns: HashRef
516 followers_ids
518 Parameters: user_id, screen_name, cursor, stringify_ids
519 Required: none
520 Returns a reference to an array of numeric IDs for every user
522 following the specified user. The order of the IDs may change from
523 call to call. To obtain the screen names, pass the arrayref to
524 "lookup_users".
525 Use the optional "cursor" parameter to retrieve IDs in pages of
527 5000. When the "cursor" parameter is used, the return value is a
528 reference to a hash with keys "previous_cursor", "next_cursor", and
529 "ids". The value of "ids" is a reference to an array of IDS of the
530 user's followers. Set the optional "cursor" parameter to -1 to get
531 the first page of IDs. Set it to the prior return's value of
532 "previous_cursor" or "next_cursor" to page forward or backwards.
533 When there are no prior pages, the value of "previous_cursor" will
534 be 0. When there are no subsequent pages, the value of
535 "next_cursor" will be 0.
536 Returns: HashRef|ArrayRef[Int]
538 friends
540 alias: friends_list
541 Parameters: user_id, screen_name, cursor
542 Required: none
543 Returns a cursored collection of user objects for users followed by
545 the specified user.
546 Returns: HashRef
548 friends_ids
550 alias: following_ids
551 Parameters: user_id, screen_name, cursor, stringify_ids
552 Required: none
553 Returns a reference to an array of numeric IDs for every user
555 followed by the specified user. The order of the IDs is reverse
556 chronological.
557 Use the optional "cursor" parameter to retrieve IDs in pages of
559 5000. When the "cursor" parameter is used, the return value is a
560 reference to a hash with keys "previous_cursor", "next_cursor", and
561 "ids". The value of "ids" is a reference to an array of IDS of the
562 user's friends. Set the optional "cursor" parameter to -1 to get
563 the first page of IDs. Set it to the prior return's value of
564 "previous_cursor" or "next_cursor" to page forward or backwards.
565 When there are no prior pages, the value of "previous_cursor" will
566 be 0. When there are no subsequent pages, the value of
567 "next_cursor" will be 0.
568 Returns: HashRef|ArrayRef[Int]
570 friendships_incoming
572 alias: incoming_friendships
573 Parameters: cursor, stringify_ids
574 Required: none
575 Returns an HASH ref with an array of numeric IDs in the "ids"
577 element for every user who has a pending request to follow the
578 authenticating user.
579 Returns: HashRef
581 friendships_outgoing
583 alias: outgoing_friendships
584 Parameters: cursor, stringify_ids
585 Required: none
586 Returns an HASH ref with an array of numeric IDs in the "ids"
588 element for every protected user for whom the authenticating user
589 has a pending follow request.
590 Returns: HashRef
592 geo_id
594 geo_id(id)
595 Parameters: id
596 Required: id
597 Returns details of a place returned from the "reverse_geocode"
599 method.
600 Returns: HashRef
602 geo_search
604 Parameters: lat, long, query, ip, granularity, accuracy,
605 max_results, contained_within, attribute:street_address, callback
606 Required: none
607 Search for places that can be attached to a statuses/update. Given
609 a latitude and a longitude pair, an IP address, or a name, this
610 request will return a list of all the valid places that can be used
611 as the place_id when updating a status.
612 Conceptually, a query can be made from the user's location,
614 retrieve a list of places, have the user validate the location he
615 or she is at, and then send the ID of this location with a call to
616 statuses/update.
617 This is the recommended method to use find places that can be
619 attached to statuses/update. Unlike geo/reverse_geocode which
620 provides raw data access, this endpoint can potentially re-order
621 places with regards to the user who is authenticated. This approach
622 is also preferred for interactive place matching with the user.
623 Returns: HashRef
625 get_configuration
627 Parameters: none
628 Required: none
629 Returns the current configuration used by Twitter including
631 twitter.com slugs which are not usernames, maximum photo
632 resolutions, and t.co URL lengths.
633 It is recommended applications request this endpoint when they are
635 loaded, but no more than once a day.
636 Returns: HashRef
638 get_languages
640 Parameters: none
641 Required: none
642 Returns the list of languages supported by Twitter along with their
644 ISO 639-1 code. The ISO 639-1 code is the two letter value to use
645 if you include lang with any of your requests.
646 Returns: ArrayRef[Lanugage]
648 get_list
650 alias: show_list
651 Parameters: list_id, slug, owner_screen_name, owner_id
652 Required: none
653 Returns the specified list. Private lists will only be shown if the
655 authenticated user owns the specified list.
656 Returns: List
658 get_lists
660 alias: all_subscriptions
661 alias: list_lists all_subscriptions
662 Parameters: user_id, screen_name reverse
663 Required: none
664 Returns all lists the authenticating or specified user subscribes
666 to, including their own. The user is specified using the user_id or
667 screen_name parameters. If no user is given, the authenticating
668 user is used.
669 A maximum of 100 results will be returned by this call. Subscribed
671 lists are returned first, followed by owned lists. This means that
672 if a user subscribes to 90 lists and owns 20 lists, this method
673 returns 90 subscriptions and 10 owned lists. The reverse method
674 returns owned lists first, so with "reverse =" 1>, 20 owned lists
675 and 80 subscriptions would be returned. If your goal is to obtain
676 every list a user owns or subscribes to, use <list_ownerships>
677 and/or "list_subscriptions" instead.
678 Returns: ArrayRef[Lists]
680 get_privacy_policy
682 Parameters: none
683 Required: none
684 Returns Twitter's privacy policy.
686 Returns: HashRef
688 get_tos
690 Parameters: none
691 Required: none
692 Returns the Twitter Terms of Service. These are not the same as the
694 Developer Rules of the Road.
695 Returns: HashRef
697 home_timeline
699 Parameters: since_id, max_id, count, exclude_replies,
700 contributor_details, include_entities, trim_user
701 Required: none
702 Returns the 20 most recent statuses, including retweets, posted by
704 the authenticating user and that user's friends.
705 Returns: ArrayRef[Status]
707 list_members
709 Parameters: list_id, slug, owner_screen_name, owner_id, cursor,
710 include_entities, skip_status
711 Required: none
712 Returns the members of the specified list. Private list members
714 will only be shown if the authenticated user owns the specified
715 list.
716 Returns: Hashref
718 list_memberships
720 Parameters: user_id, screen_name, cursor, filter_to_owned_lists
721 Required: none
722 Returns the lists the specified user has been added to. If user_id
724 or screen_name are not provided the memberships for the
725 authenticating user are returned.
726 Returns: Hashref
728 list_statuses
730 Parameters: list_id, slug, owner_screen_name, owner_id, since_id,
731 max_id, count, include_entities, include_rts
732 Required: none
733 Returns tweet timeline for members of the specified list.
735 Historically, retweets were not available in list timeline
736 responses but you can now use the include_rts=true parameter to
737 additionally receive retweet objects.
738 Returns: ArrayRef[Status]
740 list_subscribers
742 Parameters: list_id, slug, owner_screen_name, owner_id, cursor,
743 include_entities, skip_status
744 Required: none
745 Returns the subscribers of the specified list. Private list
747 subscribers will only be shown if the authenticated user owns the
748 specified list.
749 Returns: Hashref
751 lookup_friendships
753 Parameters: user_id, screen_name
754 Required: none
755 Returns the relationship of the authenticating user to the comma
757 separated list or ARRAY ref of up to 100 screen_names or user_ids
758 provided. Values for connections can be: following,
759 following_requested, followed_by, none. Requires authentication.
760 Returns: ArrayRef
762 lookup_users
764 Parameters: user_id, screen_name, include_entities
765 Required: none
766 Return up to 100 users worth of extended information, specified by
768 either ID, screen name, or combination of the two. The author's
769 most recent status (if the authenticating user has permission) will
770 be returned inline. This method is rate limited to 1000 calls per
771 hour.
772 This method will accept user IDs or screen names as either a comma
774 delimited string, or as an ARRAY ref. It will also accept
775 arguments in the normal HASHREF form or as a simple list of named
776 arguments. I.e., any of the following forms are acceptable:
777 $nt->lookup_users({ user_id => '1234,6543,3333' });
779 $nt->lookup_users(user_id => '1234,6543,3333');
780 $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] });
781 $nt->lookup_users({ screen_name => 'fred,barney,wilma' });
782 $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']);
783 $nt->lookup_users(
785 screen_name => ['fred', 'barney' ],
786 user_id => '4321,6789',
787 );
788 Returns: ArrayRef[User]
790 members_create_all
792 alias: add_list_members
793 Parameters: list_id, slug, owner_screen_name, owner_id
794 Required: none
795 Adds multiple members to a list, by specifying a reference to an
797 array or a comma-separated list of member ids or screen names. The
798 authenticated user must own the list to be able to add members to
799 it. Note that lists can't have more than 500 members, and you are
800 limited to adding up to 100 members to a list at a time with this
801 method.
802 Returns: List
804 members_destroy_all
806 alias: remove_list_members
807 Parameters: list_id, slug, user_id, screen_name, owner_screen_name,
808 owner_id
809 Required: none
810 Removes multiple members from a list, by specifying a reference to
812 an array of member ids or screen names, or a string of comma
813 separated user ids or screen names. The authenticated user must
814 own the list to be able to remove members from it. Note that lists
815 can't have more than 500 members, and you are limited to removing
816 up to 100 members to a list at a time with this method.
817 Please note that there can be issues with lists that rapidly remove
819 and add memberships. Take care when using these methods such that
820 you are not too rapidly switching between removals and adds on the
821 same list.
822 Returns: List
824 mentions
826 alias: replies
827 alias: mentions_timeline
828 Parameters: since_id, max_id, count, trim_user, include_entities,
829 contributor_details
830 Required: none
831 Returns the 20 most recent mentions (statuses containing @username)
833 for the authenticating user.
834 Returns: ArrayRef[Status]
836 new_direct_message
838 new_direct_message(text)
839 Parameters: user_id, screen_name, text
840 Required: text
841 Sends a new direct message to the specified user from the
843 authenticating user. Requires both the user and text parameters.
844 Returns the sent message when successful. In order to support
845 numeric screen names, the "screen_name" or "user_id" parameters may
846 be used instead of "user".
847 Important: this method requires an access token with RWD (read,
849 write, and direct message) permissions.
850 Returns: DirectMessage
852 no_retweet_ids
854 Parameters: none
855 Required: none
856 Returns an ARRAY ref of user IDs for which the authenticating user
858 does not want to receive retweets.
859 Returns: ArrayRef[UserIDs]
861 oembed
863 Parameters: id, url, maxwidth, hide_media, hide_thread,
864 omit_script, align, related, lang
865 Required: none
866 Returns information allowing the creation of an embedded
868 representation of a Tweet on third party sites. See the oEmbed
869 <http://oembed.com/> specification for information about the
870 response format.
871 While this endpoint allows a bit of customization for the final
873 appearance of the embedded Tweet, be aware that the appearance of
874 the rendered Tweet may change over time to be consistent with
875 Twitter's Display Requirements
876 <https://dev.twitter.com/terms/display-requirements>. Do not rely
877 on any class or id parameters to stay constant in the returned
878 markup.
879 Returns: Status
881 profile_banner
883 Parameters: user_id, screen_name
884 Required: none
885 Returns a hash reference mapping available size variations to URLs
887 that can be used to retrieve each variation of the banner.
888 Returns: HashRef
890 rate_limit_status
892 rate_limit_status(resources)
893 Parameters: resources
894 Required: none
895 Returns the remaining number of API requests available to the
897 authenticated user before the API limit is reached for the current
898 hour.
899 Use "->rate_limit_status({ authenticate => 0 })" to force an
901 unauthenticated call, which will return the status for the IP
902 address rather than the authenticated user. (Note: for a web
903 application, this is the server's IP address.)
904 Returns: RateLimitStatus
906 remove_profile_banner
908 Parameters: none
909 Required: none
910 Removes the uploaded profile banner for the authenticating user.
912 Returns: Nothing
914 report_spam
916 report_spam(id)
917 Parameters: user_id, screen_name
918 Required: id
919 The user specified in the id is blocked by the authenticated user
921 and reported as a spammer.
922 Returns: User
924 retweet
926 retweet(id)
927 Parameters: idtrim_user
928 Required: id
929 Retweets a tweet.
931 Returns: Status
933 retweets
935 retweets(id)
936 Parameters: id, count, trim_user
937 Required: id
938 Returns up to 100 of the first retweets of a given tweet.
940 Returns: Arrayref[Status]
942 retweets_of_me
944 alias: retweeted_of_me
945 Parameters: since_id, max_id, count, trim_user, include_entities,
946 include_user_entities
947 Required: none
948 Returns the 20 most recent tweets of the authenticated user that
950 have been retweeted by others.
951 Returns: ArrayRef[Status]
953 reverse_geocode
955 reverse_geocode(lat, long)
956 Parameters: lat, long, accuracy, granularity, max_results, callback
957 Required: lat, long
958 Search for places (cities and neighborhoods) that can be attached
960 to a statuses/update. Given a latitude and a longitude, return a
961 list of all the valid places that can be used as a place_id when
962 updating a status. Conceptually, a query can be made from the
963 user's location, retrieve a list of places, have the user validate
964 the location he or she is at, and then send the ID of this location
965 up with a call to statuses/update.
966 There are multiple granularities of places that can be returned --
968 "neighborhoods", "cities", etc. At this time, only United States
969 data is available through this method.
970 lat Required. The latitude to query about. Valid ranges are -90.0
972 to +90.0 (North is positive) inclusive.
973 long
975 Required. The longitude to query about. Valid ranges are
976 -180.0 to +180.0 (East is positive) inclusive.
977 accuracy
979 Optional. A hint on the "region" in which to search. If a
980 number, then this is a radius in meters, but it can also take a
981 string that is suffixed with ft to specify feet. If this is
982 not passed in, then it is assumed to be 0m. If coming from a
983 device, in practice, this value is whatever accuracy the device
984 has measuring its location (whether it be coming from a GPS,
985 WiFi triangulation, etc.).
986 granularity
988 Optional. The minimal granularity of data to return. If this
989 is not passed in, then "neighborhood" is assumed. "city" can
990 also be passed.
991 max_results
993 Optional. A hint as to the number of results to return. This
994 does not guarantee that the number of results returned will
995 equal max_results, but instead informs how many "nearby"
996 results to return. Ideally, only pass in the number of places
997 you intend to display to the user here.
998 Returns: HashRef
1000 saved_searches
1002 Parameters: none
1003 Required: none
1004 Returns the authenticated user's saved search queries.
1006 Returns: ArrayRef[SavedSearch]
1008 search
1010 search(q)
1011 Parameters: q, count, callback, lang, locale, rpp, since_id,
1012 max_id, until, geocode, result_type, include_entities
1013 Required: q
1014 Returns a HASH reference with some meta-data about the query
1016 including the "next_page", "refresh_url", and "max_id". The
1017 statuses are returned in "results". To iterate over the results,
1018 use something similar to:
1019 my $r = $nt->search($searh_term);
1021 for my $status ( @{$r->{statuses}} ) {
1022 print "$status->{text}\n";
1023 }
1024 Returns: HashRef
1026 sent_direct_messages
1028 alias: direct_messages_sent
1029 Parameters: since_id, max_id, page, count, include_entities
1030 Required: none
1031 Returns a list of the 20 most recent direct messages sent by the
1033 authenticating user including detailed information about the
1034 sending and recipient users.
1035 Important: this method requires an access token with RWD (read,
1037 write, and direct message) permissions.
1038 Returns: ArrayRef[DirectMessage]
1040 show_direct_message
1042 show_direct_message(id)
1043 Parameters: id
1044 Required: id
1045 Returns a single direct message, specified by an id parameter. Like
1047 the "direct_messages" request, this method will include the user
1048 objects of the sender and recipient. Requires authentication.
1049 Important: this method requires an access token with RWD (read,
1051 write, and direct message) permissions.
1052 Returns: HashRef
1054 show_friendship
1056 alias: show_relationship
1057 Parameters: source_id, source_screen_name, target_id,
1058 target_screen_name
1059 Required: none
1060 Returns detailed information about the relationship between two
1062 users.
1063 Returns: Relationship
1065 show_list_member
1067 alias: is_list_member
1068 Parameters: owner_screen_name, owner_id, list_id, slug, user_id,
1069 screen_name, include_entities, skip_status
1070 Required: none
1071 Check if the specified user is a member of the specified list.
1073 Returns the user or undef.
1074 Returns: Maybe[User]
1076 show_list_subscriber
1078 alias: is_list_subscriber
1079 alias: is_subscriber_lists
1080 Parameters: owner_screen_name, owner_id, list_id, slug, user_id,
1081 screen_name, include_entities, skip_status
1082 Required: none
1083 Returns the user if they are a subscriber.
1085 Returns: User
1087 show_saved_search
1089 show_saved_search(id)
1090 Parameters: id
1091 Required: id
1092 Retrieve the data for a saved search, by "id", owned by the
1094 authenticating user.
1095 Returns: SavedSearch
1097 show_status
1099 show_status(id)
1100 Parameters: id, trim_user, include_entities, include_my_retweet
1101 Required: id
1102 Returns a single status, specified by the id parameter. The
1104 status's author will be returned inline.
1105 Returns: Status
1107 show_user
1109 Parameters: user_id, screen_name, include_entities
1110 Required: none
1111 Returns extended information of a given user, specified by ID or
1113 screen name as per the required id parameter. This information
1114 includes design settings, so third party developers can theme their
1115 widgets according to a given user's preferences. You must be
1116 properly authenticated to request the page of a protected user.
1117 Returns: ExtendedUser
1119 similar_places
1121 similar_places(lat, long, name)
1122 Parameters: lat, long, name, contained_within,
1123 attribute:street_address, callback
1124 Required: lat, long, name
1125 Locates places near the given coordinates which are similar in
1127 name.
1128 Conceptually you would use this method to get a list of known
1130 places to choose from first. Then, if the desired place doesn't
1131 exist, make a request to "add_place" to create a new one.
1132 The token contained in the response is the token needed to be able
1134 to create a new place.
1135 Returns: HashRef
1137 subscribe_list
1139 Parameters: owner_screen_name, owner_id, list_id, slug
1140 Required: none
1141 Subscribes the authenticated user to the specified list.
1143 Returns: List
1145 list_subscriptions
1147 Parameters: user_id, screen_name, count, cursor
1148 Required: none
1149 Aliases: subscriptions
1150 Obtain a collection of the lists the specified user is subscribed
1152 to, 20 lists per page by default. Does not include the user's own
1153 lists.
1154 Returns: ArrayRef[List]
1156 list_ownerships
1158 Parameters: user_id screen_name count cursor
1159 Obtain a collection of the lists owned by the specified Twitter
1161 user. Private lists will only be shown if the authenticated user is
1162 also the owner of the lists.
1163 Returns: Hashref
1165 suggestion_categories
1167 Parameters: none
1168 Required: none
1169 Returns the list of suggested user categories. The category slug
1171 can be used in the "user_suggestions" API method get the users in
1172 that category . Does not require authentication.
1173 Returns: ArrayRef
1175 trends_available
1177 Parameters: none
1178 Required: none
1179 Returns the locations with trending topic information. The response
1181 is an array of "locations" that encode the location's WOEID (a
1182 Yahoo! Where On Earth ID
1183 <http://developer.yahoo.com/geo/geoplanet/>) and some other human-
1184 readable information such as a the location's canonical name and
1185 country.
1186 For backwards compatibility, this method accepts optional "lat" and
1188 "long" parameters. You should call "trends_closest" directly,
1189 instead.
1190 Use the WOEID returned in the location object to query trends for a
1192 specific location.
1193 Returns: ArrayRef[Location]
1195 trends_closest
1197 Parameters: lat, long
1198 Required: none
1199 Returns the locations with trending topic information. The response
1201 is an array of "locations" that encode the location's WOEID (a
1202 Yahoo! Where On Earth ID
1203 <http://developer.yahoo.com/geo/geoplanet/>) and some other human-
1204 readable information such as a the location's canonical name and
1205 country. The results are sorted by distance from that location,
1206 nearest to farthest.
1207 Use the WOEID returned in the location object to query trends for a
1209 specific location.
1210 Returns: ArrayRef[Location]
1212 trends_place
1214 trends_place(id)
1215 alias: trends_location
1216 Parameters: id, exclude
1217 Required: id
1218 Returns the top 10 trending topics for a specific WOEID. The
1220 response is an array of "trend" objects that encode the name of the
1221 trending topic, the query parameter that can be used to search for
1222 the topic on Search, and the direct URL that can be issued against
1223 Search. This information is cached for five minutes, and therefore
1224 users are discouraged from querying these endpoints faster than
1225 once every five minutes. Global trends information is also
1226 available from this API by using a WOEID of 1.
1227 Returns: ArrayRef[Trend]
1229 unsubscribe_list
1231 Parameters: list_id, slug, owner_screen_name, owner_id
1232 Required: none
1233 Unsubscribes the authenticated user from the specified list.
1235 Returns: List
1237 update
1239 update(status)
1240 Parameters: status, lat, long, place_id, display_coordinates,
1241 in_reply_to_status_id, trim_user
1242 Required: status
1243 Updates the authenticating user's status. Requires the status
1245 parameter specified. A status update with text identical to the
1246 authenticating user's current status will be ignored.
1247 status
1249 Required. The text of your status update. URL encode as
1250 necessary. Statuses over 140 characters will cause a 403 error
1251 to be returned from the API.
1252 in_reply_to_status_id
1254 Optional. The ID of an existing status that the update is in
1255 reply to. o Note: This parameter will be ignored unless the
1256 author of the tweet this parameter references is mentioned
1257 within the status text. Therefore, you must include @username,
1258 where username is the author of the referenced tweet, within
1259 the update.
1260 lat Optional. The location's latitude that this tweet refers to.
1262 The valid ranges for latitude is -90.0 to +90.0 (North is
1263 positive) inclusive. This parameter will be ignored if outside
1264 that range, if it is not a number, if geo_enabled is disabled,
1265 or if there not a corresponding long parameter with this tweet.
1266 long
1268 Optional. The location's longitude that this tweet refers to.
1269 The valid ranges for longitude is -180.0 to +180.0 (East is
1270 positive) inclusive. This parameter will be ignored if outside
1271 that range, if it is not a number, if geo_enabled is disabled,
1272 or if there not a corresponding lat parameter with this tweet.
1273 place_id
1275 Optional. The place to attach to this status update. Valid
1276 place_ids can be found by querying "reverse_geocode".
1277 display_coordinates
1279 Optional. By default, geo-tweets will have their coordinates
1280 exposed in the status object (to remain backwards compatible
1281 with existing API applications). To turn off the display of
1282 the precise latitude and longitude (but keep the contextual
1283 location information), pass "display_coordinates =" 0> on the
1284 status update.
1285 Returns: Status
1287 update_account_settings
1289 Parameters: trend_location_woid, sleep_time_enabled,
1290 start_sleep_time, end_sleep_time, time_zone, lang
1291 Required: none
1292 Updates the authenticating user's settings.
1294 Returns: HashRef
1296 update_delivery_device
1298 update_delivery_device(device)
1299 Parameters: device, include_entities
1300 Required: device
1301 Sets which device Twitter delivers updates to for the
1303 authenticating user. Sending none as the device parameter will
1304 disable SMS updates.
1305 Returns: BasicUser
1307 update_friendship
1309 Parameters: user_id, screen_name, device, retweets
1310 Required: none
1311 Allows you enable or disable retweets and device notifications from
1313 the specified user. All other values are assumed to be false.
1314 Requires authentication.
1315 Returns: HashRef
1317 update_list
1319 Parameters: list_id, slug, name, mode, description,
1320 owner_screen_name, owner_id
1321 Required: none
1322 Updates the specified list. The authenticated user must own the
1324 list to be able to update it.
1325 Returns: List
1327 update_profile
1329 Parameters: name, url, location, description, include_entities,
1330 skip_status
1331 Required: none
1332 Sets values that users are able to set under the "Account" tab of
1334 their settings page. Only the parameters specified will be updated;
1335 to only update the "name" attribute, for example, only include that
1336 parameter in your request.
1337 Returns: ExtendedUser
1339 update_profile_background_image
1341 Parameters: image, tile, include_entities, skip_status, use
1342 Required: none
1343 Updates the authenticating user's profile background image. The
1345 "image" parameter must be an arrayref with the same interpretation
1346 as the "image" parameter in the "update_profile_image" method. See
1347 that method's documentation for details. The "use" parameter allows
1348 you to specify whether to use the uploaded profile background or
1349 not.
1350 Returns: ExtendedUser
1352 update_profile_banner
1354 update_profile_banner(banner)
1355 Parameters: banner, width, height, offset_left, offset_top
1356 Required: banner
1357 Uploads a profile banner on behalf of the authenticating user. The
1359 "image" parameter is an arrayref with the following interpretation:
1360 [ $file ]
1362 [ $file, $filename ]
1363 [ $file, $filename, Content_Type => $mime_type ]
1364 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
1365 The first value of the array ($file) is the name of a file to open.
1367 The second value ($filename) is the name given to Twitter for the
1368 file. If $filename is not provided, the basename portion of $file
1369 is used. If $mime_type is not provided, it will be provided
1370 automatically using LWP::MediaTypes::guess_media_type().
1371 $raw_image_data can be provided, rather than opening a file, by
1373 passing "undef" as the first array value.
1374 Returns: Nothing
1376 update_profile_colors
1378 Parameters: profile_background_color, profile_text_color,
1379 profile_link_color, profile_sidebar_fill_color,
1380 profile_sidebar_border_color, include_entities, skip_status
1381 Required: none
1382 Sets one or more hex values that control the color scheme of the
1384 authenticating user's profile page on twitter.com. These values
1385 are also returned in the /users/show API method.
1386 Returns: ExtendedUser
1388 update_profile_image
1390 update_profile_image(image)
1391 Parameters: image, include_entities, skip_status
1392 Required: image
1393 Updates the authenticating user's profile image. The "image"
1395 parameter is an arrayref with the following interpretation:
1396 [ $file ]
1398 [ $file, $filename ]
1399 [ $file, $filename, Content_Type => $mime_type ]
1400 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
1401 The first value of the array ($file) is the name of a file to open.
1403 The second value ($filename) is the name given to Twitter for the
1404 file. If $filename is not provided, the basename portion of $file
1405 is used. If $mime_type is not provided, it will be provided
1406 automatically using LWP::MediaTypes::guess_media_type().
1407 $raw_image_data can be provided, rather than opening a file, by
1409 passing "undef" as the first array value.
1410 Returns: ExtendedUser
1412 upload_media
1414 alias: upload
1415 Parameters: media, media_data, additional_owners
1416 Required: media or media_data
1417 The "media" parameter is an arrayref with the following
1419 interpretation:
1420 [ $file ]
1422 [ $file, $filename ]
1423 [ $file, $filename, Content_Type => $mime_type ]
1424 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
1425 The first value of the array ($file) is the name of a file to open.
1427 The second value ($filename) is the name given to Twitter for the
1428 file. If $filename is not provided, the basename portion of $file
1429 is used. If $mime_type is not provided, it will be provided
1430 automatically using LWP::MediaTypes::guess_media_type().
1431 $raw_image_data can be provided, rather than opening a file, by
1433 passing "undef" as the first array value.
1434 Or, pass base64-encoded data with the "media_data" parameter.
1436 Returns: Hashref with media_id.
1438 user_suggestions
1440 user_suggestions(category)
1441 alias: follow_suggestions
1442 Parameters: category, lang
1443 Required: category
1444 Access the users in a given category of the Twitter suggested user
1446 list and return their most recent status if they are not a
1447 protected user. Currently supported values for optional parameter
1448 "lang" are "en", "fr", "de", "es", "it". Does not require
1449 authentication.
1450 Returns: ArrayRef
1452 user_suggestions_for
1454 user_suggestions_for(category)
1455 alias: follow_suggestions
1456 Parameters: category, lang
1457 Required: category
1458 Access the users in a given category of the Twitter suggested user
1460 list.
1461 Returns: ArrayRef
1463 user_timeline
1465 Parameters: user_id, screen_name, since_id, max_id, count,
1466 trim_user, exclude_replies, include_rts, contributor_details
1467 Required: none
1468 Returns the 20 most recent statuses posted by the authenticating
1470 user, or the user specified by "screen_name" or "user_id".
1471 Returns: ArrayRef[Status]
1473 users_search
1475 users_search(q)
1476 alias: find_people
1477 alias: search_users
1478 Parameters: q, per_page, page, count, include_entities
1479 Required: q
1480 Run a search for users similar to Find People button on
1482 Twitter.com; the same results returned by people search on
1483 Twitter.com will be returned by using this API (about being listed
1484 in the People Search). It is only possible to retrieve the first
1485 1000 matches from this API.
1486 Returns: ArrayRef[Users]
1488 verify_credentials
1490 Parameters: include_entities, skip_status
1491 Required: none
1492 Returns an HTTP 200 OK response code and a representation of the
1494 requesting user if authentication was successful; returns a 401
1495 status code and an error message if not. Use this method to test
1496 if supplied user credentials are valid.
1497 Returns: ExtendedUser
1499 update_with_media
1501 update_with_media(status, media)
1502 Parameters: status, media[], possibly_sensitive,
1503 in_reply_to_status_id, lat, long, place_id, display_coordinates
1504 Required: status, media
1505 Updates the authenticating user's status and attaches media for
1507 upload.
1508 The "media[]" parameter is an arrayref with the following
1510 interpretation:
1511 [ $file ]
1513 [ $file, $filename ]
1514 [ $file, $filename, Content_Type => $mime_type ]
1515 [ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]
1516 The first value of the array ($file) is the name of a file to open.
1518 The second value ($filename) is the name given to Twitter for the
1519 file. If $filename is not provided, the basename portion of $file
1520 is used. If $mime_type is not provided, it will be provided
1521 automatically using LWP::MediaTypes::guess_media_type().
1522 $raw_image_data can be provided, rather than opening a file, by
1524 passing "undef" as the first array value.
1525 The Tweet text will be rewritten to include the media URL(s), which
1527 will reduce the number of characters allowed in the Tweet text. If
1528 the URL(s) cannot be appended without text truncation, the tweet
1529 will be rejected and this method will return an HTTP 403 error.
1530 Returns: Status
1532
1534 These methods are provided when trait "API::Search" is included in the
1535 "traits" option to "new".
1536 search
1538 search(q)
1539 Parameters: q, callback, lang, locale, rpp, page, since_id, until,
1540 geocode, show_user, result_type
1541 Required: q
1542 Returns a HASH reference with some meta-data about the query
1544 including the "next_page", "refresh_url", and "max_id". The
1545 statuses are returned in "results". To iterate over the results,
1546 use something similar to:
1547 my $r = $nt->search($searh_term);
1549 for my $status ( @{$r->{results}} ) {
1550 print "$status->{text}\n";
1551 }
1552 Returns: HashRef
1554
1556 These methods are provided when trait "API::TwitterVision" is included
1557 in the "traits" option to "new".
1558 current_status
1560 current_status(id)
1561 Parameters: id, callback
1562 Required: id
1563 Get the current location and status of a user.
1565 Returns: HashRef
1567 update_twittervision
1569 update_twittervision(location)
1570 Parameters: location
1571 Required: location
1572 Updates the location for the authenticated user.
1574 Returns: HashRef
1576
1578 When a Twitter API error or a network error is encountered,
1579 "Net::Twitter::Lite::Error" object is thrown. You can catch and
1580 process these exceptions by using "eval" blocks and testing $@:
1581 eval {
1583 my $statuses = $nt->friends_timeline(); # this might die!
1584 for my $status ( @$statuses ) {
1586 #...
1587 }
1588 };
1589 if ( $@ ) {
1590 # friends_timeline encountered an error
1591 if ( blessed $@ && $@->isa('Net::Twitter::Lite::Error') ) {
1593 #... use the thrown error obj
1594 warn $@->error;
1595 }
1596 else {
1597 # something bad happened!
1598 die $@;
1599 }
1600 }
1601 "Net::Twitter::Lite::Error" stringifies to something reasonable, so if
1603 you don't need detailed error information, you can simply treat $@ as a
1604 string:
1605 eval { $nt->update($status) };
1607 if ( $@ ) {
1608 warn "update failed because: $@\n";
1609 }
1610
1612 Net::Twitter::Lite::Error
1613 The "Net::Twitter::Lite" exception object.
1614 <http://dev.twitter.com/rest/reference>
1616 This is the official Twitter API documentation. It describes the
1617 methods and their parameters in more detail and may be more current
1618 than the documentation provided with this module.
1619 LWP::UserAgent::POE
1621 This LWP::UserAgent compatible class can be used in POE based
1622 application along with Net::Twitter::Lite to provide concurrent,
1623 non-blocking requests.
1624 Catalyst::Authentication::Credential::Twitter
1626 This module, by Jesse Stay, provides Twitter OAuth authentication
1627 support for the popular Catalyst web application framework.
1628 AnyEvent::Twitter::Stream
1630 An excellent module for Twitter Streaming API support.
1631
1633 Please report bugs at
1634 <https://github.com/semifor/net-twitter-lite/issues>.
1635 Join the #net-twitter IRC channel on irc.perl.org.
1637 Follow perl_api: <http://twitter.com/perl_api>.
1639 Track development at <http://github.com/semifor/net-twitter-lite>.
1641
1643 Marc Mims <marc@questright.com> (@semifor on Twitter)
1644
1646 Marek Foss (@f055)
1647
1649 Copyright (c) 2013 Marc Mims
1650 This library is free software; you can redistribute it and/or modify it
1652 under the same terms as Perl itself.
1653perl v5.28.1 2016-12-0N6et::Twitter::Lite::WithAPIv1_1(3pm)