google_map_services 0.1.0.0

data/lib/google_maps_service/apis/geocoding.rb

@@ -0,0 +1,85 @@
+require 'google_maps_service/convert'
+
+module GoogleMapsService::Apis
+
+  # 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.
+    #
+    # @example Geocode an address
+    #   results = client.geocode('Sydney')
+    #
+    # @example Geocode a component only
+    #   results = client.geocode(nil, components: {administrative_area: 'TX', country: 'US'})
+    #
+    # @example Geocode an address and component
+    #   results = client.geocode('Sydney', components: {administrative_area: 'TX', country: 'US'})
+    #
+    # @example Multiple parameters
+    #   results = client.geocode('Sydney',
+    #       components: {administrative_area: 'TX', country: 'US'},
+    #       bounds: {
+    #         northeast: {lat: 32.7183997, lng: -97.26864001970849},
+    #         southwest: {lat: 32.7052583, lng: -97.27133798029149}
+    #       },
+    #       region: 'us')
+    #
+    # @param [String] address The address to geocode. You must specify either this value and/or `components`.
+    # @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] Array of geocoding results.
+    def geocode(address, 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.
+    #
+    # @example Simple lat/lon pair
+    #   client.reverse_geocode({lat: 40.714224, lng: -73.961452})
+    #
+    # @example Multiple parameters
+    #   client.reverse_geocode([40.714224, -73.961452],
+    #       location_type: ['ROOFTOP', 'RANGE_INTERPOLATED'],
+    #       result_type: ['street_address', 'route'],
+    #       language: 'es')
+    #
+    # @param [Hash, Array] latlng The latitude/longitude value for which you wish to obtain
+    #                the closest, human-readable address.
+    # @param [String, Array<String>] location_type One or more location types to restrict results to.
+    # @param [String, Array<String>] result_type One or more address types to restrict results to.
+    # @param [String] language The language in which to return results.
+    #
+    # @return [Array] Array of reverse geocoding results.
+    def reverse_geocode(latlng, location_type: nil, result_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/apis/places.rb

@@ -0,0 +1,20 @@
+require 'google_maps_service/convert'
+
+module GoogleMapsService::Apis
+
+  # Performs requests to the Google Maps Geocoding API.
+  module Places
+    def places_autocomplete(input, components: nil, bounds: nil, types: nil, region: nil, language: nil)
+      params = {}
+
+      params[:input] = input
+      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
+      params[:types] = types if types
+
+      return get('/maps/api/place/autocomplete/json', params)[:predictions]
+    end
+  end
+end

data/lib/google_maps_service/apis/roads.rb

@@ -0,0 +1,187 @@
+require 'multi_json'
+
+module GoogleMapsService::Apis
+
+  # 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.
+    #
+    # @example Single point snap
+    #   results = client.snap_to_roads([40.714728, -73.998672])
+    #
+    # @example Multi points snap
+    #   path = [
+    #       [-33.8671, 151.20714],
+    #       [-33.86708, 151.20683000000002],
+    #       [-33.867070000000005, 151.20674000000002],
+    #       [-33.86703, 151.20625]
+    #   ]
+    #   results = client.snap_to_roads(path, interpolate: true)
+    #
+    # @param [Array] path The path to be snapped. Array of latitude/longitude pairs.
+    # @param [Boolean] 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.
+    #
+    # @return [Array] Array of snapped points.
+    def snap_to_roads(path, interpolate: false)
+      path = GoogleMapsService::Convert.waypoints(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.
+    #
+    # @example Multi places snap
+    #   place_ids = [
+    #     'ChIJ0wawjUCuEmsRgfqC5Wd9ARM',
+    #     'ChIJ6cs2kkCuEmsRUfqC5Wd9ARM'
+    #   ]
+    #   results = client.speed_limits(place_ids)
+    #
+    # @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] Array of speed limits.
+    def speed_limits(place_ids)
+      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.
+    #
+    # @example Multi points snap
+    #   path = [
+    #       [-33.8671, 151.20714],
+    #       [-33.86708, 151.20683000000002],
+    #       [-33.867070000000005, 151.20674000000002],
+    #       [-33.86703, 151.20625]
+    #   ]
+    #   results = client.snapped_speed_limits(path)
+    #
+    # @param [Hash, Array] path The path of points to be snapped. A list of (or single)
+    #         latitude/longitude tuples.
+    #
+    # @return [Hash] A hash with both a list of speed limits and a list of the snapped
+    #         points.
+    def snapped_speed_limits(path)
+      path = GoogleMapsService::Convert.waypoints(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
+
+    # Returns the nearest road segments for provided points.
+    # The points passed do not need to be part of a continuous path.
+    #
+    # @example Single point snap
+    #   results = client.nearest_roads([40.714728, -73.998672])
+    #
+    # @example Multi points snap
+    #   points = [
+    #       [-33.8671, 151.20714],
+    #       [-33.86708, 151.20683000000002],
+    #       [-33.867070000000005, 151.20674000000002],
+    #       [-33.86703, 151.20625]
+    #   ]
+    #   results = client.nearest_roads(points)
+    #
+    # @param [Array] points The points to be used for nearest road segment lookup. Array of latitude/longitude pairs
+    #                       which do not need to be a part of continuous part.
+    #                       Takes up to 100 independent coordinates, and returns the closest road segment for each point.
+    #
+    # @return [Array] Array of snapped points.
+
+    def nearest_roads(points)
+      points = GoogleMapsService::Convert.waypoints(points)
+
+      params = {
+        points: points
+      }
+
+      return get('/v1/nearestRoads', params,
+                 base_url: ROADS_BASE_URL,
+                 accepts_client_id: false,
+                 custom_response_decoder: method(:extract_roads_body))[:snappedPoints]
+    end
+
+
+
+    private
+      # 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 == 200
+            check_response_status(response)
+          end
+          raise GoogleMapsService::Error::ApiError.new(response), 'Received a malformed response.'
+        end
+
+        check_roads_body_error(response, body)
+
+        unless response.status == 200
+          raise GoogleMapsService::Error::ApiError.new(response)
+        end
+        return body
+      end
+
+      # Check response body for error status.
+      #
+      # @param [Faraday::Response] response Response object.
+      # @param [Hash] body Response body.
+      def check_roads_body_error(response, body)
+        error = body[:error]
+        return unless error
+
+        case error[:status]
+          when '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]
+          when 'PERMISSION_DENIED'
+            raise GoogleMapsService::Error::RequestDeniedError.new(response), error[:message]
+          when 'RESOURCE_EXHAUSTED'
+            raise GoogleMapsService::Error::RateLimitError.new(response), error[:message]
+          else
+            raise GoogleMapsService::Error::ApiError.new(response), error[:message]
+        end
+      end
+
+  end
+end

data/lib/google_maps_service/apis/time_zone.rb

@@ -0,0 +1,41 @@
+require 'date'
+
+module GoogleMapsService::Apis
+
+  # Performs requests to the Google Maps TimeZone API."""
+  module TimeZone
+
+    # Get time zone for a location on the earth, as well as that location's
+    # time offset from UTC.
+    #
+    # @example Current time zone
+    #   timezone = client.timezone([39.603481, -119.682251])
+    #
+    # @example Time zone at certain time
+    #   timezone = client.timezone([39.603481, -119.682251], timestamp: Time.at(1608))
+    #
+    # @param [Hash, Array] location The latitude/longitude value representing the location to
+    #     look up.
+    # @param [Integer, DateTime] timestamp Timestamp specifies the desired time as seconds since
+    #     midnight, January 1, 1970 UTC. The Time Zone API uses the timestamp to
+    #     determine whether or not Daylight Savings should be applied. Times
+    #     before 1970 can be expressed as negative values. Optional. Defaults to
+    #     `Time.now`.
+    # @param [String] language The language in which to return results.
+    #
+    # @return [Hash] Time zone object.
+    def timezone(location, timestamp: Time.now, language: nil)
+      location = GoogleMapsService::Convert.latlng(location)
+      timestamp = GoogleMapsService::Convert.time(timestamp)
+
+      params = {
+        location: location,
+        timestamp: timestamp
+      }
+
+      params[:language] = language if language
+
+      return get('/maps/api/timezone/json', params)
+    end
+  end
+end

data/lib/google_maps_service/apis.rb

@@ -0,0 +1,6 @@
+module GoogleMapsService
+
+  # Collections of Google Maps Web Services
+  module Apis
+  end
+end

data/lib/google_maps_service/client.rb

@@ -0,0 +1,292 @@
+require 'faraday'
+#require 'faraday/retry'
+require 'multi_json'
+require 'thread'
+
+require 'google_maps_service/errors'
+require 'google_maps_service/convert'
+require 'google_maps_service/url'
+require 'google_maps_service/apis/directions'
+require 'google_maps_service/apis/distance_matrix'
+require 'google_maps_service/apis/elevation'
+require 'google_maps_service/apis/geocoding'
+require 'google_maps_service/apis/roads'
+require 'google_maps_service/apis/time_zone'
+require 'google_maps_service/apis/places'
+
+module GoogleMapsService
+
+  # 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 = [GoogleMapsService::Error::ServerError, GoogleMapsService::Error::RateLimitError]
+
+    include GoogleMapsService::Apis::Directions
+    include GoogleMapsService::Apis::DistanceMatrix
+    include GoogleMapsService::Apis::Elevation
+    include GoogleMapsService::Apis::Geocoding
+    include GoogleMapsService::Apis::Roads
+    include GoogleMapsService::Apis::TimeZone
+    include GoogleMapsService::Apis::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 = GoogleMapsService::Client.new(key: 'Add your key here')
+    #
+    # @example Setup client IDs
+    #   gmaps = GoogleMapsService::Client.new(
+    #       client_id: 'Add your client id here',
+    #       client_secret: 'Add your client secret here'
+    #   )
+    #
+    # @example Setup time out and QPS limit
+    #   gmaps = GoogleMapsService::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 = GoogleMapsService::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 = GoogleMapsService::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] || GoogleMapsService.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',
+              GoogleMapsService::VERSION,
+              GoogleMapsService::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, GoogleMapsService::Url.urlencode_params(params)].join("?")
+        sig = GoogleMapsService::Url.sign_hmac(@client_secret, path)
+        return path + "&signature=" + sig
+      end
+
+      if @key
+        params << ["key", @key]
+        return path + "?" + GoogleMapsService::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, 302, 303, 307
+        raise GoogleMapsService::Error::RedirectError.new(response), sprintf('Redirect to %s', response.headers[:location])
+      when 401
+        raise GoogleMapsService::Error::ClientError.new(response), 'Unauthorized'
+      when 304, 400, 402...500
+        raise GoogleMapsService::Error::ClientError.new(response), 'Invalid request'
+      when 500..600
+        raise GoogleMapsService::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 GoogleMapsService::Error::RateLimitError.new(response), body[:error_message]
+      when 'REQUEST_DENIED'
+        raise GoogleMapsService::Error::RequestDeniedError.new(response), body[:error_message]
+      when 'INVALID_REQUEST'
+        raise GoogleMapsService::Error::InvalidRequestError.new(response), body[:error_message]
+      when 'NOT_FOUND'
+        raise GoogleMapsService::Error::NotFoundError.new(response), (body[:error_message] || 'ADDRESS NOT FOUND')
+      else
+        raise GoogleMapsService::Error::ApiError.new(response), body[:error_message]
+      end
+    end
+  end
+end