googlemaps-services 1.0.0

data/lib/googlemaps/services/elevation.rb

@@ -0,0 +1,56 @@
+require "googlemaps/services/util"
+
+
+module GoogleMaps
+  module Services
+
+    # Performs requests to the Google Maps Elevation API.
+    #
+    # @example
+    #   elevation = GoogleMaps::Services::Elevation(client)
+    #   result = elevation.query(locations: [{:lat => 52.520645, :lng => 13.409779}, "Brussels"])
+    class Elevation
+      attr_accessor :client
+
+      def initialize(client)
+        self.client = client
+      end
+
+      # Provides elevation data for locations provided on the surface of the earth, including depth locations
+      # on the ocean floor (which return negative values). Provides elevation data sampled along a path on
+      # the surface of the earth.
+      #
+      # @param [Array] locations Array of lat/lng values from which to calculate elevation data.
+      # @param [String, Array] path An encoded polyline string, or an Array of lat/lng values from which to calculate elevation data.
+      # @param [Integer] samples The number of sample points along a path for which to return elevation data.
+      #
+      # @return [String] Valid JSON or XML response.
+      def query(locations: [], path: nil, samples: 0)
+        params = {}
+
+        if path && locations
+          raise StandardError, "Should not specify both path and locations."
+        end
+
+        if locations
+          params["locations"] = Convert.shortest_path(locations)
+        end
+
+        if path
+          if path.is_a? String
+            path = "enc:#{path}"
+          elsif path.is_a? Array
+            path = Convert.shortest_path(path)
+          else
+            raise TypeError, "Path should be either a String or an Array."
+          end
+
+          params = { "path" => path, "samples" => samples }
+        end
+
+        self.client.get(url: "/maps/api/elevation/json", params: params)["results"]
+      end
+    end
+
+  end
+end

data/lib/googlemaps/services/exceptions.rb

@@ -0,0 +1,55 @@
+module GoogleMaps
+  module Services
+    # Defines errors that are raised by the Google Maps client.
+    #
+    # @since 1.0.0
+    module Exceptions
+
+      # Represents an error raised by the remote API.
+      class APIError < StandardError
+        # @return [Symbol] The response status code.
+        attr_accessor :status
+
+        def initialize(status)
+          self.status = status
+        end
+      end
+
+      # Something went wrong while trying to execute the request.
+      class TransportError < StandardError
+      end
+
+      # Represents an unexpected HTTP error.
+      class HTTPError < TransportError
+        # @return [Symbol] status_code The response status code.
+        attr_accessor :status_code
+
+        def initialize(status_code)
+          self.status_code = status_code
+        end
+
+        # Returns the string representation of this error.
+        #
+        # @return [String] Human-readable error string.
+        def to_s
+          "HTTP Error: #{self.status_code}"
+        end
+      end
+
+      # Represents a timeout error.
+      class Timeout < Exception
+        # Return the string representation of this error.
+        #
+        # @return [String] Human-readable error string.
+        def to_s
+          "The request timed out."
+        end
+      end
+
+      # Signifies that the request can be retried.
+      class RetriableRequest < Exception
+      end
+
+    end
+  end
+end

data/lib/googlemaps/services/geocoding.rb

@@ -0,0 +1,106 @@
+require "googlemaps/services/util"
+
+
+module GoogleMaps
+  module Services
+
+    # Performs requests to the Google Maps Geocoding API.
+    #
+    # @example
+    #   geocode = GoogleMaps::Services::Geocode.new(client)
+    #   result = geocode.query(address: "1600 Amphitheatre Parkway, Mountain View, CA")
+    class Geocode
+      # @return [Symbol] The HTTP client.
+      attr_accessor :client
+
+      def initialize(client)
+        self.client = client
+      end
+
+      # Geocoding is the process of converting addresses (like "1600 Amphitheatre Parkway, Mountain View, CA")
+      # into geographic coordinates (like latitude 37.423021 and longitude -122.083739), which you can use
+      # to place markers or position the map.
+      #
+      # @param [String] address The address to geocode.
+      # @param [Hash] components A component filter for which you wish to obtain a geocode.
+      #                          E.g. {'administrative_area': 'TX','country': 'US'}
+      # @param [Hash] bounds The bounding box of the viewport within which to bias geocode results more prominently.
+      #                      The hash must have :northeast and :southwest keys.
+      # @param [String] region The region code, specified as a ccTLD ("top-level domain") two-character value.
+      # @param [String] language The language in which to return results.
+      #
+      # @return [String] Valid JSON or XML response.
+      def query(address: nil, components: nil, bounds: nil, region: nil, language: nil)
+        params = {}
+
+        if address
+          params["address"] = address
+        end
+
+        if components
+          params["components"] = Convert.components(components)
+        end
+
+        if bounds
+          params["bounds"] = Convert.bounds(bounds)
+        end
+
+        if region
+          params["region"] = region
+        end
+
+        if language
+          params["language"] = language
+        end
+
+        self.client.get(url: "/maps/api/geocode/json", params: params)["results"]
+      end
+    end
+
+    # Performs requests to the Google Maps Geocoding API.
+    #
+    # @example
+    #   reverse_geocode = GoogleMaps::Services::ReverseGeocode(client)
+    #   result = reverse_geocode.query(latlng: {:lat => 52.520645, :lng => 13.409779}, language: "fr")
+    class ReverseGeocode
+      attr_accessor :client
+
+      def initialize(client)
+        self.client = client
+      end
+
+      # Reverse geocoding is the process of converting geographic coordinates into a human-readable address.
+      #
+      # @param [String, Hash] latlng The lat/lng value or place_id for which you wish to obtain the closest, human-readable address.
+      # @param [Array] result_type One or more address types to restrict results to.
+      # @param [Array] location_type One or more location types to restrict results to.
+      # @param [String] language The language in which to return results.
+      #
+      # @return [String] Valid JSON or XML response.
+      def query(latlng:, result_type: nil, location_type: nil, language: nil)
+        # Check if latlng param is a place_id string.
+        # 'place_id' strings do not contain commas; latlng strings do.
+        if latlng.is_a?(String) && !latlng.include?("'")
+          params = {"place_id" => latlng}
+        else
+          params = {"latlng" => Convert.to_latlng(latlng)}
+        end
+
+        if result_type
+          params["result_type"] = Convert.join_array("|", result_type)
+        end
+
+        if location_type
+          params["location_type"] = Convert.join_array("|", location_type)
+        end
+
+        if language
+          params["language"] = language
+        end
+
+        self.client.get(url: "/maps/api/geocode/json", params: params)["results"]
+      end
+    end
+
+  end
+end

data/lib/googlemaps/services/places.rb

@@ -0,0 +1,245 @@
+require "googlemaps/services/util"
+
+module GoogleMaps
+  module Services
+
+    # Performs requests to the Google Places API.
+    class Places
+      # @return [Symbol] The HTTP client.
+      attr_accessor :client
+
+      def initialize(client)
+        self.client = client
+      end
+
+      # Performs places search.
+      #
+      # @param [String] query The text string on which to search. E.g. "restaurant".
+      # @param [String, Hash] location The lat/lng value for which you wish to obtain the closest, human-readable address.
+      # @param [Integer] radius Distance in meters within which to bias results.
+      # @param [String] language The language in which to return results.
+      # @param [Integer] min_price Restricts results to only those places with no less than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).
+      # @param [Integer] max_price Restricts results to only those places with no greater than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).
+      # @param [TrueClass, FalseClass] open_now Return only those places that are open for business at the time the query is sent.
+      # @param [String] type Restricts the results to places matching the specified type. The full list of supported types is available here: https://developers.google.com/places/supported_types
+      # @param [String] page_token Token from a previous search that when provided will returns the next page of results for the same search.
+      #
+      # @return [Hash] Valid JSON or XML response.
+      def search(query:, location: nil, radius: nil, language: nil, min_price: nil,
+                 max_price: nil, open_now: false, type: nil, page_token: nil)
+        _places(url_part: "text", query: query, location: location, radius: radius,
+                language: language, min_price: min_price,  max_price: max_price,
+                open_now: open_now, type: type, page_token: page_token)
+      end
+
+      # Performs nearby search for places.
+      #
+      # @param [String, Hash] location The lat/lng value for which you wish to obtain the closest, human-readable address.
+      # @param [Integer] radius Distance in meters within which to bias results.
+      # @param [String] keyword A term to be matched against all content that Google has indexed for this place.
+      # @param [String] language The language in which to return results.
+      # @param [Integer] min_price Restricts results to only those places with no less than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).
+      # @param [Integer] max_price Restricts results to only those places with no greater than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).
+      # @param [Array] name One or more terms to be matched against the names of places.
+      # @param [TrueClass, FalseClass] open_now Return only those places that are open for business at the time the query is sent.
+      # @param [String] rank_by Specifies the order in which results are listed. Possible values are: prominence (default), distance
+      # @param [String] type Restricts the results to places matching the specified type. The full list of supported types is available here: https://developers.google.com/places/supported_types
+      # @param [String] page_token Token from a previous search that when provided will returns the next page of results for the same search.
+      #
+      # @return [Hash] Valid JSON or XML response.
+      def nearby(location:, radius: nil, keyword: nil, language: nil, min_price: nil,
+                 max_price: nil, name: nil, open_now: false, rank_by: nil, type: nil, page_token: nil)
+        if rank_by == "distance"
+          if !(keyword || name || type)
+            raise StandardError, "either a keyword, name or type arg is required when rank_by is set to distance."
+          elsif radius
+            raise StandardError, "radius cannot be specified when rank_by is set to distance."
+          end
+        end
+
+        _places(url_part: "nearby", location: location, radius: radius, keyword: keyword, language: language,
+                min_price: min_price, max_price: max_price, name: name, open_now: open_now, rank_by: rank_by,
+                type: type, page_token: page_token)
+      end
+
+      # Performs radar search for places
+      #
+      # @param [String, Hash] location The latitude/longitude value for which you wish to obtain the closest, human-readable address.
+      # @param [Integer] radius Distance in meters within which to bias results.
+      # @param [String] keyword A term to be matched against all content that Google has indexed for this place.
+      # @param [Integer] min_price Restricts results to only those places with no less than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).
+      # @param [Integer] max_price Restricts results to only those places with no greater than this price level. Valid values are in the range from 0 (most affordable) to 4 (most expensive).
+      # @param [Array] name One or more terms to be matched against the names of places.
+      # @param [TrueClass, FalseClass] open_now Return only those places that are open for business at the time the query is sent.
+      # @param [String] type: Restricts the results to places matching the specified type. The full list of supported types is available here: https://developers.google.com/places/supported_types
+      #
+      # @return [Hash] Valid JSON or XML response.
+      def radar(location:, radius:, keyword: nil, min_price: nil,
+                     max_price: nil, name: nil, open_now: false, type: nil)
+        if !(keyword || name || type)
+          raise StandardError, "either a keyword, name, or type arg is required."
+        end
+
+        _places(url_part: "radar", location: location, radius: radius,
+                       keyword: keyword, min_price: min_price, max_price: max_price,
+                       name: name, open_now: open_now, type: type)
+      end
+
+      # Handler for "places", "places_nearby" and "places_radar" queries.
+      # @private
+      def _places(url_part:, query: nil, location: nil, radius: nil, keyword: nil, language: nil,
+                  min_price: 0, max_price: 4, name: nil, open_now: false, rank_by: nil, type: nil,
+                  page_token: nil)
+        params = { "minprice" => min_price, "maxprice" => max_price }
+
+        if query
+          params["query"] = query
+        end
+
+        if location
+          params["location"] = Convert.to_latlng(location)
+        end
+
+        if radius
+          params["radius"] = radius
+        end
+
+        if keyword
+          params["keyword"] = keyword
+        end
+
+        if language
+          params["language"] = language
+        end
+
+        if name
+          params["name"] = Convert.join_array(" ", name)
+        end
+
+        if open_now
+          params["opennow"] = "true"
+        end
+
+        if rank_by
+          params["rankby"] = rank_by
+        end
+
+        if type
+          params["type"] = type
+        end
+
+        if page_token
+          params["pagetoken"] = page_token
+        end
+
+        self.client.get(url: "/maps/api/place/#{url_part}search/json", params: params)
+      end
+
+
+      # Comprehensive details for an individual place.
+      #
+      # @param [String] place_id A textual identifier that uniquely identifies a place, returned from a Places search.
+      # @param [String] language The language in which to return results.
+      #
+      # @return [Hash] Valid JSON or XML response.
+      def place_details(place_id:, language: nil)
+        params = { "placeid" => place_id }
+        if language
+          params["language"] = language
+        end
+
+        self.client.get(url: "/maps/api/place/details/json", params: params)
+      end
+
+      # Downloads a photo from the Places API.
+      #
+      # @param [String] photo_reference: A string identifier that uniquely identifies a photo, as provided by either a Places search or Places detail request.
+      # @param [Integer] max_width: Specifies the maximum desired width, in pixels.
+      # @param [Integer] max_height: Specifies the maximum desired height, in pixels.
+      #
+      # @return [String] URL of the photo.
+      def place_photo(photo_reference:, max_width: nil, max_height: nil)
+        if !(max_width || max_height)
+          raise StandardError, "a max_width or max_height arg is required"
+        end
+
+        params = {"photoreference" => photo_reference}
+
+        if max_width
+          params["maxwidth"] = max_width
+        end
+
+        if max_height
+          params["maxheight"] = max_height
+        end
+
+        self.client.get(url: "/maps/api/place/photo", params: params)
+      end
+
+      # Returns Place predictions given a textual search string and optional geographic bounds.
+      #
+      # @param [String] input_text The text string on which to search.
+      # @param [Integer] offset The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is 'Google' and the offset is 3, the service will match on 'Goo'.
+      # @param [String, Hash] location The latitude/longitude value for which you wish to obtain the closest, human-readable address.
+      # @param [Integer] radius Distance in meters within which to bias results.
+      # @param [String] language The language in which to return results.
+      # @param [String] type Restricts the results to places matching the specified type. The full list of supported types is available here: https://developers.google.com/places/web-service/autocomplete#place_types
+      # @param [Hash] components A component filter for which you wish to obtain a geocode, e.g. "{'administrative_area': 'TX','country': 'US'}"
+      #
+      # @return [Array] Array of predictions.
+      def autocomplete(input_text:, offset: nil, location: nil, radius: nil, language: nil, type: nil, components: nil)
+        _autocomplete(url_part: "", input_text: input_text, offset: offset, location: location,
+                      radius: radius, language: language, type: type, components: components)
+      end
+
+      # Returns Place predictions given a textual search query, such as "pizza near Brussels", and optional geographic bounds.
+      #
+      # @param [String] input_text The text query on which to search.
+      # @param [Integer] offset The position, in the input term, of the last character that the service uses to match predictions. For example, if the input is 'Google' and the offset is 3, the service will match on 'Goo'.
+      # @param [String, Hash] location The latitude/longitude value for which you wish to obtain the closest, human-readable address.
+      # @param [Integer] radius Distance in meters within which to bias results.
+      # @param [String] language The language in which to return results.
+      #
+      # @return [Array] Array of predictions.
+      def autocomplete_query(input_text:, offset: nil, location: nil, radius: nil, language: nil)
+        _autocomplete(url_part: "query", input_text: input_text, offset: offset,
+                      location: location, radius: radius, language: language)
+      end
+
+      # Handler for "autocomplete" and "autocomplete_query" queries.
+      # @private
+      def _autocomplete(url_part:, input_text:, offset: nil, location: nil,
+                       radius: nil, language: nil, type: nil, components: nil)
+        params = { "input" => input_text }
+
+        if offset
+          params["offset"] = offset
+        end
+
+        if location
+          params["location"] = Convert.to_latlng(location)
+        end
+
+        if radius
+          params["radius"] = radius
+        end
+
+        if language
+          params["language"] = language
+        end
+
+        if type
+          params["type"] = type
+        end
+
+        if components
+          params["components"] = Convert.components(components)
+        end
+
+        self.client.get(url: "/maps/api/place/#{url_part}autocomplete/json", params: params)["predictions"]
+      end
+
+      private :_places, :_autocomplete
+    end
+  end
+end