Class Twitter::Search
In: lib/twitter/search.rb
Parent: API

Wrapper for the Twitter Search API

@note As of April 1st 2010, the Search API provides an option to retrieve

  "popular tweets" in addition to real-time search results. In an upcoming release,
  this will become the default and clients that don't want to receive popular tweets
  in their search results will have to explicitly opt-out. See {Twitter::Search#result_type}
  for more information.

@note The user ids in the Search API are different from those in the REST API

  ({http://dev.twitter.com/pages/api_overview about the two APIs}). This defect is
  being tracked by {http://code.google.com/p/twitter-api/issues/detail?id=214 Issue 214}.
  This means that the to_user_id and from_user_id field vary from the actualy user id on
  Twitter.com. Applications will have to perform a screen name-based lookup with
  {Twitter::Client::User#user} to get the correct user id if necessary.

@see dev.twitter.com/doc/get/search Twitter Search API Documentation

Methods

Included Modules

Enumerable

External Aliases

search_endpoint -> api_endpoint

Attributes

query  [R]  @private

Public Class methods

Creates a new search

@example Initialize a Twitter search

  search = Twitter::Search.new

Public Instance methods

Clears all query filters and cached results

@return [Twitter::Search] self @example Clear a search for "twitter"

  search = Twitter::Search.new
  search.containing("twitter").fetch
  search.clear
  search.fetch_next_page #=> 403 Forbidden: You must enter a query.

Search query

@param query [String] The search query. @return [Twitter::Search] self @example Return an array of tweets containing "twitter"

  Twitter::Search.new.containing("twitter").fetch
  Twitter::Search.new.contains("twitter").fetch   # Shortcut for the above
  Twitter::Search.new.q("twitter").fetch          # Even shorter-cut
contains(query)

Alias for containing

does_not_contain(query)

Alias for not_containing

does_not_mention(screen_name)

Alias for not_mentioning

does_not_reference(screen_name)

Alias for not_mentioning

Calls block once for each element in self, passing that element as a parameter

@yieldparam [Hashie::Mash] result Tweet that matches specified query. @return [Array] Tweets that match specified query. @example

  Twitter::Search.new.containing('marry me').to('justinbieber').each do |result|
    puts "#{result.from_user}: #{result.text}"
  end
exclude(query)

Alias for not_containing

exclude_hashtag(tag)

Alias for excluding_hashtag

excludes(query)

Alias for not_containing

excludes_hashtag(tag)

Alias for excluding_hashtag

excluding(query)

Alias for not_containing

Exclude tweets containing a given hashtag

@param tag [String] A Twitter hashtag. @return [Twitter::Search] self @example Return an array of tweets containing the hashtag FollowFriday but not FF

  Twitter::Search.new.hashtag("FollowFriday").excluding_hashtag("FF").fetch
  Twitter::Search.new.hashtag("FollowFriday").excludes_hashtag("FF").fetch  # Shortcut for the above
  Twitter::Search.new.hashtag("FollowFriday").exclude_hashtag("FF").fetch   # Even shorter

Fetch the results of the query

@param force [Boolean] Ignore the cache and hit the API again. @return [Array] Tweets that match specified query. @example Return an array of tweets containing "twitter"

  search = Twitter::Search.new.containing("twitter").fetch

Fetch the next page of results of the query

@return [Array] Tweets that match specified query. @example Return the first two pages of results

  search = Twitter::Search.new.containing("twitter").fetch
  search.fetch_next_page

Only include tweets that contain URLs

@param filter [String] A type of search filter. Only ‘links’ is currently effective. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" and URLs

  Twitter::Search.new.containing("twitter").filter.fetch

Only include tweets from a given user, specified by screen_name

@param screen_name [String] A Twitter user name. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" from @sferik

  Twitter::Search.new.containing("twitter").from("sferik").fetch

Only include tweets from users in a given radius of a given location

@param lat [Float] A latitude. @param long [Float] A longitude. @param radius [String] A search radius, specified in either ‘mi’ (miles) or ‘km’ (kilometers). @return [Twitter::Search] self @example Return an array of tweets within a 1-mile radius of Twitter HQ

  Twitter::Search.new.containing("twitter").geocode(37.781157, -122.398720, "1mi").fetch

Only include tweets containing a given hashtag

@param tag [String] A Twitter hashtag. @return [Twitter::Search] self @example Return an array of tweets containing the hashtag FollowFriday

  Twitter::Search.new.hashtag("FollowFriday").fetch
lang(code)

Alias for language

Only include tweets in a given language, specified by an ISO 639-1 code

@param code [String] An ISO 639-1 code. @return [Twitter::Search] self @example Return an array of French-language tweets containing "twitter"

  Twitter::Search.new.containing("twitter").language("fr").fetch
  Twitter::Search.new.containing("twitter").lang("fr").fetch     # Shortcut for the above

@see en.wikipedia.org/wiki/ISO_639-1

Specify the locale of the query you are sending

@param code [String] An ISO 639-1 code (only ‘ja’ is currently effective). @return [Twitter::Search] self @example Return an array of tweets from Japan containing "twitter"

  Twitter::Search.new.containing("twitter").locale("ja").fetch

@see en.wikipedia.org/wiki/ISO_639-1

max(id)

Alias for max_id

Only include tweets with an ID less than or equal to the specified ID

@param id [Integer] A Twitter status ID. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" with an ID less than or equal to 123456789

  Twitter::Search.new.containing("twitter").max_id(123456789).fetch

Only include tweets mentioning a given user, specified by screen_name

@param screen_name [String] A Twitter user name. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" and mentioning @sferik

  Twitter::Search.new.containing("twitter").mentioning("sferik").fetch
mentions(screen_name)

Alias for mentioning

Only include tweets from users in a given radius of a given location

@deprecated {Twitter::Search#near} is deprecated and will be permanently removed in the next major version. Please use {Twitter::Search#geocode} instead. @param lat [Float] A latitude. @param long [Float] A longitude. @param radius [String] A search radius, specified in either ‘mi’ (miles) or ‘km’ (kilometers). @return [Twitter::Search] self @see dev.twitter.com/pages/using_search @example Return an array of tweets within a 1-mile radius of Twitter HQ

  Twitter::Search.new.containing("twitter").geocode(37.781157, -122.398720, "1mi").fetch

Only include tweets with a negative attitude

@return [Twitter::Search] self @example Return an array of tweets containing sad emoticons

  Twitter::Search.new.negative.fetch

Indicates if there are additional results to be fetched

@return [Boolean] @example

  search = Twitter::Search.new.containing("twitter").fetch
  search.next_page? #=> true

Only include original status updates (i.e., not retweets)

@return [Twitter::Search] self @example Return an array of tweets containing "twitter", excluding retweets

  Twitter::Search.new.containing("twitter").no_retweets.fetch

Negative search query

@param query [String] The negative search query. @return [Twitter::Search] self @example Return an array of tweets containing "beer" but not "root"

  Twitter::Search.new.containing("beer").not_containing("root").fetch
  Twitter::Search.new.containing("beer").does_not_contain("root").fetch # Same as above
  Twitter::Search.new.containing("beer").excluding("root").fetch        # Shortcut for the above
  Twitter::Search.new.contains("beer").excludes("root").fetch           # Even shorter
  Twitter::Search.new.q("beer").exclude("root").fetch                   # Shorter still

Exclude tweets from a given user, specified by screen_name

@param screen_name [String] A Twitter user name. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" from everyone except @sferik

  Twitter::Search.new.containing("twitter").not_from("sferik").fetch

Exclude tweets mentioning a given user, specified by screen_name

@param screen_name [String] A Twitter user name. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" but not mentioning @sferik

  Twitter::Search.new.containing("twitter").not_mentioning("sferik").fetch
not_referencing(screen_name)

Alias for not_mentioning

Exclude tweets to a given user, specified by screen_name

@param screen_name [String] A Twitter user name. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" to everyone except @sferik

  Twitter::Search.new.containing("twitter").not_to("sferik").fetch

Specify the page number to return, up to a maximum of roughly 1500 results

@param number [Integer] The page number (starting at 1) to return, up to a max of roughly 1500 results (based on {Twitter::Client::Search#per_page} * {Twitter::Client::Search#page}). @return [Twitter::Search] self @example Return the second page of tweets containing "twitter"

  Twitter::Search.new.containing("twitter").page(2).fetch

Specify the number of tweets to return per page

@param number [Integer] The number of tweets to return per page, up to a max of 100. @return [Twitter::Search] self @example Return an array of 100 tweets containing "twitter"

  Twitter::Search.new.containing("twitter").per_page(100).fetch

Search for a specific phrase instead of a group of words

@param phrase [String] The search phrase. @return [Twitter::Search] self @example Return an array of tweets containing the phrase "happy hour"

  Twitter::Search.new.phrase("happy hour").fetch

Only include tweets from users in a given place, specified by a place ID

@param place_id [String] A place ID. @return [Twitter::Search] self @example Return an array of tweets from San Francisco

  Twitter::Search.new.place("5a110d312052166f").fetch

Only include tweets with a positive attitude

@return [Twitter::Search] self @example Return an array of tweets containing happy emoticons

  Twitter::Search.new.positive.fetch
q(query)

Alias for containing

Only include tweets that are asking a question

@return [Twitter::Search] self @example Return an array of tweets containing question marks

  Twitter::Search.new.question.fetch
references(screen_name)

Alias for mentioning

referencing(screen_name)

Alias for mentioning

Specify what type of search results you want to receive

@param result_type [String] The type of results you want to receive (‘recent’, ‘popular’, or ‘mixed’). @return [Twitter::Search] self @example Return an array of recent tweets containing "twitter"

  Twitter::Search.new.containing("twitter").result_type("recent").fetch

Only include retweets

@return [Twitter::Search] self @example Return an array of retweets containing "twitter"

  Twitter::Search.new.containing("twitter").retweets.fetch
rpp(number=15)

Alias for per_page

since(date)

Alias for since_date

Only include tweets from after a given date

@param date [String] A date in the format YYYY-MM-DD. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" since October 1, 2010

  Twitter::Search.new.containing("twitter").since_date("2010-10-01").fetch

Only include tweets with an ID greater than the specified ID

@param id [Integer] A Twitter status ID. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" with an ID greater than 123456789

  Twitter::Search.new.containing("twitter").since_id(123456789).fetch

Only include tweets from a given source

@param source [String] A Twitter source. @return [Twitter::Search] self @example Return an array of tweets containing "twitter", posted from Hibari

  Twitter::Search.new.containing("twitter").source("Hibari").fetch

Only include tweets to a given user, specified by screen_name

@param screen_name [String] A Twitter user name. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" to @sferik

  Twitter::Search.new.containing("twitter").to("sferik").fetch
until(date)

Alias for until_date

Only include tweets from before a given date

@param date [String] A date in the format YYYY-MM-DD. @return [Twitter::Search] self @example Return an array of tweets containing "twitter" up until October 1, 2010

  Twitter::Search.new.containing("twitter").since_date("2010-10-01").fetch

[Validate]