require 'uri' require 'cgi' require 'yajl' require 'yajl/http_stream' module TweetStream # Provides simple access to the Twitter Streaming API (http://apiwiki.twitter.com/Streaming-API-Documentation) # for Ruby scripts that need to create a long connection to # Twitter for tracking and other purposes. # # Basic usage of the library is to call one of the provided # methods and provide a block that will perform actions on # a yielded TweetStream::Status. For example: # # TweetStream::Client.new('user','pass').track('fail') do |status| # puts "[#{status.user.screen_name}] #{status.text}" # end # # For information about a daemonized TweetStream client, # view the TweetStream::Daemon class. class Client attr_accessor :username, :password # Create a new client with the Twitter credentials # of the account you want to be using its API quota. def initialize(user, pass) self.username = user self.password = pass end # Returns all public statuses. The Firehose is not a generally # available resource. Few applications require this level of access. # Creative use of a combination of other resources and various access # levels can satisfy nearly every application use case. def firehose(query_parameters = {}, &block) start('statuses/firehose', query_parameters, &block) end # Returns all retweets. The retweet stream is not a generally available # resource. Few applications require this level of access. Creative # use of a combination of other resources and various access levels # can satisfy nearly every application use case. As of 9/11/2009, # the site-wide retweet feature has not yet launched, # so there are currently few, if any, retweets on this stream. def retweet(query_parameters = {}, &block) start('statuses/retweet', query_parameters, &block) end # Returns a random sample of all public statuses. The default access level # provides a small proportion of the Firehose. The "Gardenhose" access # level provides a proportion more suitable for data mining and # research applications that desire a larger proportion to be statistically # significant sample. def sample(query_parameters = {}, &block) start('statuses/sample', query_parameters, &block) end # Specify keywords to track. Queries are subject to Track Limitations, # described in Track Limiting and subject to access roles, described in # the statuses/filter method. Track keywords are case-insensitive logical # ORs. Terms are exact-matched, and also exact-matched ignoring # punctuation. Phrases, keywords with spaces, are not supported. # Keywords containing punctuation will only exact match tokens. # Query parameters may be passed as the last argument. def track(*keywords, &block) query_params = keywords.pop if keywords.last.is_a?(::Hash) query_params ||= {} filter(query_params.merge(:track => keywords), &block) end # Returns public statuses from or in reply to a set of users. Mentions # ("Hello @user!") and implicit replies ("@user Hello!" created without # pressing the reply "swoosh") are not matched. Requires integer user # IDs, not screen names. Query parameters may be passed as the last argument. def follow(*user_ids, &block) query_params = user_ids.pop if user_ids.last.is_a?(::Hash) query_params ||= {} filter(query_params.merge(:follow => user_ids), &block) end # Make a call to the statuses/filter method of the Streaming API, # you may provide :follow, :track or both as options # to follow the tweets of specified users or track keywords. This # method is provided separately for cases when it would conserve the # number of HTTP connections to combine track and follow. def filter(query_params = {}, &block) [:follow, :track].each do |param| if query_params[param].is_a?(Array) query_params[param] = query_params[param].collect{|q| q.to_s}.join(',') elsif query_params[param] query_params[param] = query_params[param].to_s end end start('statuses/filter', query_params, &block) end def start(path, query_parameters = {}, &block) #:nodoc: uri = build_uri(path, query_parameters) Yajl::HttpStream.get(uri, :symbolize_keys => true) do |hash| yield TweetStream::Status.new(hash) end end protected def build_uri(path, query_parameters = {}) #:nodoc: URI.parse("http://#{self.username}:#{self.password}@stream.twitter.com/1/#{path}.json#{build_query_parameters(query_parameters)}") end def build_query_parameters(query) #:nodoc: return '' unless query && query.is_a?(::Hash) && query.size > 0 pairs = [] query.each_pair do |k,v| pairs << "#{k.to_s}=#{CGI.escape(v.to_s)}" end "?#{pairs.join('&')}" end end end