google_maps_service_ruby 0.6.0

data/lib/google_maps_service/apis/geocoding.rb

@@ -0,0 +1,82 @@
+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
+
+      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
+
+      get("/maps/api/geocode/json", params)[:results]
+    end
+  end
+end

data/lib/google_maps_service/apis/roads.rb

@@ -0,0 +1,183 @@
+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
+
+      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] }
+
+      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
+      }
+
+      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
+      }
+
+      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.code == "200"
+          check_response_status_code(response)
+        end
+        raise GoogleMapsService::Error::ApiError.new(response), "Received a malformed response."
+      end
+
+      check_roads_body_error(response, body)
+
+      unless response.code == "200"
+        raise GoogleMapsService::Error::ApiError.new(response)
+      end
+      body
+    end
+
+    # Check response body for error status.
+    #
+    # @param [Net::HTTPResponse] 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,39 @@
+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
+
+      get("/maps/api/timezone/json", params)
+    end
+  end
+end

data/lib/google_maps_service/apis.rb

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

data/lib/google_maps_service/client.rb

@@ -0,0 +1,255 @@
+require "multi_json"
+require "net/http"
+require "retriable"
+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"
+
+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
+
+    # 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.
+    #
+    # @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
+    #   )
+    #
+    # @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.
+    def initialize(**options)
+      [:key, :client_id, :client_secret,
+        :retry_timeout, :queries_per_second].each do |key|
+        instance_variable_set("@#{key}".to_sym, options[key] || GoogleMapsService.instance_variable_get("@#{key}"))
+      end
+      [:request_options, :ssl_options, :connection].each do |key|
+        if options.has_key?(key)
+          raise "GoogleMapsService::Client.new no longer supports #{key}."
+        end
+      end
+
+      initialize_query_tickets
+    end
+
+    # Get the current HTTP client.
+    # @deprecated
+    def client
+      raise "GoogleMapsService::Client.client is no longer implemented."
+    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.
+    # @deprecated
+    def new_client
+      raise "GoogleMapsService::Client.new_client is no longer implemented."
+    end
+
+    # Build the user agent header
+    # @return [String]
+    def user_agent
+      @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 = URI(base_url + generate_auth_url(path, params, accepts_client_id))
+
+      Retriable.retriable timeout: @retry_timeout, on: RETRIABLE_ERRORS do |try|
+        begin
+          request_query_ticket
+          request = Net::HTTP::Get.new(url)
+          request["User-Agent"] = user_agent
+          response = Net::HTTP.start(url.hostname, url.port, use_ssl: url.scheme == "https") do |http|
+            http.request(request)
+          end
+        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.
+      params = if params.is_a?(Hash)
+        params.sort
+      else
+        params.dup
+      end
+
+      if accepts_client_id && @client_id && @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 [Net::HTTPResponse] response Web API response.
+    #
+    # @return [Hash] Response body as hash. The hash key will be symbolized.
+    def decode_response_body(response)
+      check_response_status_code(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 [Net::HTTPResponse] response Web API response.
+    def check_response_status_code(response)
+      case response.code.to_i
+      when 200..300
+        # Do-nothing
+      when 301, 302, 303, 307
+        raise GoogleMapsService::Error::RedirectError.new(response), sprintf("Redirect to %s", response.header[: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 [Net::HTTPResponse] 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]
+      else
+        raise GoogleMapsService::Error::ApiError.new(response), body[:error_message]
+      end
+    end
+  end
+end