andre-geokit 1.2.2 → 1.2.3

data/README.markdown

@@ -1,20 +1,24 @@
-# Geokit gem
+## GEOKIT GEM DESCRIPTION
 
-* Geokit Documentation at Rubyforge [http://geokit.rubyforge.org](http://geokit.rubyforge.org).
-* Repository at Github: [http://github.com/andre/geokit-gem/tree/master](http://github.com/andre/geokit-gem/tree/master).
-
-## DESCRIPTION:
-
-The Geokit gem provides the following:
+The Geokit gem provides:
 
  * Distance calculations between two points on the earth. Calculate the distance in miles, kilometers, or nautical miles, with all the trigonometry abstracted away by GeoKit.
- * Geocoding from multiple providers. It currently supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and it provides a uniform response structure from all of them. It also provides a fail-over mechanism, in case your input fails to geocode in one service.
+ * Geocoding from multiple providers. It currently supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and it provides a uniform response structure from all of them. 
+   It also provides a fail-over mechanism, in case your input fails to geocode in one service.
  * Rectangular bounds calculations: is a point within a given rectangular bounds?
  * Heading and midpoint calculations
 
-Combine this with gem with the [geokit-rails plugin](http://github.com/andre/geokit-rails/tree/master) to get location-based finders for your Rails app. Plugins for other web frameworks and ORMs will provide similar functionality.
+Combine this with gem with the [geokit-rails plugin](http://github.com/andre/geokit-rails/tree/master) to get location-based finders for your Rails app.
+
+* Geokit Documentation at Rubyforge [http://geokit.rubyforge.org](http://geokit.rubyforge.org).
+* Repository at Github: [http://github.com/andre/geokit-gem/tree/master](http://github.com/andre/geokit-gem/tree/master).
+
+## INSTALL
 
-## SYNOPSIS:
+    gem sources -a http://gems.github.com
+    sudo gem install andre-geokit
+
+## QUICK START
 
 		irb> require 'rubygems'
 		irb> require 'geokit'
@@ -37,14 +41,9 @@ Combine this with gem with the [geokit-rails plugin](http://github.com/andre/geo
 
 FYI, that `.ll` method means "latitude longitude".
 
-See the RDOC more more ... there is also operations on rectangular bounds (e.g., determining if a point is within bounds, find the center, etc).
-
-## INSTALL:
+See the RDOC more more ... there are also operations on rectangular bounds (e.g., determining if a point is within bounds, find the center, etc).
 
-  * gem sources -a http://gems.github.com
-  * sudo gem install andre-geokit
-
-## Configuration
+## CONFIGURATION
 
 If you're using this gem by itself, here's how to set configurations:
 
@@ -99,7 +98,26 @@ If you're using this gem by itself, here's how to set configurations:
 		# geocoder you are going to use.
 		Geokit::Geocoders::provider_order = [:google,:us]
 
-If you're using this gem with the [geokit-rails plugin](http://github.com/andre/geokit-rails/tree/master), a template with these settings gets placed in your app's config/initializers directory.
+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`.
+
+## SUPPORTED GEOCODERS
+
+### "regular" address geocoders 
+* Yahoo Geocoder - requires an API key.
+* Geocoder.us - may require authentication if performing more than the free request limit.
+* Geocoder.ca - for Canada; may require authentication as well.
+* Geonames - a free geocoder
+
+### address geocoders that also provide reverse geocoding 
+* Google Geocoder - requires an API key.
+
+### IP address geocoders 
+* IP Geocoder - geocodes an IP address using hostip.info's web service.
+* Geoplugin.net -- another IP address geocoder
+
+### The Multigeocoder
+* Multi Geocoder - provides failover for the physical location geocoders.
 
 ## NOTES ON WHAT'S WHERE
 
@@ -122,7 +140,7 @@ geocoders.rb contains all the geocoder implemenations. All the gercoders
 inherit from a common base (class Geocoder) and implement the private method
 do_geocode.
 
-## LICENSE:
+## LICENSE
 
 (The MIT License)
 

data/lib/geokit/geocoders.rb

@@ -38,17 +38,26 @@ module Geokit
       end.tr(' ', '+')
     end
   end  
-  # Contains a set of geocoders which can be used independently if desired.  The list contains:
+  
+  # Contains a range of geocoders:
   # 
-  # * Google Geocoder - requires an API key.
+  # ### "regular" address geocoders 
   # * Yahoo Geocoder - requires an API key.
   # * Geocoder.us - may require authentication if performing more than the free request limit.
   # * Geocoder.ca - for Canada; may require authentication as well.
+  # * Geonames - a free geocoder
+  #
+  # ### address geocoders that also provide reverse geocoding 
+  # * Google Geocoder - requires an API key.
+  #  
+  # ### IP address geocoders 
   # * IP Geocoder - geocodes an IP address using hostip.info's web service.
+  # * Geoplugin.net -- another IP address geocoder
+  #
+  # ### The Multigeocoder
   # * Multi Geocoder - provides failover for the physical location geocoders.
   # 
-  # Some configuration is required for these geocoders and can be located in the environment
-  # configuration files.
+  # Some of these geocoders require configuration. You don't have to provide it here. See the README.
   module Geocoders
     @@proxy_addr = nil
     @@proxy_port = nil
@@ -83,6 +92,10 @@ module Geokit
     
     # Error which is thrown in the event a geocoding error occurs.
     class GeocodeError < StandardError; end
+
+    # -------------------------------------------------------------------------------------------
+    # Geocoder Base class -- every geocoder should inherit from this
+    # -------------------------------------------------------------------------------------------    
     
     # The Geocoder base class which defines the interface to be used by all
     # other geocoders.
@@ -151,6 +164,10 @@ module Geokit
         class_eval(src)
       end
     end
+
+    # -------------------------------------------------------------------------------------------
+    # "Regular" Address geocoders
+    # -------------------------------------------------------------------------------------------    
     
     # Geocoder CA geocoder implementation.  Requires the Geokit::Geocoders::GEOCODER_CA variable to
     # contain true or false based upon whether authentication is to occur.  Conforms to the 
@@ -203,115 +220,7 @@ module Geokit
       end
     end    
     
-    # Google geocoder implementation.  Requires the Geokit::Geocoders::GOOGLE variable to
-    # contain a Google API key.  Conforms to the interface set by the Geocoder class.
-    class GoogleGeocoder < Geocoder
-
-      private 
-      
-      # Template method which does the reverse-geocode lookup.
-      def self.do_reverse_geocode(latlng)
-        latlng=LatLng.normalize(latlng)
-        res = self.call_geocoder_service("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(latlng.ll)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
-  #        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8"))
-        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
-        xml = res.body
-        logger.debug "Google reverse-geocoding. LL: #{latlng.ll}. Result: #{xml}"
-        return self.xml2GeoLoc(xml)        
-      end
-
-      # Template method which does the geocode lookup.
-      def self.do_geocode(address)
-        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
-        res = self.call_geocoder_service("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
-#        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8"))
-        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
-        xml = res.body
-        logger.debug "Google geocoding. Address: #{address}. Result: #{xml}"
-        return self.xml2GeoLoc(xml)        
-      end
-      
-      def self.xml2GeoLoc(xml)
-        doc=REXML::Document.new(xml)
-
-        if doc.elements['//kml/Response/Status/code'].text == '200'
-          res = GeoLoc.new
-          coordinates=doc.elements['//coordinates'].text.to_s.split(',')
-
-          #basics
-          res.lat=coordinates[1]
-          res.lng=coordinates[0]
-          res.country_code=doc.elements['//CountryNameCode'].text if doc.elements['//CountryNameCode']
-          res.provider='google'
-
-          #extended -- false if not not available
-          res.city = doc.elements['//LocalityName'].text if doc.elements['//LocalityName']
-          res.state = doc.elements['//AdministrativeAreaName'].text if doc.elements['//AdministrativeAreaName']
-          res.full_address = doc.elements['//address'].text if doc.elements['//address'] # google provides it
-          res.zip = doc.elements['//PostalCodeNumber'].text if doc.elements['//PostalCodeNumber']
-          res.street_address = doc.elements['//ThoroughfareName'].text if doc.elements['//ThoroughfareName']
-          # Translate accuracy into Yahoo-style token address, street, zip, zip+4, city, state, country
-          # For Google, 1=low accuracy, 8=high accuracy
-          # old way -- address_details=doc.elements['//AddressDetails','urn:oasis:names:tc:ciq:xsdschema:xAL:2.0']
-          address_details=doc.elements['//*[local-name() = "AddressDetails"]']
-          accuracy = address_details ? address_details.attributes['Accuracy'].to_i : 0
-          res.precision=%w{unknown country state state city zip zip+4 street address}[accuracy]
-          res.success=true
-          
-          return res
-        else 
-          logger.info "Google was unable to geocode address: "+address
-          return GeoLoc.new
-        end
-
-        rescue
-          logger.error "Caught an error during Google geocoding call: "+$!
-          return GeoLoc.new
-      end  
-    end
-    
-    # Provides geocoding based upon an IP address.  The underlying web service is a hostip.info
-    # which sources their data through a combination of publicly available information as well
-    # as community contributions.
-    class IpGeocoder < Geocoder 
-
-      private 
-
-      # Given an IP address, returns a GeoLoc instance which contains latitude,
-      # longitude, city, and country code.  Sets the success attribute to false if the ip 
-      # parameter does not match an ip address.  
-      def self.do_geocode(ip)
-        return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
-        url = "http://api.hostip.info/get_html.php?ip=#{ip}&position=true"
-        response = self.call_geocoder_service(url)
-        response.is_a?(Net::HTTPSuccess) ? parse_body(response.body) : GeoLoc.new
-      rescue
-        logger.error "Caught an error during HostIp geocoding call: "+$!
-        return GeoLoc.new
-      end
-
-      # Converts the body to YAML since its in the form of:
-      #
-      # Country: UNITED STATES (US)
-      # City: Sugar Grove, IL
-      # Latitude: 41.7696
-      # Longitude: -88.4588
-      #
-      # then instantiates a GeoLoc instance to populate with location data.
-      def self.parse_body(body) # :nodoc:
-        yaml = YAML.load(body)
-        res = GeoLoc.new
-        res.provider = 'hostip'
-        res.city, res.state = yaml['City'].split(', ')
-        country, res.country_code = yaml['Country'].split(' (')
-        res.lat = yaml['Latitude'] 
-        res.lng = yaml['Longitude']
-        res.country_code.chop!
-        res.success = res.city != "(Private Address)"
-        res
-      end
-    end
-    
+        
     # Geocoder Us geocoder implementation.  Requires the Geokit::Geocoders::GEOCODER_US variable to
     # contain true or false based upon whether authentication is to occur.  Conforms to the 
     # interface set by the Geocoder class.
@@ -403,6 +312,8 @@ module Geokit
       end
     end
 
+    # Another geocoding web service
+    # http://www.geonames.org
     class GeonamesGeocoder < Geocoder
 
       private 
@@ -450,6 +361,154 @@ module Geokit
           logger.error "Caught an error during Geonames geocoding call: "+$!
       end
     end
+
+    # -------------------------------------------------------------------------------------------
+    # Address geocoders that also provide reverse geocoding
+    # -------------------------------------------------------------------------------------------
+
+    # Google geocoder implementation.  Requires the Geokit::Geocoders::GOOGLE variable to
+    # contain a Google API key.  Conforms to the interface set by the Geocoder class.
+    class GoogleGeocoder < Geocoder
+
+      private 
+      
+      # Template method which does the reverse-geocode lookup.
+      def self.do_reverse_geocode(latlng) 
+        latlng=LatLng.normalize(latlng)
+        res = self.call_geocoder_service("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(latlng.ll)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
+        #        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?ll=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8"))
+        return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+        xml = res.body
+        logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{xml}"
+        return self.xml2GeoLoc(xml)        
+      end  
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        res = self.call_geocoder_service("http://maps.google.com/maps/geo?q=#{Geokit::Inflector::url_escape(address_str)}&output=xml&key=#{Geokit::Geocoders::google}&oe=utf-8")
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        logger.debug "Google geocoding. Address: #{address}. Result: #{xml}"
+        return self.xml2GeoLoc(xml)        
+      end
+      
+      def self.xml2GeoLoc(xml)
+        doc=REXML::Document.new(xml)
+
+        if doc.elements['//kml/Response/Status/code'].text == '200'
+          res = GeoLoc.new
+          coordinates=doc.elements['//coordinates'].text.to_s.split(',')
+
+          #basics
+          res.lat=coordinates[1]
+          res.lng=coordinates[0]
+          res.country_code=doc.elements['//CountryNameCode'].text if doc.elements['//CountryNameCode']
+          res.provider='google'
+
+          #extended -- false if not not available
+          res.city = doc.elements['//LocalityName'].text if doc.elements['//LocalityName']
+          res.state = doc.elements['//AdministrativeAreaName'].text if doc.elements['//AdministrativeAreaName']
+          res.full_address = doc.elements['//address'].text if doc.elements['//address'] # google provides it
+          res.zip = doc.elements['//PostalCodeNumber'].text if doc.elements['//PostalCodeNumber']
+          res.street_address = doc.elements['//ThoroughfareName'].text if doc.elements['//ThoroughfareName']
+          # Translate accuracy into Yahoo-style token address, street, zip, zip+4, city, state, country
+          # For Google, 1=low accuracy, 8=high accuracy
+          # old way -- address_details=doc.elements['//AddressDetails','urn:oasis:names:tc:ciq:xsdschema:xAL:2.0']
+          address_details=doc.elements['//*[local-name() = "AddressDetails"]']
+          accuracy = address_details ? address_details.attributes['Accuracy'].to_i : 0
+          res.precision=%w{unknown country state state city zip zip+4 street address}[accuracy]
+          res.success=true
+          
+          return res
+        else 
+          logger.info "Google was unable to geocode address: "+address
+          return GeoLoc.new
+        end
+
+        rescue
+          logger.error "Caught an error during Google geocoding call: "+$!
+          return GeoLoc.new
+      end  
+    end
+
+
+    # -------------------------------------------------------------------------------------------
+    # IP Geocoders
+    # -------------------------------------------------------------------------------------------
+  
+    # Provides geocoding based upon an IP address.  The underlying web service is geoplugin.net
+    class GeoPluginGeocoder < Geocoder
+      private
+      
+      def self.do_geocode(ip)
+        return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
+        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: "+$!
+        return GeoLoc.new
+      end
+
+      def self.parse_xml(xml)
+        xml = REXML::Document.new(xml)
+        geo = GeoLoc.new
+        geo.provider='geoPlugin'
+        geo.city = xml.elements['//geoplugin_city'].text
+        geo.state = xml.elements['//geoplugin_region'].text
+        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?
+        return geo
+      end
+    end
+
+    # Provides geocoding based upon an IP address.  The underlying web service is a hostip.info
+    # which sources their data through a combination of publicly available information as well
+    # as community contributions.
+    class IpGeocoder < Geocoder 
+
+      private 
+
+      # Given an IP address, returns a GeoLoc instance which contains latitude,
+      # longitude, city, and country code.  Sets the success attribute to false if the ip 
+      # parameter does not match an ip address.  
+      def self.do_geocode(ip)
+        return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
+        url = "http://api.hostip.info/get_html.php?ip=#{ip}&position=true"
+        response = self.call_geocoder_service(url)
+        response.is_a?(Net::HTTPSuccess) ? parse_body(response.body) : GeoLoc.new
+      rescue
+        logger.error "Caught an error during HostIp geocoding call: "+$!
+        return GeoLoc.new
+      end
+
+      # Converts the body to YAML since its in the form of:
+      #
+      # Country: UNITED STATES (US)
+      # City: Sugar Grove, IL
+      # Latitude: 41.7696
+      # Longitude: -88.4588
+      #
+      # then instantiates a GeoLoc instance to populate with location data.
+      def self.parse_body(body) # :nodoc:
+        yaml = YAML.load(body)
+        res = GeoLoc.new
+        res.provider = 'hostip'
+        res.city, res.state = yaml['City'].split(', ')
+        country, res.country_code = yaml['Country'].split(' (')
+        res.lat = yaml['Latitude'] 
+        res.lng = yaml['Longitude']
+        res.country_code.chop!
+        res.success = !(res.city =~ /\(.+\)/)
+        res
+      end
+    end
+
+    # -------------------------------------------------------------------------------------------
+    # The Multi Geocoder
+    # -------------------------------------------------------------------------------------------    
     
     # Provides methods to geocode with a variety of geocoding service providers, plus failover
     # among providers in the order you configure.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: andre-geokit
 version: !ruby/object:Gem::Version 
-  version: 1.2.2
+  version: 1.2.3
 platform: ruby
 authors: 
 - Andre Lewis and Bill Eisenhauer