Twitter’s Streaming API is one of the most exciting developments in the Twitter API in some time. It gives you the ability to create a long-standing connection to Twitter that receives “push” updates when new tweets matching certain criteria arrive, obviating the need to constantly poll for updates. TweetStream is a Ruby library to access the new API.
Installation
Installation of TweetStream is simple, it’s available as a gem on GitHub and Gemcutter.org. To install it from GitHub:
gem sources -a http://gems.github.com gem install intridea-tweetstream
To install it from Gemcutter:
gem sources -a http://gemcutter.org gem install tweetstream
Usage
TweetStream creates a long-standing HTTP connection to Twitter, so unlike other Twitter libraries you don’t simply run it once and deal with the results. Instead, you provide a block that will be yielded to with each new status that arrives. The most basic example is:
require 'rubygems' require 'tweetstream' TweetStream::Client.new('user','pass').sample do |status| puts "[#{status.user.screen_name}] #{status.text}" end
This will provide you with a small sample snapshot of all of the updates being posted to Twitter at this moment and print them to the screen. There are also methods available to track single-word keywords as well as the updates of a specified list of user ids (integers, not screen names). You can do that like so:
# Track the terms 'keyword1' and 'keyword2' TweetStream::Client.new('user','pass').track('keyword1', 'keyword2') do |status| puts "[#{status.user.screen_name}] #{status.text}" end # Track users with IDs 123 and 456 TweetStream::Client.new('user','pass').follow(123, 456) do |status| puts "[#{status.user.screen_name}] #{status.text}" end
Handling Deletion/Limit Notices (Updated in 0.1.4)
Sometimes the Streaming API will send messages other than statuses.
Specifically, it does so when a status is deleted or rate limitations
have caused some tweets not to appear in the stream. To handle these, you can use the on_delete and on_limit methods. Example:
TweetStream::Client.new('user','pass').on_delete{ |status_id, user_id| Tweet.delete(status_id) }.on_limit { |skip_count| # do something }.track('intridea') do |status| # do something with the status like normal end
Daemonization
One of the most useful features of TweetStream is its built-in daemonization functionality. This allows you to create scripts that run in the background of your machine rather than taking up an active process. To create a daemon script, you simply use TweetStream::Daemon instead of TweetStream::Client. Here’s an example:
require 'rubygems' require 'tweetstream' # The third argument is an optional process name. TweetStream::Daemon.new('user','pass','tracker').track('keyword1','keyword2') do |status| # Do something like dump the status to ActiveRecord # or anything else you want. end
If you were to place the above code in a file called tracker.rb you could then run ruby tracker.rb to see a list of daemonization commands such as start, stop, or run.
TweetStream is a simple wrapper on the Streaming API, but with built-in daemonization provides powerfully flexible means of accessing the Twitter Streaming API using familiar Ruby tools. More complete code documentation is available at rdoc.info.
Update: I overlooked the deletion and rate limit notices when I wrote the initial version of the gem. As of version 0.1.4 these are handled properly.
Sometimes you just want an application that gets something done quick and gets it done right -- especially if your stomach's calling. That's why we've decided to create iPho and iCurry for the iPhone.
