intridea-tweetstream

= TweetStream

TweetStream provides simple Ruby access to Twitter's Streaming API (http://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.

== 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 (c) 2009 Intridea, Inc. (http://www.intridea.com/). See LICENSE for details.