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.