google_maps_service 0.3.0 → 0.4.0

data/lib/google_maps_service/convert.rb

@@ -23,8 +23,8 @@ module GoogleMapsService
     #
     # Accepts various representations:
     #
-    # 1. Hash with two entries - +lat+ and +lng+
-    # 2. Array or list - e.g. +[-33, 151]+
+    # 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.
     #
@@ -136,101 +136,41 @@ module GoogleMapsService
       raise ArgumentError, "Expected a bounds (southwest/northeast) Hash, but got #{arg.class}"
     end
 
-    # Converts an array of waypoints (path) to the format expected by the Google Maps
-    # server.
+    # 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] waypoints Path.
+    # @param [Array, String, Hash] waypoint 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]
+    def waypoint(waypoint)
+      if waypoint.kind_of?(String)
+        return waypoint
       end
-
-      waypoints = as_list(waypoints)
-      return join_list('|', waypoints.map { |k| k.kind_of?(String) ? k : latlng(k) })
+      return GoogleMapsService::Convert.latlng(waypoint)
     end
 
-    # 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
-    #
-    # @param [String] polyline An encoded polyline
+    # Converts an array of waypoints (path) to the format expected by the Google Maps
+    # server.
     #
-    # @return [Array] Array of hash with lat/lng keys
-    def decode_polyline(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.
+    # Accept two representation of waypoint:
     #
-    # See the developer docs for a detailed description of this encoding:
-    # https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+    # 1. String: Name of place or comma-separated lat/lon pair.
+    # 2. Hash/Array: Lat/lon pair.
     #
-    # @param [Array<Hash>, Array<Array>] points A list of lat/lng pairs.
+    # @param [Array, String, Hash] waypoints Path.
     #
     # @return [String]
-    def encode_polyline(points)
-      last_lat = last_lng = 0
-      result = ""
-
-      points.each do |point|
-        ll = 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
+    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
 
-      result
+      waypoints = as_list(waypoints)
+      return join_list('|', waypoints.map { |k| waypoint(k) })
     end
-
   end
 end

data/lib/google_maps_service/errors.rb

@@ -1,27 +1,36 @@
 module GoogleMapsService
+  # Specific Google Maps Service error
   module Error
     # Base error, capable of wrapping another
     class BaseError < StandardError
+      # HTTP response object
+      # @return [Hurley::Response]
       attr_reader :response
 
-      def initialize(response)
+      def initialize(response = nil)
         @response = response
       end
     end
 
-    # An exception that is raised if a redirect is required
+    # The response redirects to another URL.
     class RedirectError < BaseError
     end
 
     # A 4xx class HTTP error occurred.
+    # The request is invalid and should not be retried without modification.
     class ClientError < BaseError
     end
 
     # A 5xx class HTTP error occurred.
+    # An error occurred on the server and the request can be retried.
     class ServerError < BaseError
     end
 
-    # An API error occured.
+    # An unknown error occured.
+    class UnknownError < BaseError
+    end
+
+    # General Google Maps Web Service API error occured.
     class ApiError < BaseError
     end
 
@@ -29,7 +38,7 @@ module GoogleMapsService
     class InvalidRequestError < ApiError
     end
 
-    # Over quota.
+    # The quota for the credential is over limit.
     class RateLimitError < ApiError
     end
 

data/lib/google_maps_service/polyline.rb

@@ -0,0 +1,90 @@
+require 'google_maps_service/convert'
+
+module GoogleMapsService
+
+  # 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 = GoogleMapsService::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 = GoogleMapsService::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

data/lib/google_maps_service/url.rb

@@ -0,0 +1,64 @@
+require 'base64'
+require 'uri'
+
+module GoogleMapsService
+
+  # Helper for handling URL.
+  module Url
+    module_function
+
+    # Returns a base64-encoded HMAC-SHA1 signature of a given string.
+    #
+    # @param [String] secret The key used for the signature, base64 encoded.
+    # @param [String] payload The payload to sign.
+    #
+    # @return [String] Base64-encoded HMAC-SHA1 signature
+    def sign_hmac(secret, payload)
+      secret = secret.encode('ASCII')
+      payload = payload.encode('ASCII')
+
+      # Decode the private key
+      raw_key = Base64.urlsafe_decode64(secret)
+
+      # Create a signature using the private key and the URL
+      digest = OpenSSL::Digest.new('sha1')
+      raw_signature = OpenSSL::HMAC.digest(digest, raw_key, payload)
+
+      # Encode the signature into base64 for url use form.
+      signature =  Base64.urlsafe_encode64(raw_signature)
+      return signature
+    end
+
+    # URL encodes the parameters.
+    # @param [Hash, Array<Array>] params The parameters
+    # @return [String]
+    def urlencode_params(params)
+      unquote_unreserved(URI.encode_www_form(params))
+    end
+
+    # Un-escape any percent-escape sequences in a URI that are unreserved
+    # characters. This leaves all reserved, illegal and non-ASCII bytes encoded.
+    #
+    # @param [String] uri
+    #
+    # @return [String]
+    def unquote_unreserved(uri)
+      parts = uri.split('%')
+
+      (1..parts.length-1).each do |i|
+        h = parts[i][0..1]
+
+        if h =~ /^([\h]{2})(.*)/ and c = $1.to_i(16).chr and UNRESERVED_SET.include?(c)
+          parts[i] = c + $2
+        else
+          parts[i] = '%' + parts[i]
+        end
+      end
+
+      parts.join
+    end
+
+    # The unreserved URI characters (RFC 3986)
+    UNRESERVED_SET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~"
+  end
+end

data/lib/google_maps_service/validator.rb

@@ -1,9 +1,18 @@
 require_relative './convert'
 
 module GoogleMapsService
+
+  # Validate value that is accepted by Google Maps.
   module Validator
     module_function
 
+    # Validate travel mode. The valid value of travel mode are `driving`, `walking`, `bicycling` or `transit`.
+    #
+    # @param [String, Symbol] mode Travel mode to be validated.
+    #
+    # @raise ArgumentError The travel mode is invalid.
+    #
+    # @return [String] Valid travel mode.
     def travel_mode(mode)
       # NOTE(broady): the mode parameter is not validated by the Maps API
       # server. Check here to prevent silent failures.
@@ -13,6 +22,13 @@ module GoogleMapsService
       mode
     end
 
+    # Validate route restriction. The valid value of route restriction are `tolls`, `highways` or `ferries`.
+    #
+    # @param [String, Symbol] avoid Route restriction to be validated.
+    #
+    # @raise ArgumentError The route restriction is invalid.
+    #
+    # @return [String] Valid route restriction.
     def avoid(avoid)
       unless [:tolls, :highways, :ferries].include?(avoid.to_sym)
         raise ArgumentError, 'Invalid route restriction.'

data/lib/google_maps_service/version.rb

@@ -1,3 +1,23 @@
 module GoogleMapsService
-  VERSION = '0.3.0'
+  # GoogleMapsService gem version
+  VERSION = '0.4.0'
+
+  # Current operating system
+  # @private
+  OS_VERSION = begin
+    if RUBY_PLATFORM =~ /mswin|win32|mingw|bccwin|cygwin/
+      `ver`.sub(/\s*\[Version\s*/, '/').sub(']', '').strip
+    elsif RUBY_PLATFORM =~ /darwin/i
+      "Mac OS X/#{`sw_vers -productVersion`}"
+    elsif RUBY_PLATFORM == 'java'
+      require 'java'
+      name = java.lang.System.getProperty('os.name')
+      version = java.lang.System.getProperty('os.version')
+      "#{name}/#{version}"
+    else
+      `uname -sr`.sub(' ', '/')
+    end
+  rescue
+    RUBY_PLATFORM
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google_maps_service
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Edward Samuel Pasaribu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-18 00:00:00.000000000 Z
+date: 2015-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -59,61 +59,61 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 2.0.2
 - !ruby/object:Gem::Dependency
-  name: ruby-hmac
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
-  type: :runtime
+        version: '1.7'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.4.0
+        version: '1.7'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 0.8.7.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 0.8.7.6
 - !ruby/object:Gem::Dependency
-  name: yard
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.7.6
+        version: '3.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.8.7.6
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -188,24 +188,27 @@ files:
 - ".ruby-gemset"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
-- bin/console
-- bin/setup
 - google_maps_service.gemspec
 - lib/google_maps_service.rb
+- lib/google_maps_service/apis.rb
+- lib/google_maps_service/apis/directions.rb
+- lib/google_maps_service/apis/distance_matrix.rb
+- lib/google_maps_service/apis/elevation.rb
+- lib/google_maps_service/apis/geocoding.rb
+- lib/google_maps_service/apis/roads.rb
+- lib/google_maps_service/apis/time_zone.rb
 - lib/google_maps_service/client.rb
 - lib/google_maps_service/convert.rb
-- lib/google_maps_service/directions.rb
-- lib/google_maps_service/distance_matrix.rb
-- lib/google_maps_service/elevation.rb
 - lib/google_maps_service/errors.rb
-- lib/google_maps_service/geocoding.rb
-- lib/google_maps_service/roads.rb
-- lib/google_maps_service/time_zone.rb
+- lib/google_maps_service/polyline.rb
+- lib/google_maps_service/url.rb
 - lib/google_maps_service/validator.rb
 - lib/google_maps_service/version.rb
 homepage: https://github.com/edwardsamuel/google-maps-services-ruby
@@ -220,7 +223,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -231,6 +234,6 @@ rubyforge_project:
 rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
-summary: Ruby client library (unofficial) for Google Maps API Web Services
+summary: Ruby gem for Google Maps Web Service APIs
 test_files: []
 has_rdoc: yard