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
search_endpoint | -> | api_endpoint |
query | [R] | @private |
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
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 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
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
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
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
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
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 with a positive attitude
@return [Twitter::Search] self @example Return an array of tweets containing happy emoticons
Twitter::Search.new.positive.fetch
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
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
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
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