google_maps_juice 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81dd523f6c0a801f8b8e15d0589525cd683359f4b85d0427f9b697d1ade77f5d
+  data.tar.gz: 2fb1b05f6a92b3770771a5ae74de3ccd09f411f66dabde16d38160f151f48d66
+SHA512:
+  metadata.gz: cdc4a09d044ecd8549b5a7851c1fda06be8a1ff4677df0e3173dfdabadfbb9b791789a3fe4a4a8d1dbc1d353f2382812ddc6dbb912915b679598502dd0254212
+  data.tar.gz: 646b96bb8275a1230eb16a19d6472e56bd0f31218e0580976f1e9a4c88f738604885a156d92927fcb5060e54ab0ea077bc66c77e4f351eb12384ef63b3ac5260

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock
+.env

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+2.5.0

data/.travis.yml

@@ -0,0 +1,10 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.0
+
+before_install: gem install bundler -v 1.16.4
+
+install: bundle install
+
+script: bundle exec rspec

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in google_maps_juice.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Algonauti srl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# GoogleMapsJuice
+
+**Drink Google Maps Services with ease!** :tropical_drink: :earth_americas:
+
+[![Build Status](https://travis-ci.org/algonauti/google_maps_juice.svg?branch=master)](https://travis-ci.org/algonauti/google_maps_juice)
+[![Coverage Status](https://coveralls.io/repos/github/algonauti/google_maps_juice/badge.svg?branch=master)](https://coveralls.io/github/algonauti/google_maps_juice?branch=master)
+
+This gem aims at progressively covering a fair amount of those widely-used services that are part of the Google Maps Platform, such as: [Geocoding](https://developers.google.com/maps/documentation/geocoding/intro), [Time Zone](https://developers.google.com/maps/documentation/timezone/intro), [Directions](https://developers.google.com/maps/documentation/directions/intro), etc. with some key ideas:
+
+1. Allowing "standard" requests, meaning: sending the same params documented by Google.
+2. Allowing "smart" requests, meaning: with more "developer-friendly" params, and/or improved error handling.
+3. Return full Google responses, but also provide methods to easily inspect the most relevant info.
+4. Provide error handling.
+
+
+`GoogleMapsJuice` currently covers:
+
+* Geocoding
+* Time Zone
+
+Contributors are welcome!
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'google_maps_juice'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install google_maps_juice
+
+
+## Google API Key
+
+You can set your Google API key with the following one-liner:
+
+```ruby
+GoogleMapsJuice.configure { |c| c.api_key = 'my-api-key' }`
+```
+
+In a Rails application, that would typically go in an initializer.
+
+
+### Multiple API keys
+
+If you need to use multiple API keys, you have two options:
+
+* a) pass an `api_key` named param to the endpoint class method, e.g.
+
+```ruby
+GoogleMapsJuice::Geocoding.geocode(params, api_key: 'my-api-key')
+```
+
+* b) create your own `GoogleMapsJuice::Client` instance(s) and use it to create your endpoint object(s), e.g.
+
+```ruby
+client = GoogleMapsJuice::Client.new(api_key: 'my-api-key')
+geocoding = GoogleMapsJuice::Geocoding.new(client)
+response = geocoding.geocode(params)
+```
+
+This is especially useful in some "hybrid" scenario, where an API key is shared by a group of requests, but another group uses a different key: a `client` object would then be instantiated and reused for each group.
+
+
+## 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'`.
+
+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>`
+
+
+## Geocoding
+
+### Standard Geocoding
+
+The simplest geocoding requests accept an address:
+
+```ruby
+response = GoogleMapsJuice::Geocoding.geocode(address: '8955 Lantana Rd, Lake Worth, FL 33467, USA')
+```
+
+Supported params are the ones accepted by Google's endpoint: `address`, `components`, `bounds`, `language`, `region`; at least one between `address` and `components` is required. Learn more [here](https://developers.google.com/maps/documentation/geocoding/intro#geocoding). `GoogleMapsJuice` will raise an `ArgumentError` if some unsupported param is passed, or when none of the required params are passed.
+
+
+### Smart Geocoding
+
+**Motivation**
+
+For best geocoding results, the `address` param should be formatted according to the local language. This is often a hard task for an application that needs to geocode addresses stored as separate fields. Luckily, Google offers the `components` param which accepts individual address fields; however, it's annoying to build it and it's not fault tolerant. For example, an error on `postal_code` makes geocoding of a whole address fail.
+
+Purpose of `i_geocode` method is twofold:
+
+1. Providing a simpler method interface for leveraging Google's `components` param
+2. Providing an approximate geocoding result when some address component is wrong
+
+Here an example call with all supported params:
+
+```ruby
+response = GoogleMapsJuice::Geocoding.i_geocode(
+  {
+    address: '8955 Lantana Rd',
+    locality: 'Lake Worth',
+    administrative_area: 'FL',
+    postal_code: '33467',
+    country: 'US'
+  }, sleep_before_retry: 0.15
+)
+```
+
+**Accepted params:**
+
+* At least one between `address` and `country` is required
+* `locality`, `administrative_area`, `postal_code` and `country` expect the same content as described in [Component Filtering](https://developers.google.com/maps/documentation/geocoding/intro#ComponentFiltering)
+* `address` can also include more info than street number and name, as long as they do not contrast with other params passed
+* An optional `sleep_before_retry` param sets seconds between geocoding attempts (see below); defaults to zero.
+* `GoogleMapsJuice` will raise an `ArgumentError` if some unsupported param is passed, or when none of the required params are passed.
+
+**How it works**
+
+On its 1st attempt, `i_geocode` sends all received params to Google's endpoint, properly formatted. If a `GoogleMapsJuice::ZeroResults` is raised, it removes a param and retries until no error is raised. Params are removed in the following order:
+
+* `postal_code`
+* `address`
+* `locality`
+* `administrative_area`
+
+As a consequence:
+
+* In the best case, `i_geocode` will send 1 request to Google API
+* In the worst case, `i_geocode` will send 4 requests to Google API
+
+
+### Geocoding Response
+
+Both `geocode` and `i_geocode` methods return a `GoogleMapsJuice::Geocoding::Response`. It's a `Hash` representation of Google's JSON response. However, it also provides many useful methods:
+
+* `latitude`, `longitude`: geographic coordinates as `float` numbers
+
+* `street_number`, `route`, `locality`, `postal_code`, `administrative_area_level_1`, `country`: all of these methods return a `Hash` with 2 keys: `'short_name'` and `'long_name'`
+
+* `partial_match?`: boolean, `true` if some param (of the last geocoding attempt) partially matched
+
+* `precision`: can be one of: `'street_number'`, `'route'`, `'locality'`, `'postal_code'`, `'administrative_area_level_1'`, `'country'` and represents the most-specific matching component
+
+
+## Time Zone
+
+[Google's Time Zone API](https://developers.google.com/maps/documentation/timezone/intro#Requests) returns the time zone of a given geographic location; it also accepts a timestamp, in order to determine whether DST should be applied or not.
+
+GoogleMapsJuice provides the `GoogleMapsJuice::Timezone.by_location` method. Compared to Google's raw API request, it provides simpler params and some validations, in order to avoid sending requests when they would fail for sure (and then save money!) - to learn more see `spec/unit/timezone_spec.rb`.
+
+**Accepted params:**
+
+* Both `latitude` and `longitude` are mandatory
+* `timestamp` is optional and defaults to `Time.now`
+* `language` is optional
+
+
+### Time Zone Response
+
+The `by_location` method returns a `GoogleMapsJuice::Timezone::Response`. It's a `Hash` representation of Google's JSON response. However, it also provides a few useful methods:
+
+* `timezone_id`: unique name as defined in [IANA Time Zone Database](https://www.iana.org/time-zones)
+
+* `timezone_name`: the long form name of the time zone
+
+* `raw_offset`: the offset from UTC in seconds
+
+* `dst_offset`: the offset for daylight-savings time in seconds
+
+
+## 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`.
+
+Run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+### Implementing a new endpoint
+
+All endpoints must be subclasses of `GoogleMapsJuice::Endpoint`; methods that implement "standard" Google API calls have a common structure, described by the `invoke` method in the `SomeEndpoint` test class in `spec/unit/endpoint_spec.rb`.
+
+All new endpoints' methods must return subclasses of `GoogleMapsJuice::Endpoint::Response` as their response objects, since it contains methods needed for error handling.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/algonauti/google_maps_juice.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "google_maps_juice"
+require 'dotenv/load'
+
+Dotenv.overload('.env', '.env.development')
+
+GoogleMapsJuice.configure do |config|
+  config.api_key = ENV.fetch('API_KEY')
+end
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/env-example

@@ -0,0 +1 @@
+API_KEY=

data/google_maps_juice.gemspec

@@ -0,0 +1,35 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "google_maps_juice/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "google_maps_juice"
+  spec.version       = GoogleMapsJuice::VERSION
+  spec.authors       = ["Algonauti srl"]
+  spec.email         = ["info@algonauti.com"]
+
+  spec.summary       = "Client for popular Google Maps API Services: Geocoding, Time Zones"
+  spec.description   = "Put Google Maps APIs in a spin-dryer and drink their juice: Geocoding, Time Zones, ...and more upcoming!"
+  spec.homepage      = "https://github.com/algonauti/google_maps_juice"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activesupport', '~> 5.2'
+  spec.add_dependency 'excon'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'rake', '~> 12.3'
+  spec.add_development_dependency 'rspec', '~> 3.5'
+  spec.add_development_dependency 'webmock', '~> 3.4'
+  spec.add_development_dependency 'dotenv', '~> 2.5'
+  spec.add_development_dependency 'vcr', '~> 4.0'
+  spec.add_development_dependency 'coveralls', '~> 0.8'
+end

data/lib/google_maps_juice.rb

@@ -0,0 +1,21 @@
+require 'active_support/core_ext/object'
+require 'active_support/dependencies/autoload'
+
+require 'excon'
+require 'json'
+
+require 'google_maps_juice/configuration'
+require 'google_maps_juice/version'
+
+module GoogleMapsJuice
+  extend ActiveSupport::Autoload
+
+  autoload :Client, 'google_maps_juice/client'
+  autoload :Endpoint, 'google_maps_juice/endpoint'
+  autoload :Geocoding, 'google_maps_juice/geocoding'
+  autoload :Timezone, 'google_maps_juice/timezone'
+
+  class Error < Exception; end
+  class ApiLimitError < Exception; end
+  class ZeroResults < Exception; end
+end

data/lib/google_maps_juice/client.rb

@@ -0,0 +1,39 @@
+module GoogleMapsJuice
+  class Client
+    attr_reader :api_key, :connection
+
+    class << self
+      def get(endpoint, params, api_key: GoogleMapsJuice.config.api_key)
+        self.new(api_key: api_key).get(endpoint, params)
+      end
+    end
+
+    API_HOST = 'https://maps.googleapis.com'
+    API_PATH = '/maps/api'
+
+    def initialize(api_key: GoogleMapsJuice.config.api_key)
+      @api_key = api_key
+      @connection = Excon.new(API_HOST)
+    end
+
+    def get(endpoint, params)
+      full_params = (params || Hash.new).merge({ key: api_key })
+      response = connection.get(
+        path: "#{API_PATH}#{endpoint}",
+        query: full_params
+      )
+      if healthy_http_status?(response.status)
+        response.body
+      else
+        msg = "HTTP #{response.status}"
+        msg += " - #{response.body}" if response.body.present?
+        raise GoogleMapsJuice::Error, msg
+      end
+    end
+
+    def healthy_http_status?(status)
+      /^[123]\d{2}$/.match?("#{status}")
+    end
+
+  end
+end

data/lib/google_maps_juice/configuration.rb

@@ -0,0 +1,5 @@
+require 'active_support/configurable'
+
+module GoogleMapsJuice
+  include ActiveSupport::Configurable
+end

data/lib/google_maps_juice/endpoint.rb

@@ -0,0 +1,86 @@
+module GoogleMapsJuice
+  class Endpoint
+
+    def initialize(client)
+      @client = client
+    end
+
+    protected
+
+    def detect_errors(response)
+      raise ArgumentError, 'GoogleMapsJuice::Endpoint::Response argument expected' unless response.is_a?(Response)
+      if response.zero_results?
+        raise GoogleMapsJuice::ZeroResults
+      elsif response.limit_error?
+        raise GoogleMapsJuice::ApiLimitError, build_error_message(response)
+      elsif response.error?
+        raise GoogleMapsJuice::Error, "API #{build_error_message(response)}"
+      else
+        response
+      end
+    end
+
+    def build_error_message(response)
+      msg = response.status
+      msg += " - #{response.error_message}" if response.error_message.present?
+    end
+
+    def validate_supported_params(params, supported_keys)
+      unsupported_params = params.keys.select do |key|
+        !supported_keys.include?(key.to_s)
+      end
+      if unsupported_params.present?
+        raise ArgumentError, "The following params are not supported: #{unsupported_params.join(', ')}"
+      end
+    end
+
+    def validate_required_params(params, required_keys, check_mode)
+      required_params_present = required_keys.send("#{check_mode}?") do |key|
+        params.keys.map(&:to_s).include?(key)
+      end
+      unless required_params_present
+        verb = check_mode == 'one' ? 'is' : 'are'
+        raise ArgumentError, "#{check_mode.capitalize} of the following params #{verb} required: #{required_keys.join(', ')}"
+      end
+    end
+
+
+    %w( any one all ).each do |check_mode|
+
+      define_method "validate_#{check_mode}_required_params" do |params, required_keys|
+        validate_required_params(params, required_keys, check_mode)
+      end
+
+    end
+
+
+    class Response < Hash
+
+      def status
+        self['status']
+      end
+
+      def error?
+        status.upcase != 'OK'
+      end
+
+      def zero_results?
+        status.upcase == 'ZERO_RESULTS'
+      end
+
+      def limit_error?
+        %w( OVER_DAILY_LIMIT OVER_QUERY_LIMIT ).include?(status.upcase)
+      end
+
+      def error_message
+        self['error_message']
+      end
+
+      def results
+        self['results']
+      end
+
+    end
+
+  end
+end

data/lib/google_maps_juice/geocoding.rb

@@ -0,0 +1,99 @@
+module GoogleMapsJuice
+  class Geocoding < Endpoint
+
+    ENDPOINT = '/geocode'
+
+    autoload :Response, 'google_maps_juice/geocoding/response'
+
+    class << self
+      def geocode(params, api_key: GoogleMapsJuice.config.api_key)
+        client = GoogleMapsJuice::Client.new(api_key: api_key)
+        self.new(client).geocode(params)
+      end
+
+      def i_geocode(params, sleep_before_retry: 0, api_key: GoogleMapsJuice.config.api_key)
+        client = GoogleMapsJuice::Client.new(api_key: api_key)
+        self.new(client).i_geocode(params, sleep_before_retry: sleep_before_retry)
+      end
+    end
+
+
+    def geocode(params)
+      validate_geocode_params(params)
+      response_text = @client.get("#{ENDPOINT}/json", params)
+      response = JSON.parse(response_text, object_class: Response)
+      detect_errors(response)
+    end
+
+    def i_geocode(params, sleep_before_retry: 0)
+      validate_i_geocode_params(params)
+      response = nil
+      removable_keys = [:administrative_area, :locality, :address, :postal_code]
+      begin
+        request_params = build_request_params(params)
+        response = geocode(request_params)
+      rescue ZeroResults => e
+        deleted_param = nil
+        while removable_keys.present? && deleted_param.nil?
+          key = removable_keys.pop
+          deleted_param = params.delete(key)
+        end
+        if deleted_param.present?
+          sleep sleep_before_retry
+          retry
+        else
+          raise e
+        end
+      end
+      response
+    end
+
+    def validate_geocode_params(params)
+      raise ArgumentError, 'Hash argument expected' unless params.is_a?(Hash)
+
+      supported_keys = %w( address components bounds language region )
+      validate_supported_params(params, supported_keys)
+
+      required_keys = %w( address components )
+      validate_any_required_params(params, required_keys)
+    end
+
+    def validate_i_geocode_params(params)
+      raise ArgumentError, 'Hash argument expected' unless params.is_a?(Hash)
+
+      supported_keys = %w( address locality postal_code administrative_area country language)
+      validate_supported_params(params, supported_keys)
+
+      required_keys = %w( address country )
+      validate_any_required_params(params, required_keys)
+    end
+
+    def build_request_params(i_geocode_params)
+      req_params = Hash.new
+
+      [:address, :language].each do |key|
+        if i_geocode_params[key].present?
+          req_params[key] = i_geocode_params[key]
+        end
+      end
+
+      components = build_components_param(i_geocode_params, keys:
+        [:locality, :postal_code, :administrative_area, :country]
+      )
+      if components.present?
+        req_params[:components] = components
+      end
+
+      req_params
+    end
+
+    def build_components_param(params, keys: [])
+      keys.map do |key|
+        if params[key].present?
+          "#{key}:#{params[key]}"
+        end
+      end.compact.join('|')
+    end
+
+  end
+end

data/lib/google_maps_juice/geocoding/response.rb

@@ -0,0 +1,70 @@
+require 'active_support/core_ext/hash/slice'
+
+module GoogleMapsJuice
+  class Geocoding::Response < GoogleMapsJuice::Endpoint::Response
+
+    class << self
+      def precisions
+        %w( street_number route postal_code locality administrative_area_level_1
+            administrative_area_level_2 administrative_area_level_3 country )
+      end
+    end
+
+    def latitude
+      location['lat']
+    end
+
+    def longitude
+      location['lng']
+    end
+
+    def location
+      result.dig('geometry', 'location')
+    end
+
+    def partial_match?
+      result['partial_match'] == true
+    end
+
+    def result
+      results.first
+    end
+
+    def address_components
+      result['address_components']
+    end
+
+    def precision
+      self.class.precisions.find do |type|
+        address_components.any? do |comp|
+          comp['types'].include?(type)
+        end
+      end
+    end
+
+
+    %w( street_number
+        route
+        locality
+        sublocality
+        postal_code
+        administrative_area_level_1
+        administrative_area_level_2
+        administrative_area_level_3
+        country ).each do |type|
+
+      define_method(type) do
+        addr_component_by(type: type)&.slice('long_name', 'short_name')
+      end
+
+    end
+
+
+    private
+
+    def addr_component_by(type: '')
+      address_components.find { |ac| ac['types'].include?(type) }
+    end
+
+  end
+end

data/lib/google_maps_juice/timezone.rb

@@ -0,0 +1,82 @@
+module GoogleMapsJuice
+  class Timezone < Endpoint
+
+    ENDPOINT = '/timezone'
+
+    class << self
+      def by_location(params, api_key: GoogleMapsJuice.config.api_key)
+        client = GoogleMapsJuice::Client.new(api_key: api_key)
+        self.new(client).by_location(params)
+      end
+    end
+
+    def by_location(params)
+      validate_params(params)
+      response_text = @client.get("#{ENDPOINT}/json", build_request_params(params))
+      response = JSON.parse(response_text, object_class: Response)
+      detect_errors(response)
+    end
+
+    def validate_params(params)
+      raise ArgumentError, 'Hash argument expected' unless params.is_a?(Hash)
+
+      supported_keys = %w( latitude longitude timestamp language )
+      validate_supported_params(params, supported_keys)
+
+      required_keys = %w( latitude longitude )
+      validate_all_required_params(params, required_keys)
+
+      validate_timestamp_param(params)
+      validate_location_params(params)
+    end
+
+    def validate_timestamp_param(params)
+      if params.has_key?(:timestamp)
+        raise ArgumentError, 'Timestamp must be a Time instance' unless params[:timestamp].is_a?(Time)
+      end
+    end
+
+    def validate_location_params(params)
+      if params[:latitude].abs > 90
+        raise ArgumentError, 'Wrong latitude value'
+      end
+      if params[:longitude].abs > 180
+        raise ArgumentError, 'Wrong longitude value'
+      end
+    end
+
+    def build_request_params(params)
+      seconds_since_epoch = (params[:timestamp] || Time.now).to_i
+      {
+        location: "#{params[:latitude]},#{params[:longitude]}",
+        timestamp: seconds_since_epoch
+      }.tap do |req_params|
+        if params[:language]
+          req_params[:language] = params[:language]
+        end
+      end
+    end
+
+
+    class Response < GoogleMapsJuice::Endpoint::Response
+
+      def timezone_id
+        self['timeZoneId']
+      end
+
+      def timezone_name
+        self['timeZoneName']
+      end
+
+      def raw_offset
+        self['rawOffset']
+      end
+
+      def dst_offset
+        self['dstOffset']
+      end
+
+    end
+
+  end
+end

data/lib/google_maps_juice/version.rb

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

metadata

@@ -0,0 +1,191 @@
+--- !ruby/object:Gem::Specification
+name: google_maps_juice
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Algonauti srl
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-10-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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: 'Put Google Maps APIs in a spin-dryer and drink their juice: Geocoding,
+  Time Zones, ...and more upcoming!'
+email:
+- info@algonauti.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- env-example
+- google_maps_juice.gemspec
+- lib/google_maps_juice.rb
+- lib/google_maps_juice/client.rb
+- lib/google_maps_juice/configuration.rb
+- lib/google_maps_juice/endpoint.rb
+- lib/google_maps_juice/geocoding.rb
+- lib/google_maps_juice/geocoding/response.rb
+- lib/google_maps_juice/timezone.rb
+- lib/google_maps_juice/version.rb
+homepage: https://github.com/algonauti/google_maps_juice
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: 'Client for popular Google Maps API Services: Geocoding, Time Zones'
+test_files: []