Permalink
Browse files

Add documentation for search and trends

  • Loading branch information...
sferik committed Nov 1, 2010
1 parent c3a67fd commit b5d900e6dafa7b11b603fce139dbf1e9eb2b27c9
Showing with 177 additions and 29 deletions.
  1. +2 −1 .yardopts
  2. +80 −2 lib/twitter/client/geo.rb
  3. +30 −0 lib/twitter/client/local_trends.rb
  4. +39 −0 lib/twitter/client/trends.rb
  5. +26 −26 lib/twitter/search.rb
View
@@ -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
@@ -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
@@ -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}
@@ -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
Oops, something went wrong.

0 comments on commit b5d900e

Please sign in to comment.