google_maps_juice 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81dd523f6c0a801f8b8e15d0589525cd683359f4b85d0427f9b697d1ade77f5d
-  data.tar.gz: 2fb1b05f6a92b3770771a5ae74de3ccd09f411f66dabde16d38160f151f48d66
+  metadata.gz: f26ed08354506950932680c98e078c385bce57047a1b99bcab2a122bc26c2112
+  data.tar.gz: 9ea5e1e090fb76f2189468cacfdd9e6993a45936501d78f1bd6ee018a99c80b0
 SHA512:
-  metadata.gz: cdc4a09d044ecd8549b5a7851c1fda06be8a1ff4677df0e3173dfdabadfbb9b791789a3fe4a4a8d1dbc1d353f2382812ddc6dbb912915b679598502dd0254212
-  data.tar.gz: 646b96bb8275a1230eb16a19d6472e56bd0f31218e0580976f1e9a4c88f738604885a156d92927fcb5060e54ab0ea077bc66c77e4f351eb12384ef63b3ac5260
+  metadata.gz: dc3ae38123522b60496ff3094678f1aef15dbda36fc4eecd0dc0cc3f18f3389c54b995064e384167ec33e945ab2f8de9766ae80c8bdf8e1086ccb855acfe9cbd
+  data.tar.gz: 612b4cd78edf58cc7ac7c9ba67884c37b32130d7d4eb065aabeaf5cfb9011b3652e684eae4d78fef0f7ceb65584a45721a0a1d1e3de8b20746c7737659bea9c3

data/.ruby-version

@@ -1 +1 @@
-2.5.0
+2.6.3

data/.travis.yml

@@ -1,9 +1,9 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.5.0
+  - 2.6.3
 
-before_install: gem install bundler -v 1.16.4
+before_install: gem install bundler -v 1.17.2
 
 install: bundle install
 

data/README.md

@@ -17,6 +17,7 @@ This gem aims at progressively covering a fair amount of those widely-used servi
 
 * Geocoding
 * Time Zone
+* Directions
 
 Contributors are welcome!
 
@@ -72,13 +73,13 @@ This is especially useful in some "hybrid" scenario, where an API key is shared
 
 ## Error Handling
 
-If Google servers respond with a non-successful HTTP status code, i.e. `4xx` or `5xx`, a `GoogleMapsJuice::Error` is raised with a message of the form `'HTTP 503 - Error details as returned by the server'`.
+If Google servers respond with a non-successful HTTP status code, i.e. `4xx` or `5xx`, a `GoogleMapsJuice::ResponseError` is raised with a message of the form `'HTTP 503 - Error details as returned by the server'`.
 
 API errors are also handled, based on the `status` attribute of Google's JSON response, and the optional `error_message` attribute.
 
 * `GoogleMapsJuice::ZeroResults` is raised when `status` is `'ZERO_RESULTS'`
 * `GoogleMapsJuice::ApiLimitError` is raised when `status` is `'OVER_DAILY_LIMIT'` or `'OVER_QUERY_LIMIT'`
-* `GoogleMapsJuice::Error` is raised when `status` is not `OK` with a message of the form `API <status> - <error_message>`
+* `GoogleMapsJuice::ResponseError` is raised when `status` is not `OK` with a message of the form `API <status> - <error_message>`
 
 
 ## Geocoding
@@ -181,6 +182,57 @@ The `by_location` method returns a `GoogleMapsJuice::Timezone::Response`. It's a
 * `dst_offset`: the offset for daylight-savings time in seconds
 
 
+## Directions
+
+[Google's Directions API](https://developers.google.com/maps/documentation/directions/intro#DirectionsRequests) returns the possible routes of given origin and destination geographic locations; Google's API accepts address, textual latitude/longitude value, or place ID of which you wish to calculate directions. Currently this gem implements only latitude/longitude mode.
+`GoogleMapsJuice` will raise an `ArgumentError` if some unsupported param is passed, or when none of the required params are passed.
+
+```ruby
+response = GoogleMapsJuice::Directions.find(origin: '41.8892732,12.4921921', destination: '41.9016488,12.4583003')
+```
+
+Compared to Google's raw API request, it provides validation of both origin and destination, in order to avoid sending requests when they would fail for sure - to learn more see `spec/unit/directions_spec.rb`.
+
+**Accepted params:**
+
+* Both `origin` and `destination` are mandatory
+* `origin` is composed by `latitude` and `longitude`, comma separated float values
+* `destination` same format as `origin`
+
+
+### Directions Response
+
+The `find` method returns a `GoogleMapsJuice::Directions::Response`. It's a `Hash` representation of Google's JSON response. However, it also provides a few useful methods:
+
+* `results`: the `Hash` raw result
+
+* `routes`: an `Array` of `GoogleMapsJuice::Directions::Response::Route` objects
+
+* `first`: the first `Route` of the `routes` `List`
+
+As described in [Google's Directions API](https://developers.google.com/maps/documentation/directions/intro#Routes), the response contains all possible routes. Each route has some attributes and one or more *legs*, wich in turn have one or more *steps*.
+If no waypoints are passed, the route response will contain a single leg. Since `GoogleMapsJuice::Directions` doesn't handles waypoints yet, only the first leg is considered for each route.
+The `GoogleMapsJuice::Directions::Response::Route` is a representation of a response route and provides methods to access all route's attributes:
+
+* `summary`: a brief description of the route
+
+* `legs`: all legs of the route, generally a single one
+
+* `steps`: all steps of the first route's leg
+
+* `duration`: time duration of the first route's leg
+
+* `distance`: distance between origin and destination of first route's leg
+
+* `start_location`: `latitude`/`longitude` of the origin first route's leg
+
+* `end_location`: `latitude`/`longitude` of the destination first route's leg
+
+* `start_address`: address of the origin first route's leg
+
+* `end_address`: address of the destination first route's leg
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Create a `.env` file and save your Google API key there; if you want to use a different key for testing, put it in `.env.test` and it will override the one in `.env`.

data/google_maps_juice.gemspec

@@ -22,10 +22,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency 'activesupport', '~> 5.2'
+  spec.add_dependency 'activesupport'
   spec.add_dependency 'excon'
 
-  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'bundler', '~> 1.17.2'
   spec.add_development_dependency 'rake', '~> 12.3'
   spec.add_development_dependency 'rspec', '~> 3.5'
   spec.add_development_dependency 'webmock', '~> 3.4'

data/lib/google_maps_juice.rb

@@ -14,8 +14,9 @@ module GoogleMapsJuice
   autoload :Endpoint, 'google_maps_juice/endpoint'
   autoload :Geocoding, 'google_maps_juice/geocoding'
   autoload :Timezone, 'google_maps_juice/timezone'
+  autoload :Directions, 'google_maps_juice/directions'
 
-  class Error < Exception; end
-  class ApiLimitError < Exception; end
-  class ZeroResults < Exception; end
+  class ResponseError < RuntimeError; end
+  class ApiLimitError < ResponseError; end
+  class ZeroResults < ResponseError; end
 end

data/lib/google_maps_juice/client.rb

@@ -27,7 +27,7 @@ module GoogleMapsJuice
       else
         msg = "HTTP #{response.status}"
         msg += " - #{response.body}" if response.body.present?
-        raise GoogleMapsJuice::Error, msg
+        raise GoogleMapsJuice::ResponseError, msg
       end
     end
 

data/lib/google_maps_juice/directions.rb

@@ -0,0 +1,55 @@
+module GoogleMapsJuice
+  class Directions < Endpoint
+
+    ENDPOINT = '/directions'
+
+    autoload :Response, 'google_maps_juice/directions/response'
+
+    class << self
+      def find(params, api_key: GoogleMapsJuice.config.api_key)
+        client = GoogleMapsJuice::Client.new(api_key: api_key)
+        new(client).find(params)
+      end
+    end
+
+    def find(params)
+      validate_find_params(params)
+      response_text = @client.get("#{ENDPOINT}/json", params)
+      response = JSON.parse(response_text, object_class: Response)
+      detect_errors(response)
+    end
+
+    def validate_find_params(params)
+      raise ArgumentError, 'Hash argument expected' unless params.is_a?(Hash)
+
+      supported_keys = %w[origin destination]
+      validate_supported_params(params, supported_keys)
+
+      required_keys = %w[origin destination]
+      validate_any_required_params(params, required_keys)
+
+      validate_geo_coordinate(params)
+    end
+
+    def validate_geo_coordinate(params)
+      raise ArgumentError, 'String argument expected' unless params.values.all?(String)
+
+      geocoords = params.values.map { |x| x.split(',') }.flatten
+      geocoords.map! { |x| Float(x).round(7) }
+      raise ArgumentError, 'Wrong geo-coordinates' if geocoords.size != 4
+
+      validate_location_params(geocoords)
+    end
+
+    def validate_location_params(params)
+      latitudes = params[0], params[2]
+      if latitudes.any? { |l| l.abs > 90 }
+        raise ArgumentError, 'Wrong latitude value'
+      end
+      longitudes = params[1], params[3]
+      if longitudes.any? { |l| l.abs > 180 }
+        raise ArgumentError, 'Wrong longitude value'
+      end
+    end
+  end
+end

data/lib/google_maps_juice/directions/response.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/slice'
+
+module GoogleMapsJuice
+  class Directions::Response < GoogleMapsJuice::Endpoint::Response
+    def results
+      self['routes']
+    end
+
+    def routes
+      results.map { |r| Route.new(r) }
+    end
+
+    def first
+      routes.first
+    end
+
+    class Route
+      attr_reader :route, :first_leg
+      def initialize(route)
+        @route = route
+        @first_leg = route['legs'].first
+      end
+
+      def legs
+        route['legs']
+      end
+
+      def summary
+        route['summary']
+      end
+
+      def steps
+        first_leg['steps']
+      end
+
+      def duration
+        first_leg['duration']
+      end
+
+      def distance
+        first_leg['distance']
+      end
+
+      def start_location
+        first_leg['start_location']
+      end
+
+      def end_location
+        first_leg['end_location']
+      end
+
+      def start_address
+        first_leg['start_address']
+      end
+
+      def end_address
+        first_leg['end_address']
+      end
+    end
+  end
+end

data/lib/google_maps_juice/endpoint.rb

@@ -14,7 +14,7 @@ module GoogleMapsJuice
       elsif response.limit_error?
         raise GoogleMapsJuice::ApiLimitError, build_error_message(response)
       elsif response.error?
-        raise GoogleMapsJuice::Error, "API #{build_error_message(response)}"
+        raise GoogleMapsJuice::ResponseError, "API #{build_error_message(response)}"
       else
         response
       end

data/lib/google_maps_juice/version.rb

@@ -1,3 +1,3 @@
 module GoogleMapsJuice
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: google_maps_juice
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Algonauti srl
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-17 00:00:00.000000000 Z
+date: 2020-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: 1.17.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: 1.17.2
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -159,6 +159,8 @@ files:
 - lib/google_maps_juice.rb
 - lib/google_maps_juice/client.rb
 - lib/google_maps_juice/configuration.rb
+- lib/google_maps_juice/directions.rb
+- lib/google_maps_juice/directions/response.rb
 - lib/google_maps_juice/endpoint.rb
 - lib/google_maps_juice/geocoding.rb
 - lib/google_maps_juice/geocoding/response.rb
@@ -183,8 +185,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: 'Client for popular Google Maps API Services: Geocoding, Time Zones'