googlemaps-services 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c10843ca035ec6fe71bd6edc2a338d2c0eee8c22
+  data.tar.gz: 092b6d0d9398c95482a74ad88fd4192af0061517
+SHA512:
+  metadata.gz: c08995e5da233ce70dc80694b8b5d479cb5a9ce05a253aef8df59bfa696a8e6f5861f1fa9495b393cf21163dd7eb84fc8aa056fe3691c2f552571db4cdff23ac
+  data.tar.gz: 046dca085ea8c8d7000e7bab4adbadbbd680758feb3d752e919e823a4ac5bfc1144c312527db141a7a501c05277b35db294c7acff4d87e8e7a503ee2eec5fc6d

data/lib/googlemaps/services.rb

@@ -0,0 +1 @@
+require "googlemaps/services/version"

data/lib/googlemaps/services/client.rb

@@ -0,0 +1,254 @@
+require "googlemaps/services/exceptions"
+require "googlemaps/services/version"
+require "googlemaps/services/util"
+require "net/http"
+require "json"
+
+# Core functionality, common across all API requests.
+#
+# @since 1.0.0
+module GoogleMaps
+  # Core services that connect to Google Maps API web services.
+  #
+  # @since 1.0.0
+  module Services
+    $USER_AGENT = "GoogleMapsRubyClient/" + VERSION
+    $DEFAULT_BASE_URL = "https://maps.googleapis.com"
+    $RETRIABLE_STATUSES = [500, 503, 504]
+
+    # Performs requests to the Google Maps API web services.
+    class GoogleClient
+      include GoogleMaps::Services::Exceptions
+
+      # @return [Symbol] API key. Required, unless "client_id" and "client_secret" are set.
+      attr_accessor :key
+      # @return [Symbol] timeout Combined connect and read timeout for HTTP requests, in seconds.
+      attr_accessor :timeout
+      # @return [Symbol] Client ID (for Maps API for Work).
+      attr_accessor :client_id
+      # @return [Symbol] base64-encoded client secret (for Maps API for Work).
+      attr_accessor :client_secret
+      # @return [Symbol] attribute used for tracking purposes. Can only be used with a Client ID.
+      attr_accessor :channel
+      # @return [Symbol] timeout across multiple retriable requests, in seconds.
+      attr_accessor :retry_timeout
+      # @return [Symbol] extra options for Net::HTTP client.
+      attr_accessor :request_opts
+      # @return [Symbol] number of queries per second permitted. If the rate limit is reached, the client will sleep for the appropriate amout of time before it runs the current query.
+      attr_accessor :queries_per_second
+      # @return [Symbol] keeps track of sent queries.
+      attr_accessor :sent_times
+
+      def initialize(key:, client_id: nil, client_secret: nil, timeout: nil,
+                     connect_timeout: nil, read_timeout: nil,retry_timeout: 60, request_opts: nil,
+                     queries_per_second: 10, channel: nil)
+        if !key && !(client_secret && client_id)
+          raise StandardError, "Must provide API key or enterprise credentials when creationg client."
+        end
+
+        if key && !key.start_with?("AIza")
+          raise StandardError, "Invalid API key provided."
+        end
+
+        if channel
+          if !client_id
+            raise StandardError, "The channel argument must be used with a client ID."
+          end
+
+          if !/^[a-zA-Z0-9._-]*$/.match(channel)
+            raise StandardError, "The channel argument must be an ASCII alphanumeric string. The period (.), underscore (_) and hyphen (-) characters are allowed."
+          end
+        end
+
+        self.key = key
+
+        if timeout && (connect_timeout || read_timeout)
+          raise StandardError, "Specify either timeout, or connect_timeout and read_timeout."
+        end
+
+        if connect_timeout && read_timeout
+          self.timeout = { :connect_timeout => connect_timeout, :read_timeout => read_timeout }
+        else
+          self.timeout = timeout
+        end
+
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.channel = channel
+        self.retry_timeout = retry_timeout
+        self.request_opts = request_opts || {}
+        self.request_opts.merge!({
+                                      :headers => {"User-Agent" => $USER_AGENT},
+                                      :timeout => self.timeout,
+                                      :verify => true
+                                    })
+
+        self.queries_per_second = queries_per_second
+        self.sent_times = Array.new
+      end
+
+      # Performs HTTP GET requests with credentials, returning the body as JSON or XML
+      #
+      # @param [String] url URL path for the request. Should begin with a slash.
+      # @param [Hash] params HTTP GET parameters.
+      # @param [Time] first_request_time The time of the first request (nil if no retries have occurred).
+      # @param [Integer] retry_counter The number of this retry, or zero for first attempt.
+      # @param [String] base_url The base URL for the request. Defaults to the Google Maps API server. Should not have a trailing slash.
+      # @param [TrueClass, FalseClass] accepts_clientid Flag whether this call supports the client/signature params. Some APIs require API keys (e.g. Roads).
+      # @param [Proc] extract_body A function that extracts the body from the request. If the request was not successful, the function should raise a
+      #               GoogleMaps::Services::Exceptions::HTTËrror or GoogleMaps::Services::Exceptions::APIError as appropriate.
+      # @param [Hash] request_opts Additional options for the Net::HTTP client.
+      #
+      # @return [Hash, Array] response body, either in JSON or XML.
+      def get(url:, params:, first_request_time: nil, retry_counter: nil, base_url: $DEFAULT_BASE_URL,
+              accepts_clientid: true, extract_body: nil, request_opts: nil)
+        if !first_request_time
+          first_request_time = Util.current_time
+        end
+
+        elapsed = Time.now - first_request_time
+        if elapsed > self.retry_timeout
+          raise Timeout
+        end
+
+        if retry_counter && retry_counter > 0
+          # 0.5 * (1.5 ^ i) is an increased sleep time of 1.5x per iteration,
+          # starting at 0.5s when retry_counter=0. The first retry will occur
+          # at 1, so subtract that first.
+          delay_seconds = 0.5 * 1.5 ** (retry_counter - 1)
+          # Jitter this value by 50% and pause.
+          sleep(delay_seconds * (random.random() + 0.5))
+        end
+
+        authed_url = generate_auth_url(url, params, accepts_clientid)
+
+        # Default to the client-level self.request_opts, with method-level
+        # request_opts arg overriding.
+        request_opts = self.request_opts.merge(request_opts || {})
+
+        # Construct the Request URI
+        uri = URI.parse(base_url + authed_url)
+
+        # Add request headers
+        req = Net::HTTP::Get.new(uri.to_s)
+
+        request_opts[:headers].each { |header,value| req.add_field(header, value) }
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        # Get HTTP response
+        resp = http.request(req)
+
+        # Handle response errors
+        case resp
+        when Net::HTTPRequestTimeOut
+          raise Timeout
+        when Exception
+          raise TransportError, "HTTP GET request failed."
+        end
+
+        if $RETRIABLE_STATUSES.include? resp.code.to_i
+          # Retry request
+          self.get(url, params, first_request_time, retry_counter + 1,
+                   base_url, accepts_clientid, extract_body)
+        end
+
+        # Check if the time of the nth previous query (where n is queries_per_second)
+        # is under a second ago - if so, sleep for the difference.
+        if self.sent_times && (self.sent_times.length == self.queries_per_second)
+          elapsed_since_earliest = Util.current_time - self.sent_times[0]
+          if elapsed_since_earliest < 1
+            sleep(1 - elapsed_since_earliest)
+          end
+        end
+
+        begin
+          # Extract HTTP response body
+          if extract_body
+            result = extract_body.call(resp)
+          else
+            result = get_json_body(resp)
+          end
+          self.sent_times.push(Util.current_time)
+          return result
+        rescue RetriableRequest
+          # retry request
+          return self.get(url, params, first_request_time, retry_counter + 1,
+                          base_url, accepts_clientid, extract_body)
+        end
+      end
+
+      # Extracts the JSON body of the HTTP response.
+      #
+      # @private
+      #
+      # @param [Net::HTTPResponse] resp HTTP response object.
+      #
+      # @return [Hash, Array] Valid JSON response.
+      def get_json_body(resp)
+        status_code = resp.code.to_i
+        if status_code >= 300 && status_code < 400
+          return resp["location"]
+        end
+
+        if resp.code.to_i != 200
+          raise HTTPError.new(resp.code)
+        end
+
+        # Parse the response body
+        begin
+          body = JSON.parse(resp.body)
+        rescue JSON::ParserError
+          raise APIError.new(status_code), "Received a malformed response."
+        end
+
+        api_status = body["status"]
+        if api_status == "OK" || api_status == "ZERO_RESULTS"
+          return body
+        end
+
+        if api_status == "OVER_QUERY_LIMIT"
+          raise RetriableRequest
+        end
+
+        if body.key?("error_message")
+          raise APIError.new(api_status), body["error_message"]
+        else
+          raise APIError.new(api_status)
+        end
+      end
+
+      # Returns the path and query string portion of the request URL, first adding any necessary parameters.
+      #
+      # @private
+      #
+      # @param [String] path The path portion of the URL.
+      # @param [Hash] params URL parameters.
+      # @param [TrueClass, FalseClass] accepts_clientid Flag whether to use a Client ID or not.
+      #
+      # @return [String] the final request path.
+      def generate_auth_url(path, params={}, accepts_clientid)
+        if accepts_clientid && self.client_id && self.client_secret
+          if self.channel
+            params["channel"] = self.channel
+          end
+          params["client"] = self.client_id
+
+          path = [path, Util.urlencode_params(params)].join("?")
+          sig = Util.sign_hmac(self.client_secret, path)
+          return path + "&signature=" + sig
+        end
+
+        if self.key
+          params["key"] = self.key
+          return path + "?" + Util.urlencode_params(params)
+        end
+
+        raise StandardError, "Must provide API key for this API. It does not accept enterprise credentials."
+      end
+
+      private :get_json_body, :generate_auth_url
+    end
+
+  end
+end

data/lib/googlemaps/services/directions.rb

@@ -0,0 +1,119 @@
+require "googlemaps/services/util"
+
+module GoogleMaps
+  module Services
+    $TRAVEL_MODES = ["driving", "walking", "bicycling", "transit"]
+
+    # Performs requests to the Google Maps Directions API.
+    #
+    # @example
+    #   directions = GoogleMaps::Services::Directions.new(client)
+    #   result = directions.query(origin: "Brussels", destination: {:lat => 52.520645, :lng => 13.409779})
+    class Directions
+      # @return [Symbol] The HTTP client.
+      attr_accessor :client
+
+      def initialize(client)
+        self.client = client
+      end
+
+      # Get directions between an origin point and a destination point.
+      #
+      # @param [String, Hash] origin The address or lat/lng hash value from which to calculate directions
+      # @param [String, Hash] destination The address or lat/lng value from which to calculate directions
+      # @param [String] mode The mode of transport to use when calculating directions. One of "driving",
+      #                       "walking", "bicycling" or "transit".
+      # @param [Array] waypoints Specifies an array of waypoints. Waypoints alter a route by routing it through
+      #                          the specified location(s). A location can be a String or a lat/lng hash.
+      # @param [TrueClass, FalseClass] alternatives If true, more than one route may be returned in the response.
+      # @param [Array] avoid Indicates that the calculated route(s) should avoid the indicated featues.
+      # @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, Time] departure_time Specifies the desired time of departure.
+      # @param [Integer, Time] arrival_time Specifies the desired time of arrival for transit directions.
+      #                                     Note: you cannot specify both departure_time and arrival_time.
+      # @param [TrueClass, FalseClass] optimize_waypoints optimize the provided route by rearranging the waypoints in a more efficient order.
+      # @param [Array] 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".
+      # @param [String] traffic_model Specifies the predictive travel time model to use. Valid values are "best_guess" or "optimistic" or "pessimistic".
+      #                               The traffic_model parameter may only be specified for requests where the travel mode is driving, and where the
+      #                               request includes a departure_time.
+      #
+      # @return [Hash] Valid JSON or XML response.
+      def query(origin:, destination:, 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, traffic_model: nil)
+        params = {
+          "origin" => Convert.to_latlng(origin),
+          "destination" => Convert.to_latlng(destination)
+        }
+
+        if mode
+          if !$TRAVEL_MODES.include? mode
+            raise StandardError, "invalid travel mode."
+          end
+          params["mode"] = mode
+        end
+
+        if waypoints
+          waypoints = Convert.piped_location(waypoints)
+          if optimize_waypoints
+            waypoints = "optimize:true|" + waypoints
+          end
+          params["waypoints"] = waypoints
+        end
+
+        if alternatives
+          params["alternatives"] = true
+        end
+
+        if avoid
+          params["avoid"] = Convert.join_array("|", avoid)
+        end
+
+        if language
+          params["language"] = language
+        end
+
+        if units
+          params["units"] = units
+        end
+
+        if region
+          params["region"] = region
+        end
+
+        if departure_time
+          params["departure_time"] = Convert.unix_time(departure_time)
+        end
+
+        if arrival_time
+          params["arrival_time"] = Convert.unix_time(arrival_time)
+        end
+
+        if departure_time && arrival_time
+          raise StandardError, "should not specify both departure_time and arrival_time."
+        end
+
+        if transit_mode
+          params["transit_mode"] = Convert.join_array("|", transit_mode)
+        end
+
+        if transit_routing_preference
+          params["transit_routing_preference"] = transit_routing_preference
+        end
+
+        if traffic_model
+          params["traffic_model"] = traffic_model
+        end
+
+        self.client.get(url: "/maps/api/directions/json", params: params)["routes"]
+      end
+    end
+
+  end
+end

data/lib/googlemaps/services/distancematrix.rb

@@ -0,0 +1,98 @@
+require "googlemaps/services/util"
+
+module GoogleMaps
+  module Services
+
+    $AVOIDS = ["tolls", "highways", "ferries"]
+
+    # Performs requests to the Google Maps Distance Matrix API.
+    #
+    # @example
+    #   distancematrix = GoogleMaps::Services::DistanceMatrix(client)
+    #   result = distancematrix.query(origins: ["Brussels", "Ghent"], destinations: ["Bruges"])
+    class DistanceMatrix
+      # @return [Symbol] the HTTP client.
+      attr_accessor :client
+
+      def initialize(client)
+        self.client = client
+      end
+
+      # Gets travel distance and time for a matrix of origins and destinations.
+      #
+      # @param [Array] origins One or more locations and/or lat/lng 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 lat/lng coordinate to calculate directions.
+      # @param [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 lat/lng 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, Time, Date] departure_time Specifies the desired time of departure.
+      # @param [Integer, Time, Date] arrival_time Specifies the desired time of arrival for transit directions. Note: you can't specify both departure_time and arrival_time.
+      # @param [Array] transit_mode Specifies one or more preferred modes of transit. his 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".
+      # @param [String] traffic_model Specifies the predictive travel time model to use. Valid values are "best_guess" or "optimistic" or "pessimistic".
+      #                               The traffic_model parameter may only be specified for requests where the travel mode is driving, and where the request includes a departure_time.
+      #
+      # @return [Hash] Matrix of distances.
+      def query(origins:, destinations:, mode: nil, language: nil, avoid: nil,
+                units: nil, departure_time: nil, arrival_time: nil, transit_mode: nil,
+                transit_routing_preference: nil, traffic_model: nil)
+        params = {
+          "origins" => Convert.piped_location(origins),
+          "destinations" => Convert.piped_location(destinations)
+        }
+
+        if mode
+          if !$TRAVEL_MODES.include? mode
+            raise StandardError, "Invalid travel mode."
+          end
+          params["mode"] = mode
+        end
+
+        if language
+          params["language"] = language
+        end
+
+        if avoid
+          if !$AVOIDS.include? avoid
+            raise StandardError, "Invalid route restriction."
+          end
+          params["avoid"] = avoid
+        end
+
+        if units
+          params["units"] = units
+        end
+
+        if departure_time
+          params["departure_time"] = Convert.unix_time(departure_time)
+        end
+
+        if arrival_time
+          params["arrival_time"] = Convert.unix_time(arrival_time)
+        end
+
+        if departure_time && arrival_time
+          raise StandardError, "Should not specify both departure_time and arrival_time."
+        end
+
+        if transit_mode
+          params["transit_mode"] = Convert.join_arrayt("|", transit_mode)
+        end
+
+        if transit_routing_preference
+          params["transit_routing_preference"] = transit_routing_preference
+        end
+
+        if traffic_model
+          params["traffic_model"] = traffic_model
+        end
+
+        self.client.get(url: "/maps/api/distancematrix/json", params: params)
+      end
+    end
+  end
+end