geokit 1.3.0 → 1.3.1

data/History.txt

@@ -1,3 +1,7 @@
+=== 1.3.1 / 2009-05-21
+* Support for External geocoders file (thanks dreamcat4)
+* Support multiple ip geocoders, including new setting for ip_provider_order (thanks dreamcat4)
+
 === 1.3.0 / 2009-04-11
 * Added capability to define multiple API keys for different domains that may be pointing to the same application (thanks Glenn Powell)
 * Added numeric accuracy accessor for Yahoo and Google geocoders (thanks Andrew Fecheyr Lippens)

data/README.markdown

@@ -96,6 +96,10 @@ If you're using this gem by itself, here are the configuration options:
 		# and http://geocoder.ca/?register=1
 		Geokit::Geocoders::geocoder_ca = false
 		
+		# require "external_geocoder.rb"
+		# Please see the section "writing your own geocoders" for more information.
+		# Geokit::Geocoders::external_key = 'REPLACE_WITH_YOUR_API_KEY'
+		
 		# This is the order in which the geocoders are called in a failover scenario
 		# If you only want to use a single geocoder, put a single symbol in the array.
 		# Valid symbols are :google, :yahoo, :us, and :ca.
@@ -103,6 +107,10 @@ If you're using this gem by itself, here are the configuration options:
 		# various geocoders.  Make sure you read up on relevant Terms of Use for each
 		# geocoder you are going to use.
 		Geokit::Geocoders::provider_order = [:google,:us]
+		
+		# The IP provider order. Valid symbols are :ip,:geo_plugin.
+		# As before, make sure you read up on relevant Terms of Use for each.
+		# Geokit::Geocoders::ip_provider_order = [:external,:geo_plugin,:ip]
 
 If you're using this gem with the [geokit-rails plugin](http://github.com/andre/geokit-rails/tree/master), the plugin
 creates a template with these settings and places it in `config/initializers/geokit_config.rb`.
@@ -123,7 +131,11 @@ creates a template with these settings and places it in `config/initializers/geo
 * Geoplugin.net -- another IP address geocoder
 
 ### The Multigeocoder
-* Multi Geocoder - provides failover for the physical location geocoders.
+Multi Geocoder - provides failover for the physical location geocoders, and also IP address geocoders. Its configured by setting Geokit::Geocoders::provider_order, and Geokit::Geocoders::ip_provider_order. You should call the Multi-Geocoder with its :geocode method, supplying one address parameter which is either a real street address, or an ip address. For example:
+
+		Geokit::Geocoders::MultiGeocoder.geocode("900 Sycamore Drive")
+
+		Geokit::Geocoders::MultiGeocoder.geocode("12.12.12.12")
 
 ## MULTIPLE RESULTS
 Some geocoding services will return multple results if the there isn't one clear result. 
@@ -165,6 +177,36 @@ geocoders.rb contains all the geocoder implemenations. All the gercoders
 inherit from a common base (class Geocoder) and implement the private method
 do_geocode.
 
+## WRITING YOUR OWN GEOCODERS
+
+If you would like to write your own geocoders, you can do so by requiring 'geokit' or 'geokit/geocoders.rb' in a new file and subclassing the base class (which is class "Geocoder").
+You must then also require such extenal file back in your main geokit configuration.
+
+	require "geokit"
+
+	module Geokit
+	  module Geocoders
+   		
+		# Should be overriden as Geokit::Geocoders::external_key in your configuration file
+	    @@external_key = 'REPLACE_WITH_YOUR_API_KEY'
+	    __define_accessors
+   
+		# Replace name 'External' (below) with the name of your custom geocoder class
+		# and use :external to specify this geocoder in your list of geocoders.
+	    class ExternalGeocoder < Geocoder
+	      private 
+	      def self.do_geocode(address)
+	        # Main geocoding method
+	      end
+
+	      def self.parse_http_resp(body) # :nodoc:
+	        # Helper method to parse http response. See geokit/geocoders.rb.
+	      end
+	    end
+	
+	  end
+	end
+
 ## GOOGLE GROUP
 
 Follow the Google Group for updates and discussion on Geokit: http://groups.google.com/group/geokit 

data/Rakefile

@@ -4,6 +4,14 @@ require 'rubygems'
 require 'hoe'
 require './lib/geokit.rb'
 
+# undefined method `empty?' for nil:NilClass
+# /Library/Ruby/Site/1.8/rubygems/specification.rb:886:in `validate' 
+class NilClass
+  def empty?
+    true
+  end
+end 
+
 project=Hoe.new('geokit', Geokit::VERSION) do |p|
   #p.rubyforge_name = 'geokit' # if different than lowercase project name
   p.developer('Andre Lewis', 'andre@earthcode.com')

data/geokit.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{geokit}
-  s.version = "1.3.0"
+  s.version = "1.3.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andre Lewis and Bill Eisenhauer"]
-  s.date = %q{2009-4-11}
+  s.date = %q{2009-04-11}
   s.description = %q{Geokit Gem}
   s.email = ["andre@earthcode.com / bill_eisenhauer@yahoo.com"]
   s.extra_rdoc_files = ["Manifest.txt", "README.markdown"]
@@ -18,7 +18,10 @@ Gem::Specification.new do |s|
   s.rubyforge_project = %q{geokit}
   s.rubygems_version = %q{1.3.1}
   s.summary = %q{none}
-  s.test_files = ["test/test_base_geocoder.rb", "test/test_bounds.rb", "test/test_ca_geocoder.rb", "test/test_geoloc.rb", "test/test_google_geocoder.rb", "test/test_latlng.rb", "test/test_multi_geocoder.rb", "test/test_us_geocoder.rb", "test/test_yahoo_geocoder.rb"]
+  s.test_files = ["test/test_base_geocoder.rb", "test/test_bounds.rb", "test/test_ca_geocoder.rb", "test/test_geoloc.rb", 
+  								"test/test_geoplugin_geocoder.rb", "test/test_google_geocoder.rb", "test/test_google_reverse_geocoder.rb", 
+  								"test/test_inflector.rb", "test/test_ipgeocoder.rb", "test/test_latlng.rb", "test/test_multi_geocoder.rb", 
+  								"test/test_multi_ip_geocoder.rb", "test/test_us_geocoder.rb", "test/test_yahoo_geocoder.rb"]
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
@@ -26,3 +29,4 @@ Gem::Specification.new do |s|
   end
 end
 
+

data/lib/geokit.rb

@@ -1,5 +1,5 @@
 module Geokit
-  VERSION = '1.3.0'
+  VERSION = '1.3.1'
   # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
   @@default_units = :miles
   @@default_formula = :sphere

data/lib/geokit/geocoders.rb

@@ -37,6 +37,10 @@ module Geokit
       '%' + $1.unpack('H2' * $1.size).join('%').upcase
       end.tr(' ', '+')
     end
+    
+    def camelize(str)
+      str.split('_').map {|w| w.capitalize}.join
+    end
   end  
   
   # Contains a range of geocoders:
@@ -70,38 +74,37 @@ module Geokit
     @@geocoder_ca = false
     @@geonames = false
     @@provider_order = [:google,:us]
+    @@ip_provider_order = [:geo_plugin,:ip]
     @@logger=Logger.new(STDOUT)
     @@logger.level=Logger::INFO
     @@domain = nil
     
-    def self.domain
-      @@domain
-    end
-
-    def self.domain=(obj)
-      @@domain = obj
-    end
-    
-    [:yahoo, :google, :geocoder_us, :geocoder_ca, :geonames, :provider_order, :timeout, 
-     :proxy_addr, :proxy_port, :proxy_user, :proxy_pass, :logger].each do |sym|
-      class_eval <<-EOS, __FILE__, __LINE__
-        def self.#{sym}
-          value = if defined?(#{sym.to_s.upcase})
-            #{sym.to_s.upcase}
-          else
-            @@#{sym}
-          end
-          if value.is_a?(Hash)
-            value = (self.domain.nil? ? nil : value[self.domain]) || value.values.first
-          end
-          value
+    def self.__define_accessors
+      class_variables.each do |v| 
+        sym = v.delete("@").to_sym
+        unless self.respond_to? sym
+          module_eval <<-EOS, __FILE__, __LINE__
+            def self.#{sym}
+              value = if defined?(#{sym.to_s.upcase})
+                #{sym.to_s.upcase}
+              else
+                @@#{sym}
+              end
+              if value.is_a?(Hash)
+                value = (self.domain.nil? ? nil : value[self.domain]) || value.values.first
+              end
+              value
+            end
+          
+            def self.#{sym}=(obj)
+              @@#{sym} = obj
+            end
+          EOS
         end
-
-        def self.#{sym}=(obj)
-          @@#{sym} = obj
-        end
-      EOS
+      end
     end
+
+    __define_accessors
     
     # Error which is thrown in the event a geocoding error occurs.
     class GeocodeError < StandardError; end
@@ -118,9 +121,8 @@ module Geokit
       # empty one with a failed success code.
       def self.geocode(address)  
         res = do_geocode(address)
-        return res.success? ? res : GeoLoc.new
+        return res.nil? ? GeoLoc.new : res
       end  
-      
       # Main method which calls the do_reverse_geocode template method which subclasses
       # are responsible for implementing.  Returns a populated GeoLoc or an
       # empty one with a failed success code.
@@ -478,7 +480,7 @@ module Geokit
         response = self.call_geocoder_service("http://www.geoplugin.net/xml.gp?ip=#{ip}")
         return response.is_a?(Net::HTTPSuccess) ? parse_xml(response.body) : GeoLoc.new
       rescue
-        logger.error "Caught an error during GeloPluginGeocoder geocoding call: "+$!
+        logger.error "Caught an error during GeoPluginGeocoder geocoding call: "+$!
         return GeoLoc.new
       end
 
@@ -491,7 +493,7 @@ module Geokit
         geo.country_code = xml.elements['//geoplugin_countryCode'].text
         geo.lat = xml.elements['//geoplugin_latitude'].text.to_f
         geo.lng = xml.elements['//geoplugin_longitude'].text.to_f
-        geo.success = !geo.city.empty?
+        geo.success = !!geo.city && !geo.city.empty?
         return geo
       end
     end
@@ -544,7 +546,8 @@ module Geokit
     # -------------------------------------------------------------------------------------------    
     
     # Provides methods to geocode with a variety of geocoding service providers, plus failover
-    # among providers in the order you configure.
+    # among providers in the order you configure. When 2nd parameter is set 'true', perform
+    # ip location lookup with 'address' as the ip address.
     # 
     # Goal:
     # - homogenize the results of multiple geocoders
@@ -552,18 +555,21 @@ module Geokit
     # Limitations:
     # - currently only provides the first result. Sometimes geocoders will return multiple results.
     # - currently discards the "accuracy" component of the geocoding calls
-    class MultiGeocoder < Geocoder 
-      private
+    class MultiGeocoder < Geocoder       
 
+      private
       # This method will call one or more geocoders in the order specified in the 
       # configuration until one of the geocoders work.
       # 
       # The failover approach is crucial for production-grade apps, but is rarely used.
       # 98% of your geocoding calls will be successful with the first call  
       def self.do_geocode(address)
-        Geokit::Geocoders::provider_order.each do |provider|
+        geocode_ip = !!/^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(address)
+        provider_order = geocode_ip ? Geokit::Geocoders::ip_provider_order : Geokit::Geocoders::provider_order
+        
+        provider_order.each do |provider|
           begin
-            klass = Geokit::Geocoders.const_get "#{provider.to_s.capitalize}Geocoder"
+            klass = Geokit::Geocoders.const_get "#{Geokit::Inflector::camelize(provider.to_s)}Geocoder"
             res = klass.send :geocode, address
             return res if res.success?
           rescue

data/lib/geokit/mappable.rb

@@ -403,7 +403,7 @@ module Geokit
 
     # Returns a string representation of the instance.
     def to_s
-      "Provider: #{provider}\n Street: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
+      "Provider: #{provider}\nStreet: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
     end
   end
   

data/test/test_multi_ip_geocoder.rb

@@ -0,0 +1,38 @@
+require File.join(File.dirname(__FILE__), 'test_base_geocoder')
+
+Geokit::Geocoders::ip_provider_order=[:geo_plugin,:ip]
+
+class MultiIpGeocoderTest < BaseGeocoderTest #:nodoc: all
+  
+  def setup
+    @ip_address = '10.10.10.10'
+    @success = Geokit::GeoLoc.new({:city=>"SAN FRANCISCO", :state=>"CA", :country_code=>"US", :lat=>37.7742, :lng=>-122.417068})
+    @success.success = true
+    @failure = Geokit::GeoLoc.new
+  end
+  
+  def test_successful_first
+    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address).returns(@success)
+    assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
+  end
+  
+  def test_failover
+    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address).returns(@failure)
+    Geokit::Geocoders::IpGeocoder.expects(:geocode).with(@ip_address).returns(@success)
+    assert_equal @success, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
+  end
+  
+  def test_failure
+    Geokit::Geocoders::GeoPluginGeocoder.expects(:geocode).with(@ip_address).returns(@failure)
+    Geokit::Geocoders::IpGeocoder.expects(:geocode).with(@ip_address).returns(@failure)
+    assert_equal @failure, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
+  end
+  
+  def test_invalid_provider
+    temp = Geokit::Geocoders::ip_provider_order
+    Geokit::Geocoders.ip_provider_order = [:bogus]
+    assert_equal @failure, Geokit::Geocoders::MultiGeocoder.geocode(@ip_address)
+    Geokit::Geocoders.ip_provider_order = temp
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: geokit
 version: !ruby/object:Gem::Version 
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors: 
 - Andre Lewis
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-11 00:00:00 -07:00
+date: 2009-05-22 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -20,9 +20,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.9.0
+        version: 1.12.2
     version: 
-description: 
+description: ""
 email: 
 - andre@earthcode.com
 executables: []
@@ -57,6 +57,8 @@ files:
 - test/test_yahoo_geocoder.rb
 has_rdoc: true
 homepage: 
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --main
@@ -78,9 +80,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: geokit
-rubygems_version: 1.3.1
+rubygems_version: 1.3.2
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Geokit provides geocoding and distance calculation in an easy-to-use API
 test_files: 
 - test/test_base_geocoder.rb
@@ -94,5 +96,6 @@ test_files:
 - test/test_ipgeocoder.rb
 - test/test_latlng.rb
 - test/test_multi_geocoder.rb
+- test/test_multi_ip_geocoder.rb
 - test/test_us_geocoder.rb
 - test/test_yahoo_geocoder.rb