timezone 0.3.3 → 0.3.4

data/CHANGES.markdown

@@ -1,3 +1,7 @@
+# 0.3.4
+
+* Added support for Google Timezone API. (amnesia7)
+
 # 0.3.3
 
 * Updated parsing code. (panthomakos)

data/CONTRIBUTING.markdown

@@ -10,3 +10,8 @@
 * Extract and use `zic` to load data into `/usr/share/zoneinfo`.
 * Run `bundle exec rake parse` to parse files in `right/` directory into
   the local `data` directory.
+
+# Notes
+
+* How to read TZData IANA source files:
+  http://www.cstdbill.com/tzdb/tz-how-to.html

data/README.markdown

@@ -1,6 +1,14 @@
 # Timezone
 
-A simple way to get accurate current and historical timezone information based on zone or latitude and longitude coordinates. This gem uses the [tz database](http://www.twinsun.com/tz/tz-link.htm) for historical timezone information. It also uses the [geonames API](http://www.geonames.org/export/web-services.html) for timezone latitude and longitude lookup.
+A simple way to get accurate current and historical timezone information based
+on zone or latitude and longitude coordinates. This gem uses the
+[tz database][tz-database] for historical timezone information. It also uses the
+[geonames API][geonames-api] or the [Google Timezone API][google-api] for
+timezone latitude and longitude lookup.
+
+[tz-database]: http://www.twinsun.com/tz/tz-link.htm
+[geonames-api]: http://www.geonames.org/export/web-services.html
+[google-api]: https://developers.google.com/maps/documentation/timezone/
 
 ## Installation
 
@@ -47,7 +55,15 @@ Second, add the following to your application.rb file, or before you perform a c
       c.username = 'your_geonames_username_goes_here'
     end
 
-Finally, pass the coordinates to your timezone initialization function.
+Alternatively, timezone can be used with a Google api key, which you can get [here](https://code.google.com/apis/console/).
+
+Next, add the following to your application.rb file, or before you perform a coordinate lookup.
+
+    Timezone::Configure.begin do |c|
+      c.google_api_key = 'your_google_api_key_goes_here'
+    end
+
+Finally, for either geonames or Google implementation, pass the coordinates to your timezone initialization function.
 
     timezone = Timezone::Zone.new :latlon => [-34.92771808058, 138.477041423321]
     timezone.zone
@@ -74,7 +90,7 @@ If you need information from a specific set of timezones rather than a complete
 
     zone_list = Timezone::Zone.list "America/Chicago", "America/New_York", "America/Boise"
     # This will return an array of information hashes in the following format:
-    # { 
+    # {
     #   :zone => "America/Chicago",
     #   :title => "America/Chicago", # this can be customized to your needs
     #   :offset => -18000, # UTC offset in seconds
@@ -98,14 +114,13 @@ Finally, by default the **Zone#list** method will order the results by the timez
 
     Timezone::Configure.begin do |c|
       # this can equal any hash key returned by the Zone#list method
-      c.order_list_by = :title 
+      c.order_list_by = :title
     end
 
 ## Using Your Own HTTP Client
 
-If you have non-standard http request needs or want to have more control over
-API calls to Geonames, you can write your own very simple http client wrapper
-instead of using the built-in default.
+If you have non-standard http request needs or want to have more control over API calls to Geonames and Google, you can write your own very simple http client wrapper instead of using the built-in default.
+Be aware that the Google timezone API uses `https` protocol.
 
     class MyHTTPClient
       def initialize(protocol, host)

data/lib/timezone/configure.rb

@@ -7,50 +7,130 @@ module Timezone
   # {http://www.geonames.org/login Geonames}. Use the username to
   # configure your application for latitude and longitude based
   # timezone searches.
+  # Alternatively, you'll want to sign up for a Google api key at
+  # {https://code.google.com/apis/console/ Google}. Use the api key to
+  # configure your application for latitude and longitude based
+  # timezone searches.
   #
   # If you aren't going to initialize timezone objects based on lat,lng
   # then this configuration is not necessary.
   #
   # @example
   #     Timezone::Configure.begin do |c|
-  #       c.url = 'api.geonames.org'
+  #       c.geonames_url = 'api.geonames.org'
   #       c.username = 'foo-bar'
+  #       c.google_api_key = 'abc123'
   #     end
   #
   class Configure
+    # The Google API key
+    #
+    # @return [String]
+    #   the Google API key ('abc123')
+    def self.google_api_key
+      @google_api_key
+    end
+
+    # Google API key
+    #
+    # @param [String] api_key
+    #   the Google API key
+    def self.google_api_key=(api_key)
+      @google_api_key = api_key
+    end
+
+    # Use Google API if key has been set
+    #
+    # @return [Boolean]
+    def self.use_google?
+      !!google_api_key
+    end
+
     # The Geonames API URL
     #
-    # @return [Sting]
+    # @return [String]
     #   the Geonames API URL ('api.geonames.org')
-    def self.url
-      @@url ||= 'api.geonames.org'
+    def self.geonames_url
+      @@geonames_url ||= 'api.geonames.org'
     end
 
     # The Geonames API URL
     #
-    # @param [Sting] url
+    # @param [String] url
     #   the Geonames API URL
-    def self.url=(url)
-      @@url = url
+    def self.geonames_url=(url)
+      @@geonames_url = url
+    end
+
+    class << self
+      alias :url= :geonames_url=
+    end
+
+    # The Google API URL
+    #
+    # @return [String]
+    #   the Google API URL ('maps.googleapis.com')
+    def self.google_url
+      @@google_url ||= 'maps.googleapis.com'
+    end
+
+    # The Google API URL
+    #
+    # @param [String] url
+    #   the Google API URL
+    def self.google_url=(url)
+      @@google_url = url
+    end
+
+    # Use Google URL if key has been set else use Geonames URL
+    #
+    # @return [String]
+    #   the Google or Geonames API URL
+    def self.url
+      use_google? ? google_url : geonames_url
     end
 
     # The Geonames API HTTP protocol
     #
     # @param [String] protocol
     #   the Geonames API HTTP procotol
-    def self.protocol=(protocol)
-      @@protocol = protocol
+    def self.geonames_protocol=(protocol)
+      @@geonames_protocol = protocol
     end
 
     # The Geonames API HTTP protocol
     #
-    # @return [Sting]
-    #   the Geonames API URL ('api.geonames.org')
+    # @return [String]
+    #   the Geonames API HTTP protocol ('http')
+    def self.geonames_protocol
+      @@geonames_protocol ||= 'http'
+    end
+
+    # The Google API HTTP protocol
+    #
+    # @param [String] protocol
+    #   the Google API HTTP procotol
+    def self.google_protocol=(protocol)
+      @@google_protocol = protocol
+    end
+
+    # The Google API HTTP protocol
+    #
+    # @return [String]
+    #   the Google API HTTP protocol ('https')
+    def self.google_protocol
+      @@google_protocol ||= 'https'
+    end
+
+    # Use Google protocol if key has been set else use Geonames protocol
+    #
+    # @return [String]
+    #   the Google or Geonames API protocol
     def self.protocol
-      @protocol ||= 'http'
+      use_google? ? google_protocol : geonames_protocol
     end
 
-    # The HTTP client that handles requests to geonames
+    # The HTTP client that handles requests to Geonames and Google
     #
     # @return [Object]
     #   the HTTP client ({Timezone::NetHTTPClient Timezone::NetHTTPClient})
@@ -58,20 +138,28 @@ module Timezone
       @@http_client ||= Timezone::NetHTTPClient
     end
 
-    # The HTTP client that handles requests to geonames
+    # The HTTP client that handles requests to Geonames and Google
     #
     # @param [Object] client
-    #   the HTTP client that handles requests to geonames
+    #   the HTTP client that handles requests to Geonames and Google
     #
     def self.http_client=(client)
       @@http_client = client
     end
 
+    # The Geonames API username
+    #
+    # @return [String]
+    #   the Geonames API username ('foo-bar')
     def self.username
       @@username
     end
 
-    def self.username= username
+    # The Geonames API username
+    #
+    # @param [String] username
+    #   the Geonames API username
+    def self.username=(username)
       @@username = username
     end
 

data/lib/timezone/error.rb

@@ -11,6 +11,7 @@ module Timezone
     class InvalidZone < Base; end
     class NilZone < Base; end
     class GeoNames < Base; end
+    class Google < Base; end
     class ParseTime < Base; end
   end
-end
+end

data/lib/timezone/net_http_client.rb

@@ -2,9 +2,10 @@ require 'uri'
 require 'net/http'
 
 module Timezone
-  # A basic HTTP Client that handles requests to Geonames. You can create
-  # your own version of this class if you want to use a proxy or a
-  # different http library such as faraday.
+  # A basic HTTP Client that handles requests to Geonames and Google. You
+  # can create your own version of this class if you want to use a proxy
+  # or a different http library such as faraday but be aware that the 
+  # Google timezone API uses https protocol.
   #
   # @example
   #     Timezone::Configure.begin do |c|
@@ -14,6 +15,7 @@ module Timezone
     def initialize(protocol, host)
       uri = URI.parse("#{protocol}://#{host}")
       @http = Net::HTTP.new(uri.host, uri.port)
+      @http.use_ssl = (protocol == 'https')
     end
 
     def get(url)

data/lib/timezone/version.rb

@@ -1,3 +1,3 @@
 module Timezone
-  VERSION = "0.3.3"
+  VERSION = "0.3.4"
 end

data/lib/timezone/zone.rb

@@ -148,18 +148,39 @@ module Timezone
 
     def timezone_id lat, lon #:nodoc:
       begin
-        response = http_client.get("/timezoneJSON?lat=#{lat}&lng=#{lon}&username=#{Timezone::Configure.username}")
-        return nil unless response.code =~ /^2\d\d$/
+        if Timezone::Configure.use_google?
+          timestamp   = Time.now.to_i
+          lookupUrl   = "/maps/api/timezone/json?location=#{lat},#{lon}&timestamp=#{timestamp}&key=#{Timezone::Configure.google_api_key}"
+          timezoneId  = 'timeZoneId' # uppercase 'Z'
+        else
+          lookupUrl   = "/timezoneJSON?lat=#{lat}&lng=#{lon}&username=#{Timezone::Configure.username}"
+          timezoneId  = 'timezoneId' # lowercase 'z'
+        end
 
-        data = JSON.parse(response.body)
+        response = http_client.get(lookupUrl)
 
-        if data['status'] && data['status']['value'] == 18
-          raise Timezone::Error::GeoNames, "api limit reached"
-        end
+        if response.code =~ /^2\d\d$/
+          data = JSON.parse(response.body)
+
+          # check response
+          if Timezone::Configure.use_google?
+            if data['status'] != 'OK'
+              raise Timezone::Error::Google, data['errorMessage']
+            end
+          else
+            if data['status'] && data['status']['value'] == 18
+              raise Timezone::Error::GeoNames, 'api limit reached'
+            end
+          end
 
-        return data['timezoneId']
+          return data[timezoneId]
+        end
       rescue => e
-        raise Timezone::Error::GeoNames, e.message
+        if Timezone::Configure.use_google?
+          raise Timezone::Error::Google, e.message
+        else
+          raise Timezone::Error::GeoNames, e.message
+        end
       end
     end
 

data/test/mocks/google_lat_lon_coords.txt

@@ -0,0 +1,8 @@
+{
+   "dstOffset" : 3600,
+   "rawOffset" : 34200,
+   "status" : "OK",
+   "timeZoneId" : "Australia/Adelaide",
+   "timeZoneName" : "Australian Central Daylight Time"
+}
+

data/test/mocks/google_request_denied.txt

@@ -0,0 +1,5 @@
+{
+   "errorMessage" : "The provided API key is invalid.",
+   "status" : "REQUEST_DENIED"
+}
+

data/test/timezone_test.rb

@@ -162,7 +162,7 @@ class TimezoneTest < Test::Unit::TestCase
     end
   end
 
-  def test_using_lat_lon_coordinates
+  def test_geonames_using_lat_lon_coordinates
     mock_path = File.expand_path(File.join(File.dirname(__FILE__), 'mocks'))
     HTTPTestClient.body = File.open(mock_path + '/lat_lon_coords.txt').read
 
@@ -189,6 +189,33 @@ class TimezoneTest < Test::Unit::TestCase
     end
   end
 
+  def test_google_using_lat_lon_coordinates
+    mock_path = File.expand_path(File.join(File.dirname(__FILE__), 'mocks'))
+    HTTPTestClient.body = File.open(mock_path + '/google_lat_lon_coords.txt').read
+
+    Timezone::Configure.begin do |c|
+      c.http_client = HTTPTestClient
+      c.google_api_key = '123abc'
+    end
+
+    timezone = Timezone::Zone.new :latlon => [-34.92771808058, 138.477041423321]
+    assert_equal 'Australia/Adelaide', timezone.zone
+  end
+
+  def test_google_request_denied_read_lat_lon_coordinates
+    mock_path = File.expand_path(File.join(File.dirname(__FILE__), 'mocks'))
+    HTTPTestClient.body = File.open(mock_path + '/google_request_denied.txt').read
+
+    Timezone::Configure.begin do |c|
+      c.http_client = HTTPTestClient
+      c.google_api_key = 'invalid-api-key'
+    end
+
+    assert_raise Timezone::Error::Google, 'The provided API key is invalid.' do
+      Timezone::Zone.new :latlon => [-34.92771808058, 138.477041423321]
+    end
+  end
+
   def test_australian_timezone_with_dst
     timezone = Timezone::Zone.new :zone => 'Australia/Adelaide'
     utc = Time.utc(2010, 12, 23, 19, 37, 15)
@@ -201,10 +228,10 @@ class TimezoneTest < Test::Unit::TestCase
   end
 
   def test_configure_url_custom
-    Timezone::Configure.begin { |c| c.url = 'www.newtimezoneserver.com' }
+    Timezone::Configure.begin { |c| c.geonames_url = 'www.newtimezoneserver.com' }
     assert_equal 'www.newtimezoneserver.com', Timezone::Configure.url
     # clean up url after test
-    Timezone::Configure.begin { |c| c.url = nil }
+    Timezone::Configure.begin { |c| c.geonames_url = nil }
   end
 
   def test_utc_offset_without_dst

data/timezone.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.email       = ["pan.thomakos@gmail.com"]
   s.homepage    = "http://github.com/panthomakos/timezone"
   s.summary     = "timezone-#{Timezone::VERSION}"
-  s.description = %q{A simple way to get accurate current and historical timezone information based on zone or latitude and longitude coordinates. This gem uses the tz database (http://www.twinsun.com/tz/tz-link.htm) for historical timezone information. It also uses the geonames API for timezone latitude and longitude lookup (http://www.geonames.org/export/web-services.html).}
+  s.description = %q{A simple way to get accurate current and historical timezone information based on zone or latitude and longitude coordinates. This gem uses the tz database (http://www.twinsun.com/tz/tz-link.htm) for historical timezone information. It also uses either the geonames API (http://www.geonames.org/export/web-services.html) or Google timezone API (https://developers.google.com/maps/documentation/timezone/) for timezone latitude and longitude lookup.}
   s.license     = 'MIT'
 
   s.rubyforge_project = "timezone"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timezone
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-23 00:00:00.000000000 Z
+date: 2014-12-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -78,7 +78,9 @@ dependencies:
 description: A simple way to get accurate current and historical timezone information
   based on zone or latitude and longitude coordinates. This gem uses the tz database
   (http://www.twinsun.com/tz/tz-link.htm) for historical timezone information. It
-  also uses the geonames API for timezone latitude and longitude lookup (http://www.geonames.org/export/web-services.html).
+  also uses either the geonames API (http://www.geonames.org/export/web-services.html)
+  or Google timezone API (https://developers.google.com/maps/documentation/timezone/)
+  for timezone latitude and longitude lookup.
 email:
 - pan.thomakos@gmail.com
 executables: []
@@ -689,6 +691,8 @@ files:
 - test/data/Helsinki_rules_without_timestamps.json
 - test/data/asia
 - test/mocks/api_limit_reached.txt
+- test/mocks/google_lat_lon_coords.txt
+- test/mocks/google_request_denied.txt
 - test/mocks/lat_lon_coords.txt
 - test/timezone_test.rb
 - timezone.gemspec
@@ -717,11 +721,13 @@ rubyforge_project: timezone
 rubygems_version: 1.8.23.2
 signing_key: 
 specification_version: 3
-summary: timezone-0.3.3
+summary: timezone-0.3.4
 test_files:
 - test/data/Helsinki_rules_without_timestamps.json
 - test/data/asia
 - test/mocks/api_limit_reached.txt
+- test/mocks/google_lat_lon_coords.txt
+- test/mocks/google_request_denied.txt
 - test/mocks/lat_lon_coords.txt
 - test/timezone_test.rb
 has_rdoc: