README.rdoc

TweetStream¶ ↑

TweetStream provides simple Ruby access to Twitter’s Streaming API (apiwiki.twitter.com/Streaming-API-Documentation).

Installation¶ ↑

The TweetStream gem is available on GitHub and Gemcutter. To get the latest gem from GitHub:

gem sources -a http://gems.github.com/
gem install intridea-tweetstream

To install from Gemcutter:

gem sources -a http://gemcutter.org/
gem install tweetstream

Usage¶ ↑

Using TweetStream is quite simple:

require 'rubygems'
require 'tweetstream'

# This will pull a sample of all tweets based on
# your Twitter account's Streaming API role.
TweetStream::Client.new('username','password').sample do |status|
  # The status object is a special Hash with
  # method access to its keys.
  puts "#{status.text}"
end

You can also use it to track keywords or follow a given set of user ids:

# Use 'track' to track a list of single-word keywords
TweetStream::Client.new('username','password').track('term1', 'term2') do |status|
  puts "#{status.text}"
end

# Use 'follow' to follow a group of user ids (integers, not screen names)
TweetStream::Client.new('username','password').follow(14252, 53235) do |status|
  puts "#{status.text}"
end

The methods available to TweetStream::Client will be kept in parity with the methods available on the Streaming API wiki page.

Handling Deletes and Rate Limitations¶ ↑

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:

@client = TweetStream::Client.new('user','pass')

@client.on_delete do |status_id, user_id|
  Tweet.delete(status_id)
end

@client.on_limit do |skip_count|
  # do something
end  

@client.track('intridea')

The on_delete and on_limit methods can also be chained, like so:

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

You can also provide :delete and/or :limit options when you make your method call:

TweetStream::Client.new('user','pass').track('intridea',
  :delete => Proc.new{ |status_id, user_id| # do something },
  :limit => Proc.new{ |skip_count| # do something }
) do |status
  # do something with the status like normal
end

Twitter recommends honoring deletions as quickly as possible, and you would likely be wise to integrate this functionality into your application.

Terminating a TweetStream¶ ↑

It is often the case that you will need to change the parameters of your track or follow tweet streams. In the case that you need to terminate a stream, simply call <tt>TweetStream::Client.stop from within your loop:

# Stop after collecting 10 statuses
@statuses = []
TweetStream::Client.new('username','password').track('term1', 'term2') do |status|
  @statuses << status
  TweetStream::Client.stop if @statuses.size >= 10
end

When stop is called, TweetStream will return from the block the last successfully yielded status, allowing you to make note of it in your application as necessary.

Daemonizing¶ ↑

It is also possible to create a daemonized script quite easily using the TweetStream library:

# The third argument is an optional process name
TweetStream::Client.new('username','password', 'tracker').track('term1', 'term2') do |status|
  # do something in the background
end

If you put the above into a script and run the script with ruby scriptname.rb, you will see a list of daemonization commands such as start, stop, and run.

Note on Patches/Pull Requests¶ ↑

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Contributors¶ ↑

• Michael Bleigh (initial gem)

Copyright¶ ↑

Copyright © 2009 Intridea, Inc. (www.intridea.com/). See LICENSE for details.