google_maps_service 0.1.0

data/lib/google_maps_service/directions.rb

@@ -0,0 +1,93 @@
+module GoogleMapsService
+
+  # Performs requests to the Google Maps Directions API.
+  module Directions
+
+    # Get directions between an origin point and a destination point.
+    #
+    # @param [String, Hash, Array] origin The address or latitude/longitude value from which you wish
+    #         to calculate directions.
+    # @param [String, Hash, Array] destination The address or latitude/longitude value from which
+    #     you wish to calculate directions.
+    # @param [String] mode Specifies the mode of transport to use when calculating
+    #     directions. One of "driving", "walking", "bicycling" or "transit"
+    # @param [Array<String>, Array<Hash>, Array<Array>] waypoints Specifies an array of waypoints. Waypoints alter a
+    #     route by routing it through the specified location(s).
+    # @param [Boolean] alternatives If True, more than one route may be returned in the
+    #     response.
+    # @param [Array, String] avoid Indicates that the calculated route(s) should avoid the
+    #     indicated features.
+    # @param [String] language The language in which to return results.
+    # @param [String] units Specifies the unit system to use when displaying results.
+    #     "metric" or "imperial"
+    # @param [String] region The region code, specified as a ccTLD ("top-level domain"
+    #     two-character value.
+    # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
+    # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
+    #     directions. Note: you can't specify both departure_time and
+    #     arrival_time.
+    # @param [Boolean] optimize_waypoints Optimize the provided route by rearranging the
+    #     waypoints in a more efficient order.
+    # @param [String, Array<String>] transit_mode Specifies one or more preferred modes of transit.
+    #     This parameter may only be specified for requests where the mode is
+    #     transit. Valid values are "bus", "subway", "train", "tram", "rail".
+    #     "rail" is equivalent to ["train", "tram", "subway"].
+    # @param [String] transit_routing_preference Specifies preferences for transit
+    #     requests. Valid values are "less_walking" or "fewer_transfers"
+    #
+    # @return List of routes
+    def directions(origin: nil, destination: nil,
+        mode: nil, waypoints: nil, alternatives: false, avoid: nil,
+        language: nil, units: nil, region: nil, departure_time: nil,
+        arrival_time: nil, optimize_waypoints: false, transit_mode: nil,
+        transit_routing_preference: nil)
+
+      params = {
+        origin: _convert_waypoint(origin),
+        destination: _convert_waypoint(destination)
+      }
+
+      if mode
+        # NOTE(broady): the mode parameter is not validated by the Maps API
+        # server. Check here to prevent silent failures.
+        unless ["driving", "walking", "bicycling", "transit"].include?(mode)
+          raise ArgumentError, "Invalid travel mode."
+        end
+        params[:mode] = mode
+      end
+
+      if waypoints
+        waypoints = GoogleMapsService::Convert.as_list(waypoints)
+        waypoints = waypoints.map { |waypoint| _convert_waypoint(waypoint) }
+        waypoints = ["optimize:true"] + waypoints if optimize_waypoints
+
+        params[:waypoints] = GoogleMapsService::Convert.join_list("|", waypoints)
+      end
+
+      params[:alternatives] = "true" if alternatives
+      params[:avoid] = GoogleMapsService::Convert.join_list("|", avoid) if avoid
+      params[:language] = language if language
+      params[:units] = units if units
+      params[:region] = region if region
+      params[:departure_time] = GoogleMapsService::Convert.time(departure_time) if departure_time
+      params[:arrival_time] = GoogleMapsService::Convert.time(arrival_time) if arrival_time
+
+      if departure_time and arrival_time
+        raise ArgumentError, "Should not specify both departure_time and arrival_time."
+      end
+
+      params[:transit_mode] = GoogleMapsService::Convert.join_list("|", transit_mode) if transit_mode
+      params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference
+
+      return get("/maps/api/directions/json", params)[:routes]
+    end
+
+    private
+      def _convert_waypoint(waypoint)
+        if waypoint.kind_of?(String)
+          return waypoint
+        end
+        return GoogleMapsService::Convert.latlng(waypoint)
+      end
+  end
+end

data/lib/google_maps_service/distance_matrix.rb

@@ -0,0 +1,85 @@
+module GoogleMapsService
+
+  # Performs requests to the Google Maps Distance Matrix API.
+  module DistanceMatrix
+
+    # Gets travel distance and time for a matrix of origins and destinations.
+    #
+    # @param [Array<String>, Array<Hash>, Array<Array>] origins One or more addresses and/or latitude/longitude values,
+    #         from which to calculate distance and time. If you pass an address
+    #         as a string, the service will geocode the string and convert it to
+    #         a latitude/longitude coordinate to calculate directions.
+    # @param [Array<String>, Array<Hash>, Array<Array>] destinations One or more addresses and/or lat/lng values, to
+    #         which to calculate distance and time. If you pass an address as a
+    #         string, the service will geocode the string and convert it to a
+    #         latitude/longitude coordinate to calculate directions.
+    # @param [String] mode Specifies the mode of transport to use when calculating
+    #         directions. Valid values are "driving", "walking", "transit" or
+    #         "bicycling".
+    # @param [String] language The language in which to return results.
+    # @param [String] avoid Indicates that the calculated route(s) should avoid the
+    #     indicated features. Valid values are "tolls", "highways" or "ferries"
+    # @param [String] units Specifies the unit system to use when displaying results.
+    #     Valid values are "metric" or "imperial"
+    # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
+    # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
+    #     directions. Note: you can't specify both departure_time and
+    #     arrival_time.
+    # @param [String, Array<String>] transit_mode Specifies one or more preferred modes of transit.
+    #     This parameter may only be specified for requests where the mode is
+    #     transit. Valid values are "bus", "subway", "train", "tram", "rail".
+    #     "rail" is equivalent to ["train", "tram", "subway"].
+    # @param [String] transit_routing_preference Specifies preferences for transit
+    #     requests. Valid values are "less_walking" or "fewer_transfers"
+    #
+    # @return matrix of distances. Results are returned in rows, each row
+    #     containing one origin paired with each destination.
+    def distance_matrix(origins: nil, destinations: nil,
+                        mode: nil, language: nil, avoid: nil, units: nil,
+                        departure_time: nil, arrival_time: nil, transit_mode: nil,
+                        transit_routing_preference: nil)
+      params = {
+        origins: _convert_path(origins),
+        destinations: _convert_path(destinations)
+      }
+
+      if mode
+        # NOTE(broady): the mode parameter is not validated by the Maps API
+        # server. Check here to prevent silent failures.
+        unless ["driving", "walking", "bicycling", "transit"].include?(mode)
+          raise ArgumentError, "Invalid travel mode."
+        end
+        params[:mode] = mode
+      end
+
+      params[:language] = language if language
+
+      if avoid
+        unless ["tolls", "highways", "ferries"].include?(avoid)
+          raise ArgumentError, "Invalid route restriction."
+        end
+        params[:avoid] = avoid
+      end
+
+
+      params[:units] = units if units
+      params[:departure_time] = convert.time(departure_time) if departure_time
+      params[:arrival_time] = convert.time(arrival_time) if arrival_time
+
+      if departure_time and arrival_time
+        raise ArgumentError, "Should not specify both departure_time and arrival_time."
+      end
+
+      params[:transit_mode] = convert.join_list("|", transit_mode) if transit_mode
+      params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference
+
+      return get("/maps/api/distancematrix/json", params)
+    end
+
+    private
+      def _convert_path(waypoints)
+        waypoints = GoogleMapsService::Convert.as_list(waypoints)
+        return GoogleMapsService::Convert.join_list("|", waypoints.map { |k| k.kind_of?(String) ? k : GoogleMapsService::Convert.latlng(k) })
+      end
+  end
+end

data/lib/google_maps_service/elevation.rb

@@ -0,0 +1,57 @@
+module GoogleMapsService
+
+  # Performs requests to the Google Maps Elevation API.
+  module Elevation
+
+    # Provides elevation data for locations provided on the surface of the
+    # earth, including depth locations on the ocean floor (which return negative
+    # values)
+    #
+    # @param [Array] locations A single latitude/longitude hash, or an array of
+    #         latitude/longitude hash from which you wish to calculate
+    #         elevation data.
+    #
+    # @return [Array] Array of elevation data responses
+    def elevation(locations: nil)
+      params = {}
+      if locations.kind_of?(Array) and locations.length == 2 and not locations[0].kind_of?(Array)
+        locations = [locations]
+      end
+
+      params[:locations] = _convert_locations(locations)
+
+      return get("/maps/api/elevation/json", params)[:results]
+    end
+
+    # Provides elevation data sampled along a path on the surface of the earth.
+    #
+    # @param [String, Array] path A encoded polyline string, or a list of
+    #         latitude/longitude tuples from which you wish to calculate
+    #         elevation data.
+    #
+    # @param [Integer] samples The number of sample points along a path for which to
+    #         return elevation data.
+    #
+    # @return [Array] Array of elevation data responses
+    def elevation_along_path(path: nil, samples: nil)
+      if path.kind_of?(String)
+        path = "enc:%s" % path
+      else
+        path = _convert_locations(path)
+      end
+
+      params = {
+        path: path,
+        samples: samples
+      }
+
+      return get("/maps/api/elevation/json", params)[:results]
+    end
+
+    private
+      def _convert_locations(locations)
+        locations = GoogleMapsService::Convert.as_list(locations)
+        return GoogleMapsService::Convert.join_list("|", locations.map { |k| k.kind_of?(String) ? k : GoogleMapsService::Convert.latlng(k) })
+      end
+  end
+end

data/lib/google_maps_service/errors.rb

@@ -0,0 +1,40 @@
+module GoogleMapsService
+  module Error
+    # Base error, capable of wrapping another
+    class BaseError < StandardError
+      attr_reader :response
+
+      def initialize(response)
+        @response = response
+      end
+    end
+
+    # An exception that is raised if a redirect is required
+    class RedirectError < BaseError
+    end
+
+    # A 4xx class HTTP error occurred.
+    class ClientError < BaseError
+    end
+
+    # A 5xx class HTTP error occurred.
+    class ServerError < BaseError
+    end
+
+    # An API error occured.
+    class ApiError < BaseError
+    end
+
+    # Requiered query is missing
+    class InvalidRequestError < ApiError
+    end
+
+    # Over quota.
+    class RateLimitError < ApiError
+    end
+
+    # An unathorized error occurred. It might be caused by invalid key/secret or invalid access.
+    class RequestDeniedError < ApiError
+    end
+  end
+end

data/lib/google_maps_service/geocoding.rb

@@ -0,0 +1,58 @@
+require 'google_maps_service/convert'
+
+module GoogleMapsService
+
+  # Performs requests to the Google Maps Geocoding API.
+  module Geocoding
+
+    # 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,
+    #                    for example: `{ 'administrative_area': 'TX','country': 'US' }`
+    # @param [String, Hash] bounds The bounding box of the viewport within which to bias geocode
+    #                results more prominently. Accept string or hash with 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 Array of geocoding results.
+    def geocode(address: nil, components: nil, bounds: nil, region: nil, language: nil)
+      params = {}
+
+      params[:address] = address if address
+      params[:components] = GoogleMapsService::Convert.components(components) if components
+      params[:bounds] = GoogleMapsService::Convert.bounds(bounds) if bounds
+      params[:region] = region if region
+      params[:language] = language if language
+
+      return get('/maps/api/geocode/json', params)[:results]
+    end
+
+    # Reverse geocoding is the process of converting geographic coordinates into a
+    # human-readable address.
+    #
+    # @param [Hash, Array] latlng The latitude/longitude value for which you wish to obtain the
+    #                closest, human-readable address#
+    # @param [String, Array<String>] result_type One or more address types to restrict results to.
+    # @param [Array<String>] location_type One or more location types to restrict results to.
+    # @param [String] language The language in which to return results.
+    #
+    # @return Array of reverse geocoding results.
+    def reverse_geocode(latlng: nil, result_type: nil, location_type: nil, language: nil)
+      params = {
+        latlng: GoogleMapsService::Convert.latlng(latlng)
+      }
+
+      params[:result_type] = GoogleMapsService::Convert.join_list("|", result_type) if result_type
+      params[:location_type] = GoogleMapsService::Convert.join_list("|", location_type) if location_type
+      params[:language] = language if language
+
+      return get('/maps/api/geocode/json', params)[:results]
+    end
+
+  end
+end

data/lib/google_maps_service/roads.rb

@@ -0,0 +1,141 @@
+require 'multi_json'
+
+module GoogleMapsService
+
+  # Performs requests to the Google Maps Roads API."""
+  module Roads
+
+    # Base URL of Google Maps Roads API
+    ROADS_BASE_URL = "https://roads.googleapis.com"
+
+    # Snaps a path to the most likely roads travelled.
+    #
+    # Takes up to 100 GPS points collected along a route, and returns a similar
+    # set of data with the points snapped to the most likely roads the vehicle
+    # was traveling along.
+    #
+    # @param [] path The path to be snapped. A list of latitude/longitude tuples.
+    # :type path: list
+    #
+    # @param [] interpolate Whether to interpolate a path to include all points
+    #         forming the full road-geometry. When true, additional interpolated
+    #         points will also be returned, resulting in a path that smoothly
+    #         follows the geometry of the road, even around corners and through
+    #         tunnels.  Interpolated paths may contain more points than the
+    #         original path.
+    # :type interpolate: bool
+    #
+    # :rtype: A list of snapped points.
+    def snap_to_roads(path: nil, interpolate: false)
+      if path.kind_of?(Array) and path.length == 2 and not path[0].kind_of?(Array)
+        path = [path]
+      end
+
+      path = _convert_path(path)
+
+      params = {
+        path: path
+      }
+
+      params[:interpolate] = "true" if interpolate
+
+      return get("/v1/snapToRoads", params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))[:snappedPoints]
+    end
+
+    # Returns the posted speed limit (in km/h) for given road segments.
+    #
+    # @param [String, Array<String>] place_ids The Place ID of the road segment. Place IDs are returned
+    #         by the snap_to_roads function. You can pass up to 100 Place IDs.
+    # @return Array of speed limits.
+    def speed_limits(place_ids: nil)
+      params = GoogleMapsService::Convert.as_list(place_ids).map { |place_id| ["placeId", place_id] }
+
+      return get("/v1/speedLimits", params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))[:speedLimits]
+    end
+
+
+    # Returns the posted speed limit (in km/h) for given road segments.
+    #
+    # The provided points will first be snapped to the most likely roads the
+    # vehicle was traveling along.
+    #
+    # @param [Hash, Array] path The path of points to be snapped. A list of (or single)
+    #         latitude/longitude tuples.
+    #
+    # @return [Hash] a dict with both a list of speed limits and a list of the snapped
+    #         points.
+    def snapped_speed_limits(path: nil)
+
+      if path.kind_of?(Array) and path.length == 2 and not path[0].kind_of?(Array)
+        path = [path]
+      end
+
+      path = _convert_path(path)
+
+      params = {
+        path: path
+      }
+
+      return get("/v1/speedLimits", params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))
+    end
+
+    private
+      def _convert_path(paths)
+        paths = GoogleMapsService::Convert.as_list(paths)
+        return GoogleMapsService::Convert.join_list("|", paths.map { |k| k.kind_of?(String) ? k : GoogleMapsService::Convert.latlng(k) })
+      end
+
+      # Extracts a result from a Roads API HTTP response.
+      def extract_roads_body(response)
+        begin
+          body = MultiJson.load(response.body, :symbolize_keys => true)
+        rescue
+          unless response.status_code == 200
+            check_response_status_code(response)
+          end
+          raise GoogleMapsService::Error::ApiError.new(response), "Received a malformed response."
+        end
+
+        if body.has_key?(:error)
+          error = body[:error]
+          status = error[:status]
+
+          if status == 'INVALID_ARGUMENT'
+            if error[:message] == 'The provided API key is invalid.'
+              raise GoogleMapsService::Error::RequestDeniedError.new(response), error[:message]
+            end
+            raise GoogleMapsService::Error::InvalidRequestError.new(response), error[:message]
+          end
+
+          if status == 'PERMISSION_DENIED'
+            raise GoogleMapsService::Error::RequestDeniedError.new(response), error[:message]
+          end
+
+          if status == 'RESOURCE_EXHAUSTED'
+            raise GoogleMapsService::Error::RateLimitError.new(response), error[:message]
+          end
+
+          if error.has_key?(:message)
+            raise GoogleMapsService::Error::ApiError.new(response), error[:message]
+          else
+            raise GoogleMapsService::Error::ApiError.new(response)
+          end
+        end
+
+        unless response.status_code == 200
+          raise GoogleMapsService::Error::HTTPError.new(response)
+        end
+
+        return body
+      end
+  end
+end