This site has been deprecated. Do not edit pages here. Please visit the new Pico Labs documentation.


Skip to end of metadata
Go to start of metadata
Deprecated

This module is no longer supported in the KRL system.

 

The Twitter Library

The Twitter module in KRL gives you programmatic access to the Twitter API.  This documentation covers OAuth, Performance and twitter api function calls.

Please note that Twitter has stopped supporting API v1 methods. Twitter API v1.1 requires authentication for all queries. Please refer to Twitter API reference for an authoritative discussion of what methods are still supported in v1.1 For example, it appears that the friends timeline has been discontinued.

Twitter has dropped support for XML, Atom and RSS in v1.1

Please see the OAuthModule for additional resources for developers who would like to use KRL's OAuth module to perform queries directly to the Twitter API

 

OAuth

Register a Kynetx application with Twitter

Registering a kynetx application can be confusing.  Here is a list of best practices:

  • Use the same image for Twitter OAuth that you use in your card in AppBuilder for visual continuity.
  • You can say that it is a KRL application and that it's powered by Kynetx, but do not represent yourself as Kynetx
  • You can use your app's description page in the Kynetx App Directory as the application homepage if you like.
  • Choose "browser" as the application type.  You cannot leave the callback URL blank even though what you put there will not be used.  Put any URL you like there.
  • Make sure you set read or write access to your application.
  • After you save your changes, click back in and make sure they stuck.   

Keys and Secrets

To OAuth with Twitter you need to put your twitter consumer_key and cosumer_secret in the meta section of your ruleset.  You should use a different consumer key and secret for each Kynetx application you write.

An example of inserting a key with a ruleset is given below:

Authorization

Rulesets using the Twitter library will check to see if the user has authorized the ruleset to access the user's Twitter information.  If so, the app continues, and if not, it uses the twitter:authorize action to initiate an OAuth session with Twitter so that the user can make the authorization. 

An example of Authorizing a ruleset is given below:

Performance

Remember that any data you access in a KRL ruleset is turned into Javascript and sent to the browser and the Twitter API is verbose.  So retrieving several large timelines and using them will result in large data definitions being downloaded to the browser and consequent performance penalties.

Actions

authorize

The twitter:authorize action.  The action takes no parameters but is a special case of the notify action and takes the same options.

The following is an example of using twitter:authorize():

The following is a graphic of what this action looks like.  Notice that the application name, author, and description are all take from the meta section of the ruleset.

update

The twitter:update action.  The action takes a string that is the new twitter status for the OAuthed user.

The following is an example useing twitter:update:

Predicates

authorized

The twitter:authorized predicate can be used in the pre block of a rule.  The function returns whether or not the ruleset has been authorized with twitter

An example of twitter:authorized is given below:

Twitter API Functions

Once the user has authorized the ruleset to access their Twitter data, the functions described below can be used to interact with the Twitter API.  Remember that the data returned is specific to the user who authorized the access unless otherwise noted.  

The functions are based on the Net::Twitter::Lite Perl library.  You may also find the documentation for the Twitter API helpful in understanding how to interact with Twitter.  

The following descriptions of the functions list parameters that the function takes and notes any that are required.  The only way to pass arguments to the Twitter API functions is a hash with the name of the parameter and the value like so:

Methods that support the page parameter expect page numbers > 0.  Twitter silently ignores invalid page values.  So {"page": 0} produces the same result as {"page": 1}.

Several of these function accept a user ID as the id parameter.  The user ID can be a screen name, or the users numeric ID.  To disambiguate, use the screen_name or user_id parameters, instead.

All of these should be proceeded by the twitter namespace in use as seen in the previous examples.

The blocking function

The twitter:blocking function returns an array of user objects that the authenticating user is blocking.  To view details about parameters please see blocks/bloking in the Twitter api.

The following is an example of the twitter:blocking function:

The blocking_ids function

The twitter:blocking_ids function returns an array of numeric user ids the authenticating user is blocking.  To view details about parameters please see blocks/blocking/ids.

The following is an example of the twitter:blocking_ids function:

The favorites function

The twitter:favorites function returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter.  To view details about parameters see favorites

The following is an example of the twitter:favorites function:

The followers_ids function

The twitter:followers_ids function returns a reference to an array of numeric IDs for every user following the specified user. To view details about parameters see followers/ids

The following is an example of the twitter:followers_ids function:

The friends_ids function

The twitter:friends_ids returns an array of numeric IDs for every user followed by the specified user.  To view details about parameters see friends/ids

The following is an example of the twitter:friends_ids function:

The friends_timeline function

The twitter:friends_timeline returns the 20 most recent statuses posted by the authenticating user and that user's friends.  This is the equivalent of /home on the Web. To view details about parameters see statuses/friends_timeline.

The following is an example of the twitter:friends_timeline function:

The home_timeline function

The twitter:home_timeline returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user's friends. This is the equivalent of /timeline/home on the Web. To view details about parameters see statuses/home_timeline.

The following is an example of the twitter:home_timeline function:

The friendship_exists function

The twitter:friendship_exists tests for the existence of friendship between two users. Will return true if user_a follows user_b, otherwise will return false. To view details about parameters see friendships/exists.

The following is an example of the twitter:friendship_exists function:

The mentions function

The twitter:mentions returns the 20 most recent mentions (statuses containing \@username) for the authenticating user. To view details about parameters see statuses/mentions.

The following is an example of the twitter:mentions function:

The pulbic_timeline function

The twitter:public_timeline returns the 20 most recent statuses from non-protected users who have set a custom user icon. Does not require authentication. Note that the public timeline is cached for 60 seconds so requesting it more often than that is a waste of resources. To view details about parameters see statuses/friends_timeline.

The following is an example of the twitter:public_timeline function:

The rate_limit_status function

The twitter:rate_limit_status returns the remaining number of API requests available to the authenticated user before the API limit is reached for the current hour. To view details about parameters see account/rate_limit_status.

The following is an example of the twitter:rate_limit_status function:

The retweeted_by_me function

The twitter:retweeted_by_me returns the 20 most recent retweets posted by the authenticating user. To view details about parameters see statuses/retweeted_by_me.

The following is an example of the twitter:retweeted_by_me function:

The retweeted_of_me function

The twitter:retweeted_of_me returns the 20 most recent tweets of the authenticated user that have been retweeted by others. To view details about parameters see statuses/retweets_of_me.

The following is an example of the twitter:retweeted_of_me function:

The retweeted_to_me function

The twitter:retweeted_to_me returns the 20 most recent retweets posted by the authenticating user's friends. To view details about parameters see statuses/retweets_to_me.

The following is an example of the twitter:retweeted_to_me function:

The retweets function

The twitter:retweets returns up to 100 of the first retweets of a given tweet. To view details about parameters see statuses/retweeted_by_user.

The following is an example of the twitter:retweets function:

The saved_searches function

The twitter:saved_searches returns the authenticated user's saved search queries. To view details about parameters see saved_searches.

The following is an example of the twitter:saved_searches function:

The sent_direct_messages function

The twitter:sent_direct_messages returns a list of the 20 most recent direct messages sent by the authenticating user including detailed information about the sending and recipient users. To view details about parameters see direct_messages.

The following is an example of the twitter:sent_direct_messages function:

The show_friendship function

The twitter:show_friendship returns detailed information about the relationship between two users.. To view details about parameters see friendships/show.

The following is an example of the twitter:show_friendship function:

The show_saved_search function

The twitter:show_saved_search retrieve the data for a saved search, by ID, owned by the authenticating user. To view details about parameters see saved_searches/show/:id.

The following is an example of the twitter:show_saved_search function:

The show_status function

The twitter:show_status returns a single status, specified by the id parameter. The status's author will be returned inline. To view details about parameters see statuses/show/:id.

The following is an example of the twitter:show_status function:

The show_user function

The twitter:show_user returns extended information of a given user, specified by ID or screen name as per the required id parameter. This information includes design settings, so third party developers can theme their widgets according to a given user's preferences. You must be properly authenticated to request the page of a protected user. To view details about parameters see users/show.

The following is an example of the twitter:show_user function:

The trends_available function

The twitter:trends_available returns locations with trending topic information.  To view details about parameters see trends/available.

The following is an example of the twitter:trends_available function:

The trends_location function

The twitter:trends_location returns the top 10 trending topics for a specific location To view details about parameters see trends/:woeid.

The following is an example of the twitter:trends_location function:

The user_timeline function

The twitter:user_timeline returns the 20 most recent statuses posted from the authenticating user. It's also possible to request another user's timeline via the id parameter To view details about parameters see statuses/user_timeline.

The following is an example of the twitter:user_timeline function:

The users_search function

The twitter:users_search returns a HASH reference with some meta-data about the query including the next_page, refresh_url, and max_id. The statuses are returned in results.  To view details about parameters see users/search.

The following is an example of the twitter:users_search function:

The trends_daily function

The twitter:trends_daily returns the top 20 trending topics for each hour in a given day.  To view details about parameters see trends/daily.

The following is an example of the twitter:trends_daily function:

The trends_weekly function

The twitter:trends_weeky returns the top 30 trending topics for each day in a given week.  To view details about parameters see trends/weekly.

The following is an example of the twitter:trends_weekly function:

Labels:
  1. Jun 12, 2012

    Anonymous

    I thank you humbly for shranig your wisdom JJWY
  2. Jun 12, 2012

    Anonymous