google_places 0.1.1 → 0.9

data/.gitignore

@@ -8,3 +8,4 @@ spec/api_key.rb
 .yardoc/
 doc/
 spec/vcr_cassettes/*
+.idea

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    google_places (0.1.0)
+    google_places (0.1.1)
       httparty
 
 GEM
@@ -9,20 +9,20 @@ GEM
   specs:
     diff-lcs (1.1.3)
     fakeweb (1.3.0)
-    httparty (0.8.3)
+    httparty (0.9.0)
       multi_json (~> 1.0)
       multi_xml
     multi_json (1.3.6)
     multi_xml (0.5.1)
-    rspec (2.10.0)
-      rspec-core (~> 2.10.0)
-      rspec-expectations (~> 2.10.0)
-      rspec-mocks (~> 2.10.0)
-    rspec-core (2.10.1)
-    rspec-expectations (2.10.0)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
       diff-lcs (~> 1.1.3)
-    rspec-mocks (2.10.1)
-    vcr (2.2.2)
+    rspec-mocks (2.11.3)
+    vcr (2.2.5)
 
 PLATFORMS
   ruby

data/Rakefile

@@ -2,6 +2,8 @@ require 'bundler'
 require 'rspec/core/rake_task'
 
 Bundler::GemHelper.install_tasks
-RSpec::Core::RakeTask.new('spec')
+RSpec::Core::RakeTask.new('spec') do |task|
+  task.rspec_opts = "--color"
+end
 
 task :default => :spec

data/google_places.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "google_places"
-  s.version     = '0.1.1'
+  s.version     = '0.9'
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Marcel de Graaf"]
   s.email       = ["mail@marceldegraaf.net"]

data/lib/google_places/client.rb

@@ -1,23 +1,165 @@
 module GooglePlaces
+  # This class acts as a proxy to the working classes when requesting data from the API.
   class Client
+    # @return [String] the provided api key
     attr_reader :api_key
+    # @return [Hash] the provided options hash
     attr_reader :options
+    attr_reader :sensor
 
-    def initialize(api_key, options = {})
+    # Creates a new Client instance which proxies the requests to the certain classes
+    #
+    # @param [String] api_key The api key to use for the requests
+    # @param [Hash] options An options hash for requests. Is used as the query parameters on server requests
+    # @option options [String,Integer] lat
+    #   the latitude for the search
+    # @option options [String,Integer] lng
+    #   the longitude for the search
+    # @option options [Integer] :radius
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if <b>:rankby</b> is specified
+    # @option options [Boolean] :sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :name
+    #   A term to be matched against the names of Places.
+    #   Results will be restricted to those containing the passed name value.
+    # @option options [String] :keyword
+    #   A term to be matched against all content that Google has indexed for this Spot,
+    #   including but not limited to name, type, and address,
+    #   as well as customer reviews and other third-party content.
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status]
+    # @option options [Integer] :retry_options[:max] the maximum retries
+    # @option options [Integer] :retry_options[:delay] the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
+    def initialize(api_key, sensor = false, options = {})
       @api_key = api_key
+      @sensor = sensor
       @options = options
     end
 
+    # Search for Spots at the provided location
+    #
+    # @return [Array<Spot>]
+    # @param [String,Integer] lat the latitude for the search
+    # @param [String,Integer] lng the longitude for the search
+    # @param [Hash] options
+    # @option options [Integer] :radius (1000)
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if :rankby => 'distance' (described below) is specified.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :rankby
+    #   Specifies the order in which results are listed. Possible values are:
+    #   - prominence (default). This option sorts results based on their importance.
+    #     Ranking will favor prominent places within the specified area.
+    #     Prominence can be affected by a Place's ranking in Google's index,
+    #     the number of check-ins from your application, global popularity, and other factors.
+    #   - distance. This option sorts results in ascending order by their distance from the specified location.
+    #     Ranking results by distance will set a fixed search radius of 50km.
+    #     One or more of keyword, name, or types is required.                                                                                                                                                                                                                                                                                       distance. This option sorts results in ascending order by their distance from the specified location. Ranking results by distance will set a fixed search radius of 50km. One or more of keyword, name, or types is required.
+    # @option options [Boolean] :sensor (false)
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS)
+    #   to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :name
+    #   A term to be matched against the names of Places.
+    #   Results will be restricted to those containing the passed name value.
+    # @option options [String] :keyword
+    #   A term to be matched against all content that Google has indexed for this Spot,
+    #   including but not limited to name, type, and address,
+    #   as well as customer reviews and other third-party content.
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
     def spots(lat, lng, options = {})
-      Spot.list(lat, lng, @api_key, @options.merge(options))
+      Spot.list(lat, lng, @api_key, @sensor, @options.merge(options))
     end
 
+    # Search for a Spot with a reference key
+    #
+    # @return [Spot]
+    # @param [String] reference the reference of the spot
+    # @param [Hash] options
+    # @option options [Boolean] :sensor (false)
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
     def spot(reference, options = {})
-      Spot.find(reference, @api_key, @options.merge(options))
+      Spot.find(reference, @api_key, @sensor, @options.merge(options))
     end
 
+    # Search for Spots with a query
+    #
+    # @return [Array<Spot>]
+    # @param [String] query the query to search for
+    # @param [Hash] options
+    # @option options [String,Integer] lat the latitude for the search
+    # @option options [String,Integer] lng the longitude for the search
+    # @option options [Integer] :radius (1000)
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if :rankby => 'distance' (described below) is specified.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :rankby
+    #   Specifies the order in which results are listed. Possible values are:
+    #   - prominence (default). This option sorts results based on their importance.
+    #     Ranking will favor prominent places within the specified area.
+    #     Prominence can be affected by a Place's ranking in Google's index,
+    #     the number of check-ins from your application, global popularity, and other factors.
+    #   - distance. This option sorts results in ascending order by their distance from the specified location.
+    #     Ranking results by distance will set a fixed search radius of 50km.
+    #     One or more of keyword, name, or types is required.                                                                                                                                                                                                                                                                                       distance. This option sorts results in ascending order by their distance from the specified location. Ranking results by distance will set a fixed search radius of 50km. One or more of keyword, name, or types is required.
+    # @option options [Boolean] :sensor (false)
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
     def spots_by_query(query, options = {})
-      Spot.list_by_query(query, @api_key, @options.merge(options))
+      Spot.list_by_query(query, @api_key, @sensor, @options.merge(options))
     end
   end
 end

data/lib/google_places/error.rb

@@ -2,9 +2,21 @@ module GooglePlaces
   class OverQueryLimitError < HTTParty::ResponseError
   end
 
+  # Thrown when a request was denied by the server
+  #
+  # This can be the case when:
+  # - querying the SPOT_LIST_URL <b>without</b> the following parameters:
+  # - - key
+  # - - sensor
   class RequestDeniedError < HTTParty::ResponseError
   end
 
+  # Thrown when a request was rejected as invalid by the server
+  #
+  # This can be the case when:
+  # - querying the SPOT_LIST_URL <b>without</b> the following parameters:
+  # - - location
+  # - - radius
   class InvalidRequestError < HTTParty::ResponseError
   end
 

data/lib/google_places/location.rb

@@ -1,8 +1,8 @@
 module GooglePlaces
   class Location
     def initialize(lat, lng)
-      @lat = lat
-      @lng = lng
+      @lat = ("%.8f"%lat)
+      @lng = ("%.8f"%lng)
     end
 
     def format

data/lib/google_places/request.rb

@@ -1,29 +1,167 @@
 module GooglePlaces
+  # This class performs the queries on the API
   class Request
+    # @return [HTTParty::Response] the retrieved response from the API
     attr_accessor :response
+    attr_reader :options
 
     include ::HTTParty
     format :json
 
-    SPOTS_LIST_URL = 'https://maps.googleapis.com/maps/api/place/search/json'
-    SPOT_URL = 'https://maps.googleapis.com/maps/api/place/details/json'
-    SPOTS_LIST_QUERY_URL = 'https://maps.googleapis.com/maps/api/place/textsearch/json'
-
+    NEARBY_SEARCH_URL = 'https://maps.googleapis.com/maps/api/place/nearbysearch/json'
+    DETAILS_URL       = 'https://maps.googleapis.com/maps/api/place/details/json'
+    TEXT_SEARCH_URL   = 'https://maps.googleapis.com/maps/api/place/textsearch/json'
+
+    # Search for Spots at the provided location
+    #
+    # @return [Array<Spot>]
+    # @param [Hash] options
+    # @option options [String] :key
+    #   the provided api key.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [Integer] :radius
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if <b>:rankby</b> is specified
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [Boolean] :sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [(Integer,Integer),String] :location
+    #   The latitude/longitude around which to retrieve Spot information. This must be specified as latitude,longitude
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :name
+    #   A term to be matched against the names of Places.
+    #   Results will be restricted to those containing the passed name value.
+    # @option options [String] :keyword
+    #   A term to be matched against all content that Google has indexed for this Spot,
+    #   including but not limited to name, type, and address,
+    #   as well as customer reviews and other third-party content.
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
     def self.spots(options = {})
-      request = new(SPOTS_LIST_URL, options)
+      request = new(NEARBY_SEARCH_URL, options)
       request.parsed_response
     end
 
+    # Search for a Spot with a reference key
+    #
+    # @return [Spot]
+    # @param [Hash] options
+    # @option options [String] :key
+    #   the provided api key.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :reference
+    #   The reference of a already retrieved Spot
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [Boolean] :sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
     def self.spot(options = {})
-      request = new(SPOT_URL, options)
+      request = new(DETAILS_URL, options)
       request.parsed_response
     end
 
+    # Search for Spots with a query
+    #
+    # @return [Array<Spot>]
+    # @param [String] query the query to search for
+    # @param [String] api_key the provided api key
+    # @param [Hash] options
+    # @option options [String,Integer] :lat
+    #   the latitude for the search
+    # @option options [String,Integer] :lng
+    #   the longitude for the search
+    # @option options [Integer] :radius
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if <b>:rankby</b> is specified
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [Boolean] :sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
     def self.spots_by_query(options = {})
-      request = new(SPOTS_LIST_QUERY_URL, options)
+      request = new(TEXT_SEARCH_URL, options)
       request.parsed_response
     end
 
+    # Create a new Request for a given uri and the provided params
+    #
+    # @return [Request]
+    # @param [String] url The uri to make the query on
+    # @param [Hash] options A Hash providing options for the request
+    # @option options [String] :key
+    #   the provided api key.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [Integer] :radius
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if <b>:rankby</b> is specified
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [Boolean] :sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [(Integer,Integer),String] :location
+    #   The latitude/longitude around which to retrieve Spot information. This must be specified as latitude,longitude
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :name
+    #   A term to be matched against the names of Places.
+    #   Results will be restricted to those containing the passed name value.
+    # @option options [String] :keyword
+    #   A term to be matched against all content that Google has indexed for this Spot,
+    #   including but not limited to name, type, and address,
+    #   as well as customer reviews and other third-party content.
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
     def initialize(url, options)
       retry_options = options.delete(:retry_options) || {}
 
@@ -62,6 +200,16 @@ module GooglePlaces
       end
     end
 
+    def execute
+      @response = self.class.get(url, :query => options)
+    end
+
+    # Parse errors from the server respons, if any
+    # @raise [OverQueryLimitError] when server response object includes status 'OVER_QUERY_LIMIT'
+    # @raise [RequestDeniedError] when server response object includes 'REQUEST_DENIED'
+    # @raise [InvalidRequestError] when server response object includes 'INVALID_REQUEST'
+    # @raise [UnknownError] when server response object includes 'UNKNOWN_ERROR'
+    # @return [String] the response from the server as JSON
     def parsed_response
       case @response.parsed_response['status']
       when 'OK', 'ZERO_RESULTS'

data/lib/google_places/spot.rb

@@ -4,14 +4,60 @@ module GooglePlaces
   class Spot
     attr_accessor :lat, :lng, :name, :icon, :reference, :vicinity, :types, :id, :formatted_phone_number, :international_phone_number, :formatted_address, :address_components, :street_number, :street, :city, :region, :postal_code, :country, :rating, :url, :cid, :website, :reviews
 
-    def self.list(lat, lng, api_key, options = {})
-      radius = options.delete(:radius) || 200
-      sensor = options.delete(:sensor) || false
+    # Search for Spots at the provided location
+    #
+    # @return [Array<Spot>]
+    # @param [String,Integer] lat the latitude for the search
+    # @param [String,Integer] lng the longitude for the search
+    # @param [String] api_key the provided api key
+    # @param [Boolean] sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS) to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @param [Hash] options
+    # @option options [Integer] :radius (1000)
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if :rankby => 'distance' (described below) is specified.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :rankby
+    #   Specifies the order in which results are listed. Possible values are:
+    #   - prominence (default). This option sorts results based on their importance.
+    #     Ranking will favor prominent places within the specified area.
+    #     Prominence can be affected by a Place's ranking in Google's index,
+    #     the number of check-ins from your application, global popularity, and other factors.
+    #   - distance. This option sorts results in ascending order by their distance from the specified location.
+    #     Ranking results by distance will set a fixed search radius of 50km.
+    #     One or more of keyword, name, or types is required.                                                                                                                                                                                                                                                                                       distance. This option sorts results in ascending order by their distance from the specified location. Ranking results by distance will set a fixed search radius of 50km. One or more of keyword, name, or types is required.
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :name
+    #   A term to be matched against the names of Places.
+    #   Results will be restricted to those containing the passed name value.
+    # @option options [String] :keyword
+    #   A term to be matched against all content that Google has indexed for this Spot,
+    #   including but not limited to name, type, and address,
+    #   as well as customer reviews and other third-party content.
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
+    def self.list(lat, lng, api_key, sensor, options = {})
+      location = Location.new(lat, lng)
+      rankby = options.delete(:rankby)
+      radius = options.delete(:radius) || 1000 if rankby.nil?
       types  = options.delete(:types)
       name  = options.delete(:name)
       keyword = options.delete(:keyword)
       language  = options.delete(:language)
-      location = Location.new(lat, lng)
       exclude = options.delete(:exclude) || []
       retry_options = options.delete(:retry_options) || {}
 
@@ -21,6 +67,7 @@ module GooglePlaces
         :location => location.format,
         :radius => radius,
         :sensor => sensor,
+        :rankby => rankby,
         :key => api_key,
         :name => name,
         :language => language,
@@ -34,14 +81,32 @@ module GooglePlaces
         options.merge!(:types => types)
       end
 
-      response = Request.spots(options)
-      response['results'].map do |result|
-        self.new(result) if (result['types'] & exclude) == []
-      end.compact
+      results = []
+      self.multi_pages_request(:spots, options) do |result|
+        results << self.new(result) if (result['types'] & exclude) == []
+      end
+      results
     end
 
-    def self.find(reference, api_key, options = {})
-      sensor = options.delete(:sensor) || false
+    # Search for a Spot with a reference key
+    #
+    # @return [Spot]
+    # @param [String] reference the reference of the spot
+    # @param [String] api_key the provided api key
+    # @param [Boolean] sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS)
+    #   to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @param [Hash] options
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    def self.find(reference, api_key, sensor, options = {})
       language  = options.delete(:language)
       retry_options = options.delete(:retry_options) || {}
 
@@ -56,7 +121,50 @@ module GooglePlaces
       self.new(response['result'])
     end
 
-    def self.list_by_query(query, api_key, options)
+    # Search for Spots with a query
+    #
+    # @return [Array<Spot>]
+    # @param [String] query the query to search for
+    # @param [String] api_key the provided api key
+    # @param [Boolean] sensor
+    #   Indicates whether or not the Place request came from a device using a location sensor (e.g. a GPS)
+    #   to determine the location sent in this request.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @param [Hash] options
+    # @option options [String,Integer] :lat
+    #   the latitude for the search
+    # @option options [String,Integer] :lng
+    #   the longitude for the search
+    # @option options [Integer] :radius (1000)
+    #   Defines the distance (in meters) within which to return Place results.
+    #   The maximum allowed radius is 50,000 meters.
+    #   Note that radius must not be included if :rankby => 'distance' (described below) is specified.
+    #   <b>Note that this is a mandatory parameter</b>
+    # @option options [String] :rankby
+    #   Specifies the order in which results are listed. Possible values are:
+    #   - prominence (default). This option sorts results based on their importance.
+    #     Ranking will favor prominent places within the specified area.
+    #     Prominence can be affected by a Place's ranking in Google's index,
+    #     the number of check-ins from your application, global popularity, and other factors.
+    #   - distance. This option sorts results in ascending order by their distance from the specified location.
+    #     Ranking results by distance will set a fixed search radius of 50km.
+    #     One or more of keyword, name, or types is required.
+    # @option options [String,Array] :types
+    #   Restricts the results to Spots matching at least one of the specified types
+    # @option options [String] :language
+    #   The language code, indicating in which language the results should be returned, if possible.
+    # @option options [String,Array<String>] :exclude ([])
+    #   A String or an Array of <b>types</b> to exclude from results
+    #
+    # @option options [Hash] :retry_options ({})
+    #   A Hash containing parameters for search retries
+    # @option options [Object] :retry_options[:status] ([])
+    # @option options [Integer] :retry_options[:max] (0) the maximum retries
+    # @option options [Integer] :retry_options[:delay] (5) the delay between each retry in seconds
+    #
+    # @see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1 List of supported languages
+    # @see https://developers.google.com/maps/documentation/places/supported_types List of supported types
+    def self.list_by_query(query, api_key, sensor, options = {})
       if options.has_key?(:lat) && options.has_key?(:lng)
         with_location = true
       else
@@ -70,9 +178,10 @@ module GooglePlaces
       end
 
       query = query
-      sensor = options.delete(:sensor) || false
+      sensor = sensor
       location = Location.new(options.delete(:lat), options.delete(:lng)) if with_location
       radius = options.delete(:radius) if with_radius
+      rankby = options.delete(:rankby)
       language = options.delete(:language)
       types = options.delete(:types)
       exclude = options.delete(:exclude) || []
@@ -84,6 +193,7 @@ module GooglePlaces
         :query => query,
         :sensor => sensor,
         :key => api_key,
+        :rankby => rankby,
         :language => language,
         :retry_options => retry_options
       }
@@ -97,12 +207,38 @@ module GooglePlaces
         options.merge!(:types => types)
       end
 
-      response = Request.spots_by_query(options)
-      response['results'].map do |result|
-        self.new(result) if (result['types'] & exclude) == []
-      end.compact
+      results = []
+      self.multi_pages_request(:spots_by_query, options) do |result|
+        results << self.new(result) if (result['types'] & exclude) == []
+      end
+      results
+    end
+
+    def self.multi_pages_request(method, options)
+      begin
+
+        response = Request.send(method, options)
+        response['results'].each do |result|
+          yield(result)
+        end
+
+        # request the next page if presence of a "next_page" token
+        next_page = false
+        unless response["next_page_token"].nil?
+          options = {
+            pagetoken: response["next_page_token"],
+            key: options[:key],
+            sensor: options[:sensor]
+          }
+          sleep(2) # the time the token is issued, else InvalidRequestError
+          next_page = true
+        end
+
+      end while (next_page)
     end
 
+    # @param [JSON] json_result_object a JSON object to create a Spot from
+    # @return [Spot] a newly created spot
     def initialize(json_result_object)
       @reference                  = json_result_object['reference']
       @vicinity                   = json_result_object['vicinity']

data/spec/google_places/client_spec.rb

@@ -14,7 +14,7 @@ describe GooglePlaces::Client do
   it 'should request spots' do
     lat, lng = '-33.8670522', '151.1957362'
     @client = GooglePlaces::Client.new(api_key)
-    GooglePlaces::Spot.should_receive(:list).with(lat, lng, api_key, {})
+    GooglePlaces::Spot.should_receive(:list).with(lat, lng, api_key, false, {})
 
     @client.spots(lat, lng)
   end
@@ -22,7 +22,7 @@ describe GooglePlaces::Client do
   it 'should request a single spot' do
     reference = "CoQBeAAAAO-prCRp9Atcj_rvavsLyv-DnxbGkw8QyRZb6Srm6QHOcww6lqFhIs2c7Ie6fMg3PZ4PhicfJL7ZWlaHaLDTqmRisoTQQUn61WTcSXAAiCOzcm0JDBnafqrskSpFtNUgzGAOx29WGnWSP44jmjtioIsJN9ik8yjK7UxP4buAmMPVEhBXPiCfHXk1CQ6XRuQhpztsGhQU4U6-tWjTHcLSVzjbNxoiuihbaA"
     @client = GooglePlaces::Client.new(api_key)
-    GooglePlaces::Spot.should_receive(:find).with(reference, api_key, {})
+    GooglePlaces::Spot.should_receive(:find).with(reference, api_key, false, {})
 
     @client.spot(reference)
   end
@@ -30,7 +30,7 @@ describe GooglePlaces::Client do
   it 'should request spots by query' do
     query = "Statue of liberty, New York"
     @client = GooglePlaces::Client.new(api_key)
-    GooglePlaces::Spot.should_receive(:list_by_query).with(query, api_key, {})
+    GooglePlaces::Spot.should_receive(:list_by_query).with(query, api_key, false, {})
 
     @client.spots_by_query(query)
   end

data/spec/google_places/location_spec.rb

@@ -3,7 +3,7 @@ require 'spec_helper'
 describe GooglePlaces::Location do
 
   it 'should return a location based on a lat and lng' do
-    GooglePlaces::Location.new('123', '456').format.should == '123,456'
+    GooglePlaces::Location.new('123', '456').format.should == '123.00000000,456.00000000'
   end
 
 end

data/spec/google_places/spot_spec.rb

@@ -18,14 +18,14 @@ describe GooglePlaces::Spot do
     end
 
     it 'should be a collection of Spots' do
-      @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor)
+      @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius)
     end
 
     describe 'with a single type' do
       use_vcr_cassette 'list_spots_with_single_type'
 
       before(:each) do
-        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor, :types => 'cafe')
+        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius, :types => 'cafe')
       end
 
       it 'should have Spots with a specific type' do
@@ -39,7 +39,7 @@ describe GooglePlaces::Spot do
       use_vcr_cassette 'list_spots_with_multiple_types'
 
       before(:each) do
-        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor, :types => ['food','establishment'])
+        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius, :types => ['food','establishment'])
       end
 
       it 'should have Spots with specific types' do
@@ -53,7 +53,7 @@ describe GooglePlaces::Spot do
       use_vcr_cassette 'list_spots_with_name'
 
       before(:each) do
-        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor, :name => 'italian')
+        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius, :name => 'italian')
       end
 
       # Apparently the Google Places API returns spots with
@@ -72,7 +72,7 @@ describe GooglePlaces::Spot do
       use_vcr_cassette 'list_spots_with_name_and_types'
 
       before(:each) do
-        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor, :types => ['food','establishment'], :name => 'italian')
+        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius, :types => ['food','establishment'], :name => 'italian')
       end
 
       # Apparently the Google Places API returns spots with
@@ -97,7 +97,7 @@ describe GooglePlaces::Spot do
       use_vcr_cassette 'list_spots_with_types_and_exclusion'
 
       it 'should exclude spots with type "restaurant"' do
-        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor, :types => ['food','establishment'], :exclude => 'restaurant')
+        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius, :types => ['food','establishment'], :exclude => 'restaurant')
 
         @collection.map(&:types).each do |types|
           types.should_not include('restaurant')
@@ -105,7 +105,7 @@ describe GooglePlaces::Spot do
       end
 
       it 'should exclude spots with type "restaurant" and "cafe"' do
-        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, :radius => @radius, :sensor => @sensor, :types => ['food','establishment'], :exclude => ['restaurant', 'cafe'])
+        @collection = GooglePlaces::Spot.list(@lat, @lng, api_key, @sensor, :radius => @radius, :types => ['food','establishment'], :exclude => ['restaurant', 'cafe'])
 
         @collection.map(&:types).each do |types|
           types.should_not include('restaurant')
@@ -124,7 +124,7 @@ describe GooglePlaces::Spot do
     end
 
     it 'should be a collection of Spots' do
-      @collection = GooglePlaces::Spot.list_by_query("Statue of liberty, New York", api_key, :sensor => @sensor)
+      @collection = GooglePlaces::Spot.list_by_query("Statue of liberty, New York", api_key, @sensor)
     end
 
   end
@@ -132,7 +132,7 @@ describe GooglePlaces::Spot do
   context 'Find a single spot' do
     use_vcr_cassette 'single_spot'
     before :each do
-      @spot = GooglePlaces::Spot.find(@reference, api_key, :sensor => @sensor)
+      @spot = GooglePlaces::Spot.find(@reference, api_key, @sensor)
     end
     it 'should be a Spot' do
       @spot.class.should == GooglePlaces::Spot

data/spec/vcr_setup.rb

@@ -1,8 +1,8 @@
 require 'vcr'
 
-VCR.config do |c|
+VCR.configure do |c|
   c.cassette_library_dir     = 'spec/vcr_cassettes'
-  c.stub_with                  :fakeweb
+  c.hook_into                  :fakeweb
   c.ignore_localhost         = true
   c.default_cassette_options = { :record => :new_episodes }
 end

metadata

@@ -1,88 +1,88 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: google_places
-version: !ruby/object:Gem::Version 
-  hash: 25
+version: !ruby/object:Gem::Version
+  version: '0.9'
   prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
 platform: ruby
-authors: 
+authors:
 - Marcel de Graaf
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-07-14 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-12-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: httparty
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: fakeweb
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fakeweb
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: vcr
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
-description: This gem provides a Ruby wrapper around the Google Places API for use in your own project. Please note that this gem does not provide OAuth authentication.
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This gem provides a Ruby wrapper around the Google Places API for use
+  in your own project. Please note that this gem does not provide OAuth authentication.
+email:
 - mail@marceldegraaf.net
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - Gemfile.lock
@@ -105,38 +105,29 @@ files:
 - spec/vcr_setup.rb
 homepage: https://github.com/marceldegraaf/google_places
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: A Ruby wrapper around the Google Places API.
-test_files: 
+test_files:
 - spec/api_key.sample.rb
 - spec/google_places/client_spec.rb
 - spec/google_places/location_spec.rb
@@ -144,3 +135,4 @@ test_files:
 - spec/google_places/spot_spec.rb
 - spec/spec_helper.rb
 - spec/vcr_setup.rb
+has_rdoc: