Twitter Search

Twitter Search is sweet. I use it every day to find first-person commentary on thoughtbot's work, Boston sports, national politics, or anything else that catches my fancy.

The Twitter Search API is also sweet. I wanted to use it for Politweets, a side project, to aggregate tweets on the U.S. presidential election from around the world within minutes of being published.

Dustin Sallings published a Ruby wrapper for the Summize API on GitHub. I forked it and added a test suite and documentation.

Introducing the Twitter Search gem! (Update: The Twitter Search gem was later merged into the Twitter gem.)


Install the gem.

gem install twitter-search

Require the gem.

require "twitter_search"

Set up a TwitterSearch::Client. Name your client (a.k.a. "user agent") to something meaningful, such as your app's name. This helps Twitter Search answer any questions about your use of the API.

@client ="politweets")

Request tweets by calling the query method of your client.

@tweets = @client.query(:q => "twitter search")

Search Operators

The following operator examples find tweets...

Foreign Languages

The Twitter Search API supports foreign languages, accessible via the :lang key. Use an ISO 639-1 code as the value:

@tweets = @client.query(:q => "programmé", :lang => "fr")

Result pagination

Alter the number of Tweets returned per page with the :rpp key. Stick with 10, 15, 20, 25, 30, or 50.

@tweets = @client.query(:q => "Boston Celtics", :rpp => "30")


Searching for a positive attitude :) returns tweets containing the text :), =), :D, and :-)

Searches are case-insensitive.

The near operator available in the Twitter Search web interface is not available via the API: You must geocode before making the API call and use the :geocode key in the request using the pattern lat,lngmi or lat,lngkm:

@tweets = @client.query(:q => "Pearl Jam", :geocode => "43.4411,-70.9846mi")

Usage with ActiveRecord and Cron

You can get fancier with your setup, using queuing or another approach, but here's an example using cron.


create_table "tweets", :force => true do |t|
  t.string   "user_name",          :limit => 20,  :default => "", :null => false
  t.string   "body",               :limit => 140, :default => "", :null => false
  t.datetime "created_at",                                        :null => false
  t.datetime "updated_at",                                        :null => false
  t.integer  "twitter_id",         :limit => 11

add_index "tweets", ["created_at"], :name => "index_tweets_on_created_at"
add_index "tweets", ["twitter_id"], :name => "index_tweets_on_twitter_id"

Request the API from a rake task, keeping the logic in a class so it can be easily tested:

class Twitter
  def self.import!
    # the implementation is up to you

Since I don't have the cron API memorized, I like to define cron jobs with crondle:

require "lib/crondle"

Crondle.define_jobs do |builder|
  rails_root = "/var/www/apps/politweets/current"

  [3, 9, 15, 21, 27, 33, 39, 45, 51, 57].each do |minute|
    builder.desc "Import tweets at #{minute} past the hour"
    builder.job "#{rails_root}/script/runner Twitter.import!", :minute => minute

Run the crondle script to get the text to enter into crontab -e:

# Import tweets at 3 past the hour
3 * * * * /var/www/apps/politweets/current/script/runner Twitter.import!

# Import tweets at 9 past the hour
9 * * * * /var/www/apps/politweets/current/script/runner Twitter.import!

And you're on your way.

Thanks to Doug, Gabe, Jason, Min, and Dustin for their work on Politweets and the Twitter Search gem.