Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add documentation for search and trends

  • Loading branch information...
commit b5d900e6dafa7b11b603fce139dbf1e9eb2b27c9 1 parent c3a67fd
@sferik sferik authored
View
3  .yardopts
@@ -1,6 +1,7 @@
--protected
+--tag formats:"Supported formats"
--tag authenticated:"Requires Authentication"
---tag rate_limited:"Rate limited"
+--tag rate_limited:"Rate Limited"
-
LICENSE.md
HISTORY.md
View
82 lib/twitter/client/geo.rb
@@ -1,23 +1,101 @@
module Twitter
class Client
+ # @see http://dev.twitter.com/pages/geo_dev_guidelines Twitter Geo Developer Guidelines
module Geo
+ # Search for places that can be attached to a {Twitter::Client::Tweets#update}.
+ # Given a latitude and a longitude pair, an IP address, or a name, this request
+ # will return a list of all the valid places that can be used as the place_id
+ # when updating a status.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+ # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+ # @option options [String] :query Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name.
+ # @option options [String] :ip An IP address. Used when attempting to fix geolocation based off of the user's IP address.
+ # @option options [String] :granularity This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. If no granularity is provided for the request neighborhood is assumed.
+ # @option options [String] :accuracy A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).
+ # @option options [Integer] :max_results A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here.
+ # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.
+ # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/geo/search
def places_nearby(options={})
get('geo/search', options)['result']['places']
end
alias :geo_search :places_nearby
+ # Locates places near the given coordinates which are similar in name.
+ #
+ # Conceptually you would use this method to get a list of known places to choose from first.
+ # Then, if the desired place doesn't exist, make a request to {Twitter::Client::Geo#place}
+ # to create a new one.
+ #
+ # The token contained in the response is the token needed to be able to create a new place.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+ # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+ # @option options [String] :name The name a place is known as.
+ # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.
+ # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/geo/similar_places
def places_similar(options={})
get('geo/similar_places', options)['result']['places']
end
+ # Given a latitude and a longitude, searches for up to 20 places that can be used as a place_id when updating a status.
+ #
+ # This request is an informative call and will deliver generalized results about geography.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+ # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+ # @option options [String] :accuracy A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).
+ # @option options [String] :granularity This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. If no granularity is provided for the request neighborhood is assumed.
+ # @option options [Integer] :max_results A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/geo/reverse_geocode
def reverse_geocode(options={})
get('geo/reverse_geocode', options)['result']['places']
end
- def place(id, options={})
- get("geo/id/#{id}", options)
+ # Returns all the information about a known place
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param place_id [String] A place in the world. These IDs can be retrieved from {Twitter::Client::Geo#reverse_geocode}.
+ # @param options [Hash] A customizable set of options.
+ # @return [Hashie::Mash]
+ # @see http://dev.twitter.com/doc/get/geo/id/:place_id
+ def place(place_id, options={})
+ get("geo/id/#{place_id}", options)
end
+ # Creates a new place at the given latitude and longitude
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @option options [String] :name The name a place is known as.
+ # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.
+ # @option options [String] :token The token found in the response from {Twitter::Client::Geo#places_similar}.
+ # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
+ # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
+ # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
+ # @return [Hashie::Mash]
+ # @see http://dev.twitter.com/doc/post/geo/place
def place_create(options={})
post('geo/place', options)
end
View
30 lib/twitter/client/local_trends.rb
@@ -1,11 +1,41 @@
module Twitter
class Client
module LocalTrends
+ # Returns the locations that Twitter has trending topic information for.
+ #
+ # The response is an array of "locations" that encode the location's WOEID and some other human-readable information
+ # such as a canonical name and country the location belongs in.
+ #
+ # A WOEID is a {http://developer.yahoo.com/geo/geoplanet Yahoo! Where On Earth ID}.
+ #
+ # @formats :json, :xml
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @option options [Float] :lat If provided with a :long option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for latitude is -90.0 to +90.0 (North is positive) inclusive.
+ # @option options [Float] :long If provided with a :lat option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/trends/available
def trend_locations(options={})
response = get('trends/available', options)
format.to_s.downcase == 'xml' ? response['locations'] : response
end
+ # Returns the top 10 trending topics for a specific WOEID, if trending information is available for it.
+ #
+ # The response is an array of "trend" objects that encode the name of the trending topic, the query option that can be
+ # used to search for the topic on {http://search.twitter.com Twitter Search}, and the Twitter Search URL.
+ #
+ # This information is cached for 5 minutes. Requesting more frequently than that will not return any more data, and will
+ # count against your rate limit usage.
+ #
+ # @formats :json, :xml
+ # @authenticated false
+ # @rate_limited true
+ # @param woeid [Integer] The {http://developer.yahoo.com/geo/geoplanet Yahoo! Where On Earth ID} of the location to return trending information for. Global information is available by using 1 as the WOEID.
+ # @param options [Hash] A customizable set of options.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/trends/:woeid
def local_trends(woeid=1, options={})
response = get("trends/#{woeid}", options)
format.to_s.downcase == 'xml' ? response['matching_trends'].first.trend : response.first.trends.map{|trend| trend.name}
View
39 lib/twitter/client/trends.rb
@@ -1,18 +1,57 @@
module Twitter
class Client
module Trends
+ # Returns the top ten topics that are currently trending on Twitter. The response includes the time of the request,
+ # the name of each trend, and the url to the {http://search.twitter.com Twitter Search} results page for that topic.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/trends
def trends(options={})
get('trends', options)['trends']
end
+ # Returns the current top 10 trending topics on Twitter. The response includes the time of the request,
+ # the name of each trending topic, and query used on {http://search.twitter.com Twitter Search} results page for that topic.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param options [Hash] A customizable set of options.
+ # @option options [String] :exclude Setting this equal to 'hashtags' will remove all hashtags from the trends list.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/trends/current
def trends_current(options={})
get('trends/current', options)['trends']
end
+ # Returns the top 20 trending topics for each hour in a given day.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param date [String] The start date for the report. The date should be formatted YYYY-MM-DD. A 404 error will be thrown if the date is older than the available search index (7-10 days). Dates in the future will be forced to the current date.
+ # @param options [Hash] A customizable set of options.
+ # @option options [String] :exclude Setting this equal to 'hashtags' will remove all hashtags from the trends list.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/trends/daily
def trends_daily(date=Time.now, options={})
get('trends/daily', options.merge(:date => date.strftime('%Y-%m-%d')))['trends']
end
+ # Returns the top 30 trending topics for each day in a given week.
+ #
+ # @formats :json
+ # @authenticated false
+ # @rate_limited true
+ # @param date [String] The start date for the report. The date should be formatted YYYY-MM-DD. A 404 error will be thrown if the date is older than the available search index (7-10 days). Dates in the future will be forced to the current date.
+ # @param options [Hash] A customizable set of options.
+ # @option options [String] :exclude Setting this equal to 'hashtags' will remove all hashtags from the trends list.
+ # @return [Array]
+ # @see http://dev.twitter.com/doc/get/trends/weekly
def trends_weekly(date=Time.now, options={})
get('trends/weekly', options.merge(:date => date.strftime('%Y-%m-%d')))['trends']
end
View
52 lib/twitter/search.rb
@@ -47,7 +47,7 @@ def clear
# Search query
#
- # @param query [String] The search query
+ # @param query [String] The search query.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").fetch # Returns an array of tweets containing "twitter"
@@ -62,7 +62,7 @@ def containing(query)
# Negative search query
#
- # @param query [String] The negative search query
+ # @param query [String] The negative search query.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("beer").not_containing("root").fetch # Returns an array of tweets containing "beer" but not "root"
@@ -81,7 +81,7 @@ def not_containing(query)
# Search for a specific phrase instead of a group of words
#
- # @param phrase [String] The search phrase
+ # @param phrase [String] The search phrase.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.phrase("happy hour").fetch # Returns an array of tweets containing the phrase "happy hour"
@@ -103,7 +103,7 @@ def filter(filter='links')
# Only include tweets from after a given date, specified in the formatted YYYY-MM-DD
#
- # @param date [String] A date in the format YYYY-MM-DD
+ # @param date [String] A date in the format YYYY-MM-DD.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").since_date("2010-10-01").fetch # Return an array of tweets containing "twitter" since October 1, 2010
@@ -115,7 +115,7 @@ def since_date(date)
# Only include tweets from before a given date, specified in the formatted YYYY-MM-DD
#
- # @param date [String] A date in the format YYYY-MM-DD
+ # @param date [String] A date in the format YYYY-MM-DD.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").since_date("2010-10-01").fetch # Return an array of tweets containing "twitter" up until October 1, 2010
@@ -159,7 +159,7 @@ def question
# Only include tweets in a given language, specified by an ISO 639-1 code
#
- # @param code [String] An ISO 639-1 code
+ # @param code [String] An ISO 639-1 code.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").language("fr").fetch # Returns an array of French-language tweets containing "twitter"
@@ -175,7 +175,7 @@ def language(code)
# This is intended for language-specific clients and
# the default should work in the majority of cases.
#
- # @param code [String] An ISO 639-1 code (only 'ja' is currently effective)
+ # @param code [String] An ISO 639-1 code (only 'ja' is currently effective).
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").locale("ja").fetch # Returns an array of tweets from Japan containing "twitter"
@@ -187,9 +187,9 @@ def locale(code)
# Only include tweets from users in a given radius of a given location, specified by latitude and longitude
#
- # @param lat [Float] A latitude
- # @param long [Float] A longitude
- # @param radius [String] A search radius, specified in either 'mi' or 'km'
+ # @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
# Twitter::Search.new.containing("twitter").geocode(37.781157, -122.398720, "1mi").fetch # Returns an array of tweets within a 1-mile radius of Twitter HQ
@@ -200,7 +200,7 @@ def geocode(lat, long, radius)
# Only include tweets from users in a given place, specified by a place ID
#
- # @param place_id [String] A place ID
+ # @param place_id [String] A place ID.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.place("5a110d312052166f").fetch # Returns an array of tweets from San Francisco
@@ -211,7 +211,7 @@ def place(place_id)
# Only include tweets from users near a given location
#
- # @param location [String] A place ID
+ # @param location [String] A location name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.near("San Francisco").fetch # Returns an array of tweets near San Francisco
@@ -224,7 +224,7 @@ def near(location)
# Only include tweets from a given user, specified by screen_name
#
- # @param screen_name [String] A Twitter user name
+ # @param screen_name [String] A Twitter user name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").from("sferik").fetch # Returns an array of tweets containing "twitter" from @sferik
@@ -235,7 +235,7 @@ def from(screen_name)
# Exclude tweets from a given user, specified by screen_name
#
- # @param screen_name [String] A Twitter user name
+ # @param screen_name [String] A Twitter user name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").not_from("sferik").fetch # Returns an array of tweets containing "twitter" from everyone except @sferik
@@ -246,7 +246,7 @@ def not_from(screen_name)
# Only include tweets to a given user, specified by screen_name
#
- # @param screen_name [String] A Twitter user name
+ # @param screen_name [String] A Twitter user name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").to("sferik").fetch # Returns an array of tweets containing "twitter" to @sferik
@@ -257,7 +257,7 @@ def to(screen_name)
# Exclude tweets to a given user, specified by screen_name
#
- # @param screen_name [String] A Twitter user name
+ # @param screen_name [String] A Twitter user name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").not_to("sferik").fetch # Returns an array of tweets containing "twitter" to everyone except @sferik
@@ -268,7 +268,7 @@ def not_to(screen_name)
# Only include tweets mentioning a given user, specified by screen_name
#
- # @param screen_name [String] A Twitter user name
+ # @param screen_name [String] A Twitter user name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").mentioning("sferik").fetch # Returns an array of tweets containing "twitter" and mentioning @sferik
@@ -282,7 +282,7 @@ def mentioning(screen_name)
# Exclude tweets mentioning a given user, specified by screen_name
#
- # @param screen_name [String] A Twitter user name
+ # @param screen_name [String] A Twitter user name.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").not_mentioning("sferik").fetch # Returns an array of tweets containing "twitter" but not mentioning @sferik
@@ -317,7 +317,7 @@ def no_retweets
# Only include tweets containing a given hashtag
#
- # @param tag [String] A Twitter hashtag
+ # @param tag [String] A Twitter hashtag.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.hashtag("FollowFriday").fetch # Returns an array of tweets containing the hashtag #FollowFriday
@@ -328,7 +328,7 @@ def hashtag(tag)
# Exclude tweets containing a given hashtag
#
- # @param tag [String] A Twitter hashtag
+ # @param tag [String] A Twitter hashtag.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.hashtag("FollowFriday").excluding_hashtag("FF").fetch # Returns an array of tweets containing the hashtag #FollowFriday but not #FF
@@ -343,7 +343,7 @@ def excluding_hashtag(tag)
# Only include tweets with an ID greater than (that is, more recent than) the specified ID.
#
- # @param id [Integer] A Twitter status ID
+ # @param id [Integer] A Twitter status ID.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").since_id(123456789).fetch # Returns an array of tweets containing "twitter" with an ID greater than 123456789
@@ -354,7 +354,7 @@ def since_id(id)
# Only include tweets with an ID less than or equal to the specified ID
#
- # @param id [Integer] A Twitter status ID
+ # @param id [Integer] A Twitter status ID.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").max_id(123456789).fetch # Returns an array of tweets containing "twitter" with an ID less than or equal to 123456789
@@ -367,7 +367,7 @@ def max_id(id)
# 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')
+ # @param result_type [String] The type of results you want to receive ('recent', 'popular', or 'mixed').
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").result_type("recent").fetch # Returns an array of recent tweets containing "twitter"
@@ -378,7 +378,7 @@ def result_type(result_type="mixed")
# Only include tweets from a given source
#
- # @param source [String] A Twitter source
+ # @param source [String] A Twitter source.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").source("Hibari").fetch # Returns an array of tweets containing "twitter", posted from Hibari
@@ -391,7 +391,7 @@ def source(source)
# Specify the number of tweets to return per page
#
- # @param number [Integer] The number of tweets to return per page, maximum 100
+ # @param number [Integer] The number of tweets to return per page, up to a max of 100.
# @return [Twitter::Search] self
# @example
# Twitter::Search.new.containing("twitter").per_page(100).fetch # Returns an array of 100 tweets containing "twitter"
@@ -403,7 +403,7 @@ def per_page(number=15)
# Specify the page number to return, up to a maximum of roughly 1500 results
#
- # @param number [Integer] A page number, starting at 1
+ # @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
# Twitter::Search.new.containing("twitter").page(2).fetch # Returns the second page of tweets containing "twitter"
Please sign in to comment.
Something went wrong with that request. Please try again.