Class: TwitterSearchWatcher

Inherits:
Object
  • Object
show all
Defined in:
lib/twitter-search-watcher.rb

Overview

Usage

coming soon

Constant Summary collapse

TWITTER_SEARCH_URL = 
'http://search.twitter.com/search.json'
DEFAULT_USER_AGENT = 
'TwitterSearchWatcher RubyGem http://github.com/devfu/twitter-search-watcher'
QUERY_STRING_ATTRIBUTES = 
[ :q, :to, :from, :since_id, :page, :max_id, :rpp ]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(search_string = nil, options = nil) ⇒ TwitterSearchWatcher

Create a new TwitterSearchWatcher

TwitterSearchWatcher.new 'string to search'
TwitterSearchWatcher.new 'string to search', :check_every => 60
TwitterSearchWatcher.new :to => 'barackobama', :from => 'SenJohnMcCain'



62
63
64
65
66
67
68
69
70
 
# File 'lib/twitter-search-watcher.rb', line 62

def initialize search_string = nil, options = nil
  if search_string.is_a? Hash
    options = search_string
  else
    self.q = search_string
  end

  options.each {|k,v| send "#{k}=", v } if options
end

Instance Attribute Details

#check_every ⇒ Object

The number of seconds to wait between Twitter calls. Default: 60 (seconds)



40
41
42
 
# File 'lib/twitter-search-watcher.rb', line 40

def check_every
  @check_every
end

#from ⇒ Object

The username of someone you want to search replies from



24
25
26
 
# File 'lib/twitter-search-watcher.rb', line 24

def from
  @from
end

#max_id ⇒ Object

Used for pagination, so you can get page=3 where the max_id of the first page was 1234



31
32
33
 
# File 'lib/twitter-search-watcher.rb', line 31

def max_id
  @max_id
end

#max_pages ⇒ Object

The maximum number of pages to check for tweets

If nil, we’ll check until there are no more pages (when :next_page isn’t present)



45
46
47
 
# File 'lib/twitter-search-watcher.rb', line 45

def max_pages
  @max_pages
end

#page ⇒ Object

Get a particular page of Twitter search results (pagination). Typically used in conjunction with :max_id



28
29
30
 
# File 'lib/twitter-search-watcher.rb', line 28

def page
  @page
end

#q ⇒ Object

A string you want to search twitter for



18
19
20
 
# File 'lib/twitter-search-watcher.rb', line 18

def q
  @q
end

#rpp ⇒ Object

Number of results per page (max 100)



37
38
39
 
# File 'lib/twitter-search-watcher.rb', line 37

def rpp
  @rpp
end

#since_id ⇒ Object

Only get tweets with ID’s greater than this ID (useful for only getting new tweets)



34
35
36
 
# File 'lib/twitter-search-watcher.rb', line 34

def since_id
  @since_id
end

#to ⇒ Object

The username of someone you want to search replies to



21
22
23
 
# File 'lib/twitter-search-watcher.rb', line 21

def to
  @to
end

#user_agent ⇒ Object

The User-Agent header value to send along with all Twitter Search API requests



15
16
17
 
# File 'lib/twitter-search-watcher.rb', line 15

def user_agent
  @user_agent
end

Class Method Details

.get(url, options = {}) ⇒ Object

Helper to do an HTTP GET request and return the response body



160
161
162
 
# File 'lib/twitter-search-watcher.rb', line 160

def self.get url, options = {}
  open( url, { 'User-Agent' => DEFAULT_USER_AGENT }.merge(options) ).read
end

.json(url) ⇒ Object

Helper to #get a url and return the response body parsed as JSON



170
171
172
 
# File 'lib/twitter-search-watcher.rb', line 170

def self.json url
  JSON.parse get(url)
end

.search_with_pagination!(search_string, options = nil) ⇒ Object

Instantiates a new TwitterSearchWatcher given the search_string and options and then calls search_with_pagination! on the instance, returning the response.

tweets_json = TwitterSearchWatcher.search_with_pagination!('foo')['results']



179
180
181
182
 
# File 'lib/twitter-search-watcher.rb', line 179

def self.search_with_pagination! search_string, options = nil
  watcher = TwitterSearchWatcher.new search_string, options
  watcher.search_with_pagination!
end

.watch!(search_string, options = nil, &block) ⇒ Object

Instantiates a new TwitterSearchWatcher given the search_string and options and then calls #watch on the instance using the block given.



186
187
188
189
 
# File 'lib/twitter-search-watcher.rb', line 186

def self.watch! search_string, options = nil, &block
  watcher = TwitterSearchWatcher.new search_string, options
  watcher.watch! &block
end

Instance Method Details

#get(url) ⇒ Object

Helper to do an HTTP GET request and return the response body



155
156
157
 
# File 'lib/twitter-search-watcher.rb', line 155

def get url
  TwitterSearchWatcher.get url, 'User-Agent' => user_agent
end

#json(url) ⇒ Object

Helper to #get a url and return the response body parsed as JSON



165
166
167
 
# File 'lib/twitter-search-watcher.rb', line 165

def json url
  JSON.parse get(url)
end

#search!(additional_parameters = nil) ⇒ Object

Performs a search. Accepts the same parameters as #search_url



94
95
96
 
# File 'lib/twitter-search-watcher.rb', line 94

def search! additional_parameters = nil
  json search_url(additional_parameters)
end

#search_more!(response, additional_parameters = nil) ⇒ Object

Performs a search, given the response from another search.

If the response given is paginated (ie. there are additional tweets available on additional pages), this will return the next page. Else, this will return nil.

Accepts additional parameters (same as #search_url)



118
119
120
 
# File 'lib/twitter-search-watcher.rb', line 118

def search_more! response, additional_parameters = nil
  search!( (additional_parameters || {}).merge( :page => (response['page'] + 1), :max_id => response['max_id'] ) ) if response['next_page']
end

#search_newer!(response = nil, additional_parameters = nil) ⇒ Object

Performs a search, given the response from another search.

If a response if given, the search will only return tweets newer than the given response’s tweets. If a response is not given, this performs a normal search.

Accepts additional parameters (same as #search_url)



104
105
106
107
108
109
110
 
# File 'lib/twitter-search-watcher.rb', line 104

def search_newer! response = nil, additional_parameters = nil
  if response
    search!( (additional_parameters || {}).merge( :since_id => response['max_id'] ) )
  else
    search! additional_parameters
  end
end

#search_url(additional_parameters = nil) ⇒ Object

Returns the URL we’ll use to call the Twitter Search API.

Without parameters, it’ll generate a URL just from this TwitterSearchWatcher instance.

With parameters, it’ll override the TwitterSearchWatcher instance’s options with whatever you pass, eg.

>> TwitterSearchWatcher.new( 'foo', :rpp => 15 ).search_url
=> "http://search.twitter.com/search.json?q=foo&rpp=15"

>> TwitterSearchWatcher.new( 'foo', :rpp => 15 ).search_url( :rpp => 99 )
=> "http://search.twitter.com/search.json?q=foo&rpp=99"



85
86
87
 
# File 'lib/twitter-search-watcher.rb', line 85

def search_url additional_parameters = nil
  TWITTER_SEARCH_URL + build_query_string(additional_parameters)
end

#search_with_pagination!(additional_parameters = nil) ⇒ Object

Performs a search! and search_more! as needed to return a response with all pages of tweets.

This respects max_pages and will only make max_pages number of additional requests to get paginated tweets.

The response object returned is similar to the responses returned by all other methods, but we only currently have a ‘results’ key on the Hash returned. If you’re used to getting some of the other keys returned by the other methods (which Twitter returns), be warned!

To get the tweets off of the response:

tweets = watcher.search_with_pagination!['results']



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/twitter-search-watcher.rb', line 133

def search_with_pagination! additional_parameters = nil
  response     = search! additional_parameters

  max_requests = max_pages
  max_requests = additional_parameters[:max_pages] if additional_parameters && additional_parameters[:max_pages]

  tweets = { 'results' => [] }
  pages_requested_so_far = 0

  if response['next_page']
    while response = search_more!(response)
      tweets['results'] << response['results']
      pages_requested_so_far += 1

      break if max_requests && pages_requested_so_far >= max_requests
    end
  end

  tweets
end

#watch!(additional_parameters = nil, &block) ⇒ Object

Starts watching this search in a loop. It will wait #check_every seconds between new requests (except requests to get additional pages). Every time a new tweet is found, that tweet is passed to the block given.

TwitterSearchWatcher.new('foo').watch! {|tweet| puts "got tweet: #{ tweet.text }" }



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/twitter-search-watcher.rb', line 197

def watch! additional_parameters = nil, &block
  @max_id_found_so_far = 0

  trap('INT'){ puts "\nexiting ..."; exit }
  puts "Watching for tweets: #{ search_url(additional_parameters) }"

  loop do

    @last_response = search_newer!(@last_response, additional_parameters)
    call_tweet_callbacks(@last_response, block)
    update_max_id @last_response

    # this is kindof icky ... but it works
    if @last_response['next_page']
      response = @last_response
      num_pages_searched = 0
      while (response = search_more!(response, additional_parameters)) && (num_pages_searched <= max_pages if max_pages)
        num_pages_searched += 1
        call_tweet_callbacks(response, block)
        update_max_id response
      end
    end

    sleep check_every
  end
end