google_maps_apis 1.0.0

data/lib/google_maps_apis/client.rb

@@ -0,0 +1,294 @@
+require 'faraday'
+#require 'faraday/retry'
+require 'multi_json'
+require 'thread'
+
+require 'google_maps_apis/errors'
+require 'google_maps_apis/convert'
+require 'google_maps_apis/url'
+require 'google_maps_apis/services/directions'
+require 'google_maps_apis/services/distance_matrix'
+require 'google_maps_apis/services/elevation'
+require 'google_maps_apis/services/geocoding'
+require 'google_maps_apis/services/roads'
+require 'google_maps_apis/services/time_zone'
+require 'google_maps_apis/services/places'
+
+module GoogleMapsApis
+
+  # Core client functionality, common across all API requests (including performing
+  # HTTP requests).
+  class Client
+    # Default Google Maps Web Service base endpoints
+    DEFAULT_BASE_URL = 'https://maps.googleapis.com'
+
+    # Errors those could be retriable.
+    RETRIABLE_ERRORS = [GoogleMapsApis::Error::ServerError, GoogleMapsApis::Error::RateLimitError]
+
+    include GoogleMapsApis::Services::Directions
+    include GoogleMapsApis::Services::DistanceMatrix
+    include GoogleMapsApis::Services::Elevation
+    include GoogleMapsApis::Services::Geocoding
+    include GoogleMapsApis::Services::Roads
+    include GoogleMapsApis::Services::TimeZone
+    include GoogleMapsApis::Services::Places
+
+    # Secret key for accessing Google Maps Web Service.
+    # Can be obtained at https://developers.google.com/maps/documentation/geocoding/get-api-key#key.
+    # @return [String]
+    attr_accessor :key
+
+    # Client id for using Maps API for Work services.
+    # @return [String]
+    attr_accessor :client_id
+
+    # Client secret for using Maps API for Work services.
+    # @return [String]
+    attr_accessor :client_secret
+
+    # Timeout across multiple retriable requests, in seconds.
+    # @return [Integer]
+    attr_accessor :retry_timeout
+
+    # Number of queries per second permitted.
+    # If the rate limit is reached, the client will sleep for
+    # the appropriate amount of time before it runs the current query.
+    # @return [Integer]
+    attr_reader :queries_per_second
+
+    # Construct Google Maps Web Service API client.
+    #
+    # You can configure `Hurley::Client` through `request_options` and `ssl_options` parameters.
+    # You can also directly get the `Hurley::Client` object via {#client} method.
+    #
+    # @example Setup API keys
+    #   gmaps = GoogleMapsApis::Client.new(key: 'Add your key here')
+    #
+    # @example Setup client IDs
+    #   gmaps = GoogleMapsApis::Client.new(
+    #       client_id: 'Add your client id here',
+    #       client_secret: 'Add your client secret here'
+    #   )
+    #
+    # @example Setup time out and QPS limit
+    #   gmaps = GoogleMapsApis::Client.new(
+    #       key: 'Add your key here',
+    #       retry_timeout: 20,
+    #       queries_per_second: 10
+    #   )
+    #
+    # @example Request behind proxy
+    #   request_options = Hurley::RequestOptions.new
+    #   request_options.proxy = Hurley::Url.parse 'http://user:password@proxy.example.com:3128'
+    #
+    #   gmaps = GoogleMapsApis::Client.new(
+    #       key: 'Add your key here',
+    #       request_options: request_options
+    #   )
+    #
+    # @example Using Excon and Http Cache
+    #  require 'hurley-excon'       # https://github.com/lostisland/hurley-excon
+    #  require 'hurley/http_cache'  # https://github.com/plataformatec/hurley-http-cache
+    #
+    #  gmaps = GoogleMapsApis::Client.new(
+    #      key: 'Add your key here',
+    #      connection: Hurley::HttpCache.new(HurleyExcon::Connection.new)
+    #  )
+    #
+    # @option options [String] :key Secret key for accessing Google Maps Web Service.
+    #   Can be obtained at https://developers.google.com/maps/documentation/geocoding/get-api-key#key.
+    # @option options [String] :client_id Client id for using Maps API for Work services.
+    # @option options [String] :client_secret Client secret for using Maps API for Work services.
+    # @option options [Integer] :retry_timeout Timeout across multiple retriable requests, in seconds.
+    # @option options [Integer] :queries_per_second Number of queries per second permitted.
+    #
+    # @option options [Hurley::RequestOptions] :request_options HTTP client request options.
+    #     See https://github.com/lostisland/hurley/blob/master/lib/hurley/options.rb.
+    # @option options [Hurley::SslOptions] :ssl_options HTTP client SSL options.
+    #     See https://github.com/lostisland/hurley/blob/master/lib/hurley/options.rb.
+    # @option options [Object] :connection HTTP client connection.
+    #     By default, the default Hurley's HTTP client connection (Net::Http) will be used.
+    #     See https://github.com/lostisland/hurley/blob/master/README.md#connections.
+    def initialize(**options)
+      [:key, :client_id, :client_secret,
+          :retry_timeout, :queries_per_second,
+          :request_options, :ssl_options, :connection].each do |key|
+        self.instance_variable_set("@#{key}".to_sym, options[key] || GoogleMapsApis.instance_variable_get("@#{key}"))
+      end
+
+      initialize_query_tickets
+    end
+
+    # Get the current HTTP client.
+    # @return [Faraday::Client]
+    def client
+      @client ||= new_client
+    end
+
+    protected
+
+    # Initialize QPS queue. QPS queue is a "tickets" for calling API
+    def initialize_query_tickets
+      if @queries_per_second
+        @qps_queue = SizedQueue.new @queries_per_second
+        @queries_per_second.times do
+          @qps_queue << 0
+        end
+      end
+    end
+
+    # Create a new HTTP client.
+    # @return [Faraday::Connection]
+    def new_client
+      client = Faraday.new(DEFAULT_BASE_URL)
+      #client.request_options.query_class = Hurley::Query::Flat
+      #client.request_options.redirection_limit = 0
+      client.headers[:user_agent] = user_agent
+
+      #client.connection = @connection if @connection
+      #@request_options.each_pair {|key, value| client.request_options[key] = value } if @request_options
+      #@ssl_options.each_pair {|key, value| client.ssl_options[key] = value } if @ssl_options
+
+      client
+    end
+
+    # Build the user agent header
+    # @return [String]
+    def user_agent
+      sprintf('google-maps-services-ruby/%s %s',
+              GoogleMapsApis::VERSION,
+              GoogleMapsApis::OS_VERSION)
+    end
+
+    # Make API call.
+    #
+    # @param [String] path Url path.
+    # @param [String] params Request parameters.
+    # @param [String] base_url Base Google Maps Web Service API endpoint url.
+    # @param [Boolean] accepts_client_id Sign the request using API {#keys} instead of {#client_id}.
+    # @param [Method] custom_response_decoder Custom method to decode raw API response.
+    #
+    # @return [Object] Decoded response body.
+    def get(path, params, base_url: DEFAULT_BASE_URL, accepts_client_id: true, custom_response_decoder: nil)
+      url = base_url + generate_auth_url(path, params, accepts_client_id)
+
+      #Retriable.retriable timeout: @retry_timeout, on: RETRIABLE_ERRORS do |try|
+        #begin
+          #request_query_ticket
+          response = client.get url
+        #ensure
+          #release_query_ticket
+        #end
+
+        return custom_response_decoder.call(response) if custom_response_decoder
+        decode_response_body(response)
+      #end
+    end
+
+    # Get/wait the request "ticket" if QPS is configured.
+    # Check for previous request time, it must be more than a second ago before calling new request.
+    #
+    # @return [void]
+    def request_query_ticket
+      if @qps_queue
+        elapsed_since_earliest = Time.now - @qps_queue.pop
+        sleep(1 - elapsed_since_earliest) if elapsed_since_earliest.to_f < 1
+      end
+    end
+
+    # Release request "ticket".
+    #
+    # @return [void]
+    def release_query_ticket
+      @qps_queue << Time.now if @qps_queue
+    end
+
+    # Returns the path and query string portion of the request URL,
+    # first adding any necessary parameters.
+    #
+    # @param [String] path The path portion of the URL.
+    # @param [Hash] params URL parameters.
+    # @param [Boolean] accepts_client_id Sign the request using API {#keys} instead of {#client_id}.
+    #
+    # @return [String]
+    def generate_auth_url(path, params, accepts_client_id)
+      # Deterministic ordering through sorting by key.
+      # Useful for tests, and in the future, any caching.
+      if params.kind_of?(Hash)
+        params = params.sort
+      else
+        params = params.dup
+      end
+
+      if accepts_client_id and @client_id and @client_secret
+        params << ["client", @client_id]
+
+        path = [path, GoogleMapsApis::Url.urlencode_params(params)].join("?")
+        sig = GoogleMapsApis::Url.sign_hmac(@client_secret, path)
+        return path + "&signature=" + sig
+      end
+
+      if @key
+        params << ["key", @key]
+        return path + "?" + GoogleMapsApis::Url.urlencode_params(params)
+      end
+
+      raise ArgumentError, "Must provide API key for this API. It does not accept enterprise credentials."
+    end
+
+    # Extract and parse body response as hash. Throw an error if there is something wrong with the response.
+    #
+    # @param [Faraday::Response] response Web API response.
+    #
+    # @return [Hash] Response body as hash. The hash key will be symbolized.
+    def decode_response_body(response)
+      check_response_status(response)
+      body = MultiJson.load(response.body, :symbolize_keys => true)
+      check_body_error(response, body)
+      body
+    end
+
+    # Check HTTP response status code. Raise error if the status is not 2xx.
+    #
+    # @param [Faraday::Response] response Web API response.
+    def check_response_status(response)
+      case response.status
+      when 200..300
+        # Do-nothing
+      when 301...308
+        raise GoogleMapsApis::Error::RedirectError.new(response),
+          (GoogleMapsApis::Error::RedirectError::ERRORS_3XX[response.status.to_s] + sprintf('Redirect to %s', response.headers[:location]))
+      when 400...409,415,422,429
+        raise GoogleMapsApis::Error::ClientError.new(response),
+          GoogleMapsApis::Error::ClientError::ERRORS_4XX[response.status.to_s]
+      when 410...500
+        raise GoogleMapsApis::Error::ClientError.new(response), 'Invalid request'
+      when 500..600
+        raise GoogleMapsApis::Error::ServerError.new(response), 'Server error'
+      end
+    end
+
+    # Check response body for error status.
+    #
+    # @param [Faraday::Response] response Response object.
+    # @param [Hash] body Response body.
+    #
+    # @return [void]
+    def check_body_error(response, body)
+      case body[:status]
+      when 'OK', 'ZERO_RESULTS'
+        # Do-nothing
+      when 'OVER_QUERY_LIMIT'
+        raise GoogleMapsApis::Error::RateLimitError.new(response), body[:error_message]
+      when 'REQUEST_DENIED'
+        raise GoogleMapsApis::Error::RequestDeniedError.new(response), body[:error_message]
+      when 'INVALID_REQUEST'
+        raise GoogleMapsApis::Error::InvalidRequestError.new(response), body[:error_message]
+      when 'NOT_FOUND'
+        raise GoogleMapsApis::Error::NotFoundError.new(response), (body[:error_message] || 'ADDRESS NOT FOUND')
+      else
+        raise GoogleMapsApis::Error::ApiError.new(response), body[:error_message]
+      end
+    end
+  end
+end

data/lib/google_maps_apis/convert.rb

@@ -0,0 +1,176 @@
+module GoogleMapsApis
+
+  # Converts Ruby types to string representations suitable for Maps API server.
+  module Convert
+    module_function
+
+    # Converts a lat/lon pair to a comma-separated string.
+    #
+    # @example
+    #   >> GoogleMapsApis::Convert.latlng({"lat": -33.8674869, "lng": 151.2069902})
+    #   => "-33.867487,151.206990"
+    #
+    # @param [Hash, Array] arg The lat/lon hash or array pair.
+    #
+    # @return [String] Comma-separated lat/lng.
+    #
+    # @raise [ArgumentError] When argument is not lat/lng hash or array.
+    def latlng(arg)
+      return "%f,%f" % normalize_latlng(arg)
+    end
+
+    # Take the various lat/lng representations and return a tuple.
+    #
+    # Accepts various representations:
+    #
+    # 1. Hash with two entries - `lat` and `lng`
+    # 2. Array or list - e.g. `[-33, 151]`
+    #
+    # @param [Hash, Array] arg The lat/lon hash or array pair.
+    #
+    # @return [Array] Pair of lat and lng array.
+    def normalize_latlng(arg)
+      if arg.kind_of?(Hash)
+        lat = arg[:lat] || arg[:latitude] || arg["lat"] || arg["latitude"]
+        lng = arg[:lng] || arg[:longitude] || arg["lng"] || arg["longitude"]
+        return lat, lng
+      elsif arg.kind_of?(Array)
+        return arg[0], arg[1]
+      end
+
+      raise ArgumentError, "Expected a lat/lng Hash or Array, but got #{arg.class}"
+    end
+
+    # If arg is list-like, then joins it with sep.
+    #
+    # @param [String] sep Separator string.
+    # @param [Array, String] arg Value to coerce into a list.
+    #
+    # @return [String]
+    def join_list(sep, arg)
+      return as_list(arg).join(sep)
+    end
+
+    # Coerces arg into a list. If arg is already list-like, returns arg.
+    # Otherwise, returns a one-element list containing arg.
+    #
+    # @param [Object] arg
+    #
+    # @return [Array]
+    def as_list(arg)
+      if arg.kind_of?(Array)
+          return arg
+      end
+      return [arg]
+    end
+
+
+    # Converts the value into a unix time (seconds since unix epoch).
+    #
+    # @example
+    #   >> GoogleMapsApis::Convert.time(datetime.now())
+    #   => "1409810596"
+    #
+    # @param [Time, Date, DateTime, Integer] arg The time.
+    #
+    # @return [String] String representation of epoch time
+    def time(arg)
+      if arg.kind_of?(DateTime)
+        arg = arg.to_time
+      end
+      return arg.to_i.to_s
+    end
+
+    # Converts a dict of components to the format expected by the Google Maps
+    # server.
+    #
+    # @example
+    #   >> GoogleMapsApis::Convert.components({"country": "US", "postal_code": "94043"})
+    #   => "country:US|postal_code:94043"
+    #
+    # @param [Hash] arg The component filter.
+    #
+    # @return [String]
+    def components(arg)
+      if arg.kind_of?(Hash)
+        arg = arg.sort.map { |k, v| "#{k}:#{v}" }
+        return arg.join("|")
+      end
+
+      raise ArgumentError, "Expected a Hash for components, but got #{arg.class}"
+    end
+
+    # Converts a lat/lon bounds to a comma- and pipe-separated string.
+    #
+    # Accepts two representations:
+    #
+    # 1. String: pipe-separated pair of comma-separated lat/lon pairs.
+    # 2. Hash with two entries - "southwest" and "northeast". See {.latlng}
+    # for information on how these can be represented.
+    #
+    # For example:
+    #
+    #   >> sydney_bounds = {
+    #   ?>   "northeast": {
+    #   ?>     "lat": -33.4245981,
+    #   ?>     "lng": 151.3426361
+    #   ?>   },
+    #   ?>   "southwest": {
+    #   ?>     "lat": -34.1692489,
+    #   ?>     "lng": 150.502229
+    #   ?>   }
+    #   ?> }
+    #   >> GoogleMapsApis::Convert.bounds(sydney_bounds)
+    #   => '-34.169249,150.502229|-33.424598,151.342636'
+    #
+    # @param [Hash] arg The bounds.
+    #
+    # @return [String]
+    def bounds(arg)
+      if arg.kind_of?(Hash)
+        southwest = arg[:southwest] || arg["southwest"]
+        northeast = arg[:northeast] || arg["northeast"]
+        return "#{latlng(southwest)}|#{latlng(northeast)}"
+      end
+
+      raise ArgumentError, "Expected a bounds (southwest/northeast) Hash, but got #{arg.class}"
+    end
+
+    # Converts a waypoints to the format expected by the Google Maps server.
+    #
+    # Accept two representation of waypoint:
+    #
+    # 1. String: Name of place or comma-separated lat/lon pair.
+    # 2. Hash/Array: Lat/lon pair.
+    #
+    # @param [Array, String, Hash] waypoint Path.
+    #
+    # @return [String]
+    def waypoint(waypoint)
+      if waypoint.kind_of?(String)
+        return waypoint
+      end
+      return GoogleMapsApis::Convert.latlng(waypoint)
+    end
+
+    # Converts an array of waypoints (path) to the format expected by the Google Maps
+    # server.
+    #
+    # Accept two representation of waypoint:
+    #
+    # 1. String: Name of place or comma-separated lat/lon pair.
+    # 2. Hash/Array: Lat/lon pair.
+    #
+    # @param [Array, String, Hash] waypoints Path.
+    #
+    # @return [String]
+    def waypoints(waypoints)
+      if waypoints.kind_of?(Array) and waypoints.length == 2 and waypoints[0].kind_of?(Numeric) and waypoints[1].kind_of?(Numeric)
+        waypoints = [waypoints]
+      end
+
+      waypoints = as_list(waypoints)
+      return join_list('|', waypoints.map { |k| waypoint(k) })
+    end
+  end
+end

data/lib/google_maps_apis/errors.rb

@@ -0,0 +1,82 @@
+module GoogleMapsApis
+  # Specific Google Maps Service error
+  module Error
+    # Base error, capable of wrapping another
+    class BaseError < StandardError
+      # HTTP response object
+      # @return [Faraday::Response]
+      attr_reader :response
+
+      # Initialize error
+      #
+      # @param [Faraday::Response] response HTTP response.
+      def initialize(response = nil)
+        @response = response
+      end
+    end
+
+    # The response redirects to another URL.
+    class RedirectError < BaseError
+      ERRORS_3XX = {
+        '300' => 'Multiple Choices',
+        '301' => 'Moved Permanently',
+        '302' => 'Found',
+        '303' => 'See Other',
+        '304' => 'Not Modified',
+        '305' => 'Use Proxy',
+        '306' => 'Switch Proxy',
+        '307' => 'Temporary Redirect',
+        '308' => 'Permanent Redirect'
+      }
+    end
+
+    # A 4xx class HTTP error occurred.
+    # The request is invalid and should not be retried without modification.
+    class ClientError < BaseError
+      ERRORS_4XX = {
+        '400' => 'Bad Request',
+        '401' => 'Unauthorized',
+        '402' => 'Payment Required',
+        '403' => 'Forbidden',
+        '404' => 'Not Found',
+        '405' => 'Method Not Allowed',
+        '406' => 'Not Acceptable',
+        '407' => 'Proxy Authentication Required',
+        '408' => 'Request Timeout',
+        '409' => 'Conflict',
+        '415' => 'Unsupported Media Type',
+        '422' => 'Unprocessable Entity',
+        '429' => 'Too Many Requests'
+      }
+    end
+
+    # A 5xx class HTTP error occurred.
+    # An error occurred on the server and the request can be retried.
+    class ServerError < BaseError
+    end
+
+    # An unknown error occured.
+    class UnknownError < BaseError
+    end
+
+    # General Google Maps Web Service API error occured.
+    class ApiError < BaseError
+    end
+
+    # Requiered query is missing
+    class InvalidRequestError < ApiError
+    end
+
+    # The quota for the credential is over limit.
+    class RateLimitError < ApiError
+    end
+
+    # An unathorized error occurred. It might be caused by invalid key/secret or invalid access.
+    class RequestDeniedError < ApiError
+    end
+
+    # When an Address is not found. i.e. An address string could not be geocoded
+    class NotFoundError < ApiError
+    end
+  end
+end

data/lib/google_maps_apis/polyline.rb

@@ -0,0 +1,90 @@
+require 'google_maps_apis/convert'
+
+module GoogleMapsApis
+
+  # Encoder/decoder for [Google Encoded Polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
+  module Polyline
+    module_function
+
+    # Decodes a Polyline string into a list of lat/lng hash.
+    #
+    # See the developer docs for a detailed description of this encoding:
+    # https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+    #
+    # @example
+    #   encoded_path = '_p~iF~ps|U_ulLnnqC_mqNvxq`@'
+    #   path = GoogleMapsApis::Polyline.decode(encoded_path)
+    #   #=> [{:lat=>38.5, :lng=>-120.2}, {:lat=>40.7, :lng=>-120.95}, {:lat=>43.252, :lng=>-126.45300000000002}]
+    #
+    # @param [String] polyline An encoded polyline
+    #
+    # @return [Array] Array of hash with lat/lng keys
+    def decode(polyline)
+      points = []
+      index = lat = lng = 0
+
+      while index < polyline.length
+        result = 1
+        shift = 0
+        while true
+          b = polyline[index].ord - 63 - 1
+          index += 1
+          result += b << shift
+          shift += 5
+          break if b < 0x1f
+        end
+        lat += (result & 1) != 0 ? (~result >> 1) : (result >> 1)
+
+        result = 1
+        shift = 0
+        while true
+          b = polyline[index].ord - 63 - 1
+          index += 1
+          result += b << shift
+          shift += 5
+          break if b < 0x1f
+        end
+        lng += (result & 1) != 0 ? ~(result >> 1) : (result >> 1)
+
+        points << {lat: lat * 1e-5, lng: lng * 1e-5}
+      end
+
+      points
+    end
+
+    # Encodes a list of points into a polyline string.
+    #
+    # See the developer docs for a detailed description of this encoding:
+    # https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+    #
+    # @param [Array<Hash>, Array<Array>] points A list of lat/lng pairs.
+    #
+    # @return [String]
+    def encode(points)
+      last_lat = last_lng = 0
+      result = ""
+
+      points.each do |point|
+        ll = GoogleMapsApis::Convert.normalize_latlng(point)
+        lat = (ll[0] * 1e5).round.to_i
+        lng = (ll[1] * 1e5).round.to_i
+        d_lat = lat - last_lat
+        d_lng = lng - last_lng
+
+        [d_lat, d_lng].each do |v|
+          v = (v < 0) ? ~(v << 1) : (v << 1)
+          while v >= 0x20
+            result += ((0x20 | (v & 0x1f)) + 63).chr
+            v >>= 5
+          end
+          result += (v + 63).chr
+        end
+
+        last_lat = lat
+        last_lng = lng
+      end
+
+      result
+    end
+  end
+end