google_maps_service 0.3.0 → 0.4.0

data/google_maps_service.gemspec

@@ -9,9 +9,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Edward Samuel Pasaribu']
   spec.email         = ['edwardsamuel92@gmail.com']
 
-  spec.summary       = %q{Ruby client library (unofficial) for Google Maps API Web Services}
+  spec.summary       = %q{Ruby gem for Google Maps Web Service APIs }
   spec.homepage      = %q{https://github.com/edwardsamuel/google-maps-services-ruby}
   spec.license       = 'Apache-2.0'
+  spec.required_ruby_version = '>= 2.0.0'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.require_paths = ['lib']
@@ -20,10 +21,10 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'multi_json', '~> 1.11'
   spec.add_runtime_dependency 'hurley', '~> 0.1'
   spec.add_runtime_dependency 'retriable', '~> 2.0', '>= 2.0.2'
-  spec.add_runtime_dependency 'ruby-hmac', '~> 0.4.0'
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'yard', '~> 0.8.7.6'
+  spec.add_development_dependency 'redcarpet', '~> 3.3'
   spec.add_development_dependency 'rspec', '~> 3.3'
   spec.add_development_dependency 'simplecov', '~> 0.10.0'
   spec.add_development_dependency 'coveralls', '~> 0.8.2'

data/lib/google_maps_service.rb

@@ -1,6 +1,46 @@
+# Google Maps Web Service API.
 module GoogleMapsService
   class << self
-    attr_accessor :key, :client_id, :client_secret, :connect_timeout, :read_timeout, :retry_timeout, :queries_per_second
+
+    # Global key.
+    # @see Client#key
+    # @return [String]
+    attr_accessor :key
+
+    # Global client_id.
+    # @see Client#client_id
+    # @return [String]
+    attr_accessor :client_id
+
+    # Global client_secret.
+    # @see Client#client_secret
+    # @return [String]
+    attr_accessor :client_secret
+
+    # Global retry_timeout.
+    # @see Client#retry_timeout
+    # @return [Integer]
+    attr_accessor :retry_timeout
+
+    # Global queries_per_second.
+    # @see Client#queries_per_second
+    # @return [Integer]
+    attr_accessor :queries_per_second
+
+    # Global request_options.
+    # @see Client#initialize-instance_method
+    # @return [Hurley::RequestOptions]
+    attr_accessor :request_options
+
+    # Global ssl_options.
+    # @see Client#initialize-instance_method
+    # @return [Hurley::SslOptions]
+    attr_accessor :ssl_options
+
+    # Global connection.
+    # @see Client#initialize-instance_method
+    # @return [Object]
+    attr_accessor :connection
 
     def configure
       yield self
@@ -9,13 +49,6 @@ module GoogleMapsService
   end
 
   require 'google_maps_service/version'
-  require 'google_maps_service/errors'
-  require 'google_maps_service/convert'
-  require 'google_maps_service/directions'
-  require 'google_maps_service/distance_matrix'
-  require 'google_maps_service/elevation'
-  require 'google_maps_service/geocoding'
-  require 'google_maps_service/roads'
-  require 'google_maps_service/time_zone'
   require 'google_maps_service/client'
+  require 'google_maps_service/polyline'
 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/{directions.rb → apis/directions.rb}

@@ -1,18 +1,39 @@
-require_relative './validator'
+require_relative '../validator'
 
-module GoogleMapsService
+module GoogleMapsService::Apis
 
   # Performs requests to the Google Maps Directions API.
   module Directions
 
     # Get directions between an origin point and a destination point.
     #
+    # @example Simple directions
+    #   routes = client.directions('Sydney', 'Melbourne')
+    #
+    # @example Complex bicycling directions
+    #   routes = client.directions('Sydney', 'Melbourne',
+    #       mode: 'bicycling',
+    #       avoid: ['highways', 'tolls', 'ferries'],
+    #       units: 'metric',
+    #       region: 'au')
+    #
+    # @example Public transportation directions
+    #    an_hour_from_now = Time.now - (1.0/24)
+    #    routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
+    #        mode: 'transit',
+    #        arrival_time: an_hour_from_now)
+    #
+    # @example Walking with alternative routes
+    #    routes = client.directions('Sydney Town Hall', 'Parramatta, NSW',
+    #       mode: 'walking',
+    #       alternatives: true)
+    #
     # @param [String, Hash, Array] origin The address or latitude/longitude value from which you wish
     #         to calculate directions.
     # @param [String, Hash, Array] destination The address or latitude/longitude value from which
     #     you wish to calculate directions.
     # @param [String] mode Specifies the mode of transport to use when calculating
-    #     directions. One of "driving", "walking", "bicycling" or "transit"
+    #     directions. One of `driving`, `walking`, `bicycling` or `transit`.
     # @param [Array<String>, Array<Hash>, Array<Array>] waypoints Specifies an array of waypoints. Waypoints alter a
     #     route by routing it through the specified location(s).
     # @param [Boolean] alternatives If True, more than one route may be returned in the
@@ -21,40 +42,40 @@ module GoogleMapsService
     #     indicated features.
     # @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"
+    #     `metric` or `imperial`.
+    # @param [String] region The region code, specified as a ccTLD (_top-level domain_)
     #     two-character value.
     # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
     # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
-    #     directions. Note: you can't specify both departure_time and
-    #     arrival_time.
+    #     directions. Note: you can not specify both `departure_time` and
+    #     `arrival_time`.
     # @param [Boolean] optimize_waypoints Optimize the provided route by rearranging the
     #     waypoints in a more efficient order.
     # @param [String, Array<String>] 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"].
+    #     transit. Valid values are `bus`, `subway`, `train`, `tram` or `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"
+    #     requests. Valid values are `less_walking` or `fewer_transfers`.
     #
-    # @return List of routes
-    def directions(origin: nil, destination: nil,
+    # @return [Array] Array of routes.
+    def directions(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)
 
       params = {
-        origin: _convert_waypoint(origin),
-        destination: _convert_waypoint(destination)
+        origin: GoogleMapsService::Convert.waypoint(origin),
+        destination: GoogleMapsService::Convert.waypoint(destination)
       }
 
       params[:mode] = GoogleMapsService::Validator.travel_mode(mode) if mode
 
-      if waypoints
+      if waypoints = waypoints
         waypoints = GoogleMapsService::Convert.as_list(waypoints)
-        waypoints = waypoints.map { |waypoint| _convert_waypoint(waypoint) }
-        waypoints = ["optimize:true"] + waypoints if optimize_waypoints
+        waypoints = waypoints.map { |waypoint| GoogleMapsService::Convert.waypoint(waypoint) }
+        waypoints = ['optimize:true'] + waypoints if optimize_waypoints
 
         params[:waypoints] = GoogleMapsService::Convert.join_list("|", waypoints)
       end
@@ -76,13 +97,5 @@ module GoogleMapsService
 
       return get('/maps/api/directions/json', params)[:routes]
     end
-
-    private
-      def _convert_waypoint(waypoint)
-        if waypoint.kind_of?(String)
-          return waypoint
-        end
-        return GoogleMapsService::Convert.latlng(waypoint)
-      end
   end
 end

data/lib/google_maps_service/{distance_matrix.rb → apis/distance_matrix.rb}

@@ -1,45 +1,64 @@
-require_relative './validator'
+require_relative '../validator'
 
-module GoogleMapsService
+module GoogleMapsService::Apis
 
   # Performs requests to the Google Maps Distance Matrix API.
   module DistanceMatrix
 
     # Gets travel distance and time for a matrix of origins and destinations.
     #
-    # @param [Array<String>, Array<Hash>, Array<Array>] origins One or more addresses and/or latitude/longitude values,
+    # @example Simple distance matrix
+    #   origins = ["Perth, Australia", "Sydney, Australia",
+    #              "Melbourne, Australia", "Adelaide, Australia",
+    #              "Brisbane, Australia", "Darwin, Australia",
+    #              "Hobart, Australia", "Canberra, Australia"]
+    #   destinations = ["Uluru, Australia",
+    #                   "Kakadu, Australia",
+    #                   "Blue Mountains, Australia",
+    #                   "Bungle Bungles, Australia",
+    #                   "The Pinnacles, Australia"]
+    #   matrix = client.distance_matrix(origins, destinations)
+    #
+    # @example Complex distance matrix
+    #   origins = ["Bobcaygeon ON", [41.43206, -81.38992]]
+    #   destinations = [[43.012486, -83.6964149], {lat: 42.8863855, lng: -78.8781627}]
+    #   matrix = client.distance_matrix(origins, destinations,
+    #       mode: 'driving',
+    #       language: 'en-AU',
+    #       avoid: 'tolls',
+    #       units: 'imperial')
+    #
+    # @param [Array] origins One or more addresses and/or lat/lon pairs,
     #         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 latitude/longitude coordinate to calculate directions.
-    # @param [Array<String>, Array<Hash>, Array<Array>] destinations One or more addresses and/or lat/lng values, to
+    #         a lat/lon coordinate to calculate directions.
+    # @param [Array] destinations One or more addresses and/or lat/lon pairs, 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
-    #         latitude/longitude coordinate to calculate directions.
+    #         lat/lon 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".
+    #         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"
+    #     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"
+    #     Valid values are `metric` or `imperial`.
     # @param [Integer, DateTime] departure_time Specifies the desired time of departure.
     # @param [Integer, DateTime] arrival_time Specifies the desired time of arrival for transit
-    #     directions. Note: you can't specify both departure_time and
-    #     arrival_time.
+    #     directions. Note: you can not specify both `departure_time` and `arrival_time`.
     # @param [String, Array<String>] 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"].
+    #     transit. Valid values are `bus`, `subway`, `train`, `tram`, or `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"
+    #     requests. Valid values are `less_walking` or `fewer_transfers`.
     #
-    # @return matrix of distances. Results are returned in rows, each row
+    # @return [Hash] Matrix of distances. Results are returned in rows, each row
     #     containing one origin paired with each destination.
-    def distance_matrix(origins: nil, destinations: nil,
-                        mode: nil, language: nil, avoid: nil, units: nil,
-                        departure_time: nil, arrival_time: nil, transit_mode: nil,
-                        transit_routing_preference: nil)
+    def distance_matrix(origins, destinations,
+        mode: nil, language: nil, avoid: nil, units: nil,
+        departure_time: nil, arrival_time: nil, transit_mode: nil,
+        transit_routing_preference: nil)
       params = {
         origins: GoogleMapsService::Convert.waypoints(origins),
         destinations: GoogleMapsService::Convert.waypoints(destinations)
@@ -57,7 +76,7 @@ module GoogleMapsService
         raise ArgumentError, 'Should not specify both departure_time and arrival_time.'
       end
 
-      params[:transit_mode] = GoogleMapsService::Convert.join_list("|", transit_mode) if transit_mode
+      params[:transit_mode] = GoogleMapsService::Convert.join_list('|', transit_mode) if transit_mode
       params[:transit_routing_preference] = transit_routing_preference if transit_routing_preference
 
       return get('/maps/api/distancematrix/json', params)

data/lib/google_maps_service/{elevation.rb → apis/elevation.rb}

@@ -1,43 +1,50 @@
-module GoogleMapsService
+module GoogleMapsService::Apis
 
   # Performs requests to the Google Maps Elevation API.
   module Elevation
 
     # Provides elevation data for locations provided on the surface of the
     # earth, including depth locations on the ocean floor (which return negative
-    # values)
+    # values).
+    #
+    # @example Single point elevation
+    #   results = client.elevation({latitude: 40.714728, longitude: -73.998672})
+    #
+    # @example Multiple points elevation
+    #   locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+    #   results = client.elevation(locations)
     #
     # @param [Array] locations A single latitude/longitude hash, or an array of
     #         latitude/longitude hash from which you wish to calculate
     #         elevation data.
     #
     # @return [Array] Array of elevation data responses
-    def elevation(locations: nil)
-      params = {}
-      if locations.kind_of?(Array) and locations.length == 2 and not locations[0].kind_of?(Array)
-        locations = [locations]
-      end
-
-      params[:locations] = _convert_locations(locations)
+    def elevation(locations)
+      params = {
+        locations: GoogleMapsService::Convert.waypoints(locations)
+      }
 
-      return get("/maps/api/elevation/json", params)[:results]
+      return get('/maps/api/elevation/json', params)[:results]
     end
 
     # Provides elevation data sampled along a path on the surface of the earth.
     #
+    # @example Elevation along path
+    #   locations = [[40.714728, -73.998672], [-34.397, 150.644]]
+    #   results = client.elevation_along_path(locations, 5)
+    #
     # @param [String, Array] path A encoded polyline string, or a list of
-    #         latitude/longitude tuples from which you wish to calculate
+    #         latitude/longitude pairs from which you wish to calculate
     #         elevation data.
-    #
     # @param [Integer] samples The number of sample points along a path for which to
     #         return elevation data.
     #
     # @return [Array] Array of elevation data responses
-    def elevation_along_path(path: nil, samples: nil)
+    def elevation_along_path(path, samples)
       if path.kind_of?(String)
         path = "enc:%s" % path
       else
-        path = _convert_locations(path)
+        path = GoogleMapsService::Convert.waypoints(path)
       end
 
       params = {
@@ -45,13 +52,7 @@ module GoogleMapsService
         samples: samples
       }
 
-      return get("/maps/api/elevation/json", params)[:results]
+      return get('/maps/api/elevation/json', params)[:results]
     end
-
-    private
-      def _convert_locations(locations)
-        locations = GoogleMapsService::Convert.as_list(locations)
-        return GoogleMapsService::Convert.join_list("|", locations.map { |k| k.kind_of?(String) ? k : GoogleMapsService::Convert.latlng(k) })
-      end
   end
 end

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