Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A RubyGem to access the Twitter Streaming API.
branch: master

This branch is 364 commits behind tweetstream:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.document
.gitignore
LICENSE
README.rdoc
Rakefile
VERSION
tweetstream.gemspec

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 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::Daemon.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.

Something went wrong with that request. Please try again.