andre-geokit 1.1.0 → 1.2.0

data/Manifest.txt

@@ -1,13 +1,12 @@
 .loadpath
 .project
-History.txt
 Manifest.txt
 README.markdown
 Rakefile
 geokit.gemspec
-lib/geocoders.rb
+lib/geokit/geocoders.rb
 lib/geokit.rb
-lib/mappable.rb
+lib/geokit/mappable.rb
 test/test_base_geocoder.rb
 test/test_bounds.rb
 test/test_ca_geocoder.rb

data/README.markdown

@@ -8,13 +8,10 @@ The Geokit gem provides the following:
 
  * Distance calculations between two points on the earth. Calculate the distance in miles or KM, 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.
+ * Rectangular bounds calculations: is a point within a given rectangular bounds?
+ * Heading and midpoint calculations
 
-Combine this with gem with the geokit-rails plugin to get location-based finders for your Rails app. Plugins for other web frameworks and ORMs will provide similar functionality.
-
-
-## FEATURES/PROBLEMS:
-
-* none currently
+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.
 
 ## SYNOPSIS:
 
@@ -30,21 +27,103 @@ Combine this with gem with the geokit-rails plugin to get location-based finders
 		 => 1.21120007413626
 		irb> a.heading_to(b)
 		=> 244.959832435678
+		irb(main):006:0> c=a.midpoint_to(b)      # what's halfway from a to b?
+		irb> c.ll
+		=> "37.7899239257175,-122.406153503469"
+		irb(main):008:0> d=c.endpoint(90,10)     # what's 10 miles to the east of c?
+		irb> d.ll
+		=> "37.7897825005142,-122.223214776155"
 
-
-## REQUIREMENTS:
-
+FYI, that `.ll` method means "latitude longitude".
 
 ## INSTALL:
 
   * gem sources -a http://gems.github.com
-  * sudo gem install
+  * sudo gem install andre-geokit-gem
+
+## Configuration
+
+If you're using this gem by itself, here's how to set configurations:
+
+		# These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
+		Geokit::default_units = :miles
+		Geokit::default_formula = :sphere
+		
+		# This is the timeout value in seconds to be used for calls to the geocoder web
+		# services.  For no timeout at all, comment out the setting.  The timeout unit
+		# is in seconds. 
+		Geokit::Geocoders::timeout = 3
+		
+		# These settings are used if web service calls must be routed through a proxy.
+		# These setting can be nil if not needed, otherwise, addr and port must be 
+		# filled in at a minimum.  If the proxy requires authentication, the username
+		# and password can be provided as well.
+		Geokit::Geocoders::proxy_addr = nil
+		Geokit::Geocoders::proxy_port = nil
+		Geokit::Geocoders::proxy_user = nil
+		Geokit::Geocoders::proxy_pass = nil
+		
+		# This is your yahoo application key for the Yahoo Geocoder.
+		# See http://developer.yahoo.com/faq/index.html#appid
+		# and http://developer.yahoo.com/maps/rest/V1/geocode.html
+		Geokit::Geocoders::yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
+		    
+		# This is your Google Maps geocoder key. 
+		# See http://www.google.com/apis/maps/signup.html
+		# and http://www.google.com/apis/maps/documentation/#Geocoding_Examples
+		Geokit::Geocoders::google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+		    
+		# This is your username and password for geocoder.us.
+		# To use the free service, the value can be set to nil or false.  For 
+		# usage tied to an account, the value should be set to username:password.
+		# See http://geocoder.us
+		# and http://geocoder.us/user/signup
+		Geokit::Geocoders::geocoder_us = false 
+		
+		# This is your authorization key for geocoder.ca.
+		# To use the free service, the value can be set to nil or false.  For 
+		# usage tied to an account, set the value to the key obtained from
+		# Geocoder.ca.
+		# See http://geocoder.ca
+		# and http://geocoder.ca/?register=1
+		Geokit::Geocoders::geocoder_ca = false
+		
+		# 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.
+		# Be aware that there are Terms of Use restrictions on how you can use the 
+		# 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]
+
+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.
+
+## NOTES ON WHAT'S WHERE
+
+mappable.rb contains the Mappable module, which provides basic
+distance calculation methods, i.e., calculating the distance
+between two points. 
+
+mappable.rb also contains LatLng, GeoLoc, and Bounds.
+LatLng is a simple container for latitude and longitude, but 
+it's made more powerful by mixing in the above-mentioned Mappable
+module -- therefore, you can calculate easily the distance between two
+LatLng ojbects with `distance = first.distance_to(other)`
+
+GeoLoc (also in mappable.rb) represents an address or location which
+has been geocoded. You can get the city, zipcode, street address, etc.
+from a GeoLoc object. GeoLoc extends LatLng, so you also get lat/lng
+AND the Mappable modeule goodness for free.
+
+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:
 
 (The MIT License)
 
-Copyright (c) 2007-2008 Andre Lewis and Bill Eisenhauer
+Copyright (c) 2007-2009 Andre Lewis and Bill Eisenhauer
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/geokit.rb

@@ -1,5 +1,5 @@
 module Geokit
-  VERSION = '1.0.0'
+  VERSION = '1.2.0'
   # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
   @@default_units = :miles
   @@default_formula = :sphere
@@ -21,8 +21,8 @@ module Geokit
   end
 end
 
-require 'geocoders'
-require 'mappable'
+require 'geokit/geocoders'
+require 'geokit/mappable'
 
 # make old-style module name "GeoKit" equivilent to new-style "Geokit"
 module GeoKit

data/lib/{geocoders.rb → geokit/geocoders.rb}

@@ -59,11 +59,12 @@ module Geokit
     @@google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
     @@geocoder_us = false
     @@geocoder_ca = false
+    @@geonames = false
     @@provider_order = [:google,:us]
     @@logger=Logger.new(STDOUT)
     @@logger.level=Logger::INFO
     
-    [:yahoo, :google, :geocoder_us, :geocoder_ca, :provider_order, :timeout, 
+    [: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}
@@ -111,9 +112,16 @@ module Geokit
       private
       
       # Wraps the geocoder call around a proxy if necessary.
-      def self.do_get(url)     
-        return Net::HTTP::Proxy(Geokit::Geocoders::proxy_addr, Geokit::Geocoders::proxy_port,
-            Geokit::Geocoders::proxy_user, Geokit::Geocoders::proxy_pass).get_response(URI.parse(url))          
+      def self.do_get(url) 
+        uri = URI.parse(url)
+        req = Net::HTTP::Get.new(url)
+        req.basic_auth(uri.user, uri.password) if uri.userinfo
+        res = Net::HTTP::Proxy(GeoKit::Geocoders::proxy_addr,
+                GeoKit::Geocoders::proxy_port,
+                GeoKit::Geocoders::proxy_user,
+                GeoKit::Geocoders::proxy_pass).start(uri.host, uri.port) { |http| http.request(req) }
+
+        return res
       end
       
       # Adds subclass' geocode method making it conveniently available through 
@@ -280,19 +288,32 @@ module Geokit
     class UsGeocoder < Geocoder
 
       private
-
-      # For now, the geocoder_method will only geocode full addresses -- not zips or cities in isolation
       def self.do_geocode(address)
         address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
-        url = "http://"+(Geokit::Geocoders::geocoder_us || '')+"geocoder.us/service/csv/geocode?address=#{Geokit::Inflector::url_escape(address_str)}"
+        
+        query = (address_str =~ /^\d{5}(?:-\d{4})?$/ ? "zip" : "address") + "=#{Geokit::Inflector::url_escape(address_str)}"
+        url = if GeoKit::Geocoders::geocoder_us         
+          "http://#{GeoKit::Geocoders::geocoder_us}@geocoder.us/member/service/csv/geocode"
+        else
+          "http://geocoder.us/service/csv/geocode"
+        end
+        
+        url = "#{url}?#{query}"  
         res = self.call_geocoder_service(url)
+        
         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
         data = res.body
         logger.debug "Geocoder.us geocoding. Address: #{address}. Result: #{data}"
         array = data.chomp.split(',')
-
-        if array.length == 6  
+        
+        if array.length == 5
           res=GeoLoc.new
+          res.lat,res.lng,res.city,res.state,res.zip=array
+          res.country_code='US'
+          res.success=true
+          return res
+        elsif array.length == 6  
+          res=GeoLoc.new 
           res.lat,res.lng,res.street_address,res.city,res.state,res.zip=array
           res.country_code='US'
           res.success=true 
@@ -304,6 +325,7 @@ module Geokit
         rescue 
           logger.error "Caught an error during geocoder.us geocoding call: "+$!
           return GeoLoc.new
+
       end
     end
     
@@ -350,6 +372,54 @@ module Geokit
           return GeoLoc.new
       end
     end
+
+    class GeonamesGeocoder < Geocoder
+
+      private 
+      
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        # geonames need a space seperated search string
+        address_str.gsub!(/,/, " ")
+        params = "/postalCodeSearch?placename=#{Geokit::Inflector::url_escape(address_str)}&maxRows=10"
+        
+        if(GeoKit::Geocoders::geonames)
+          url = "http://ws.geonames.net#{params}&username=#{GeoKit::Geocoders::geonames}"
+        else
+          url = "http://ws.geonames.org#{params}"
+        end
+        
+        res = self.call_geocoder_service(url)
+        
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        
+        xml=res.body
+        logger.debug "Geonames geocoding. Address: #{address}. Result: #{xml}"
+        doc=REXML::Document.new(xml)
+        
+        if(doc.elements['//geonames/totalResultsCount'].text.to_i > 0)
+          res=GeoLoc.new
+        
+          # only take the first result
+          res.lat=doc.elements['//code/lat'].text if doc.elements['//code/lat']
+          res.lng=doc.elements['//code/lng'].text if doc.elements['//code/lng']
+          res.country_code=doc.elements['//code/countryCode'].text if doc.elements['//code/countryCode']
+          res.provider='genomes'  
+          res.city=doc.elements['//code/name'].text if doc.elements['//code/name']
+          res.state=doc.elements['//code/adminName1'].text if doc.elements['//code/adminName1']
+          res.zip=doc.elements['//code/postalcode'].text if doc.elements['//code/postalcode']
+          res.success=true
+          return res
+        else 
+          logger.info "Geonames was unable to geocode address: "+address
+          return GeoLoc.new
+        end
+        
+        rescue
+          logger.error "Caught an error during Geonames geocoding call: "+$!
+      end
+    end
     
     # Provides methods to geocode with a variety of geocoding service providers, plus failover
     # among providers in the order you configure.

data/lib/{mappable.rb → geokit/mappable.rb}

@@ -353,7 +353,7 @@ module Geokit
     
     # provide sw and ne to instantiate a new Bounds instance
     def initialize(sw,ne)
-      raise ArguementError if !(sw.is_a?(Geokit::LatLng) && ne.is_a?(Geokit::LatLng))
+      raise ArgumentError if !(sw.is_a?(Geokit::LatLng) && ne.is_a?(Geokit::LatLng))
       @sw,@ne=sw,ne
     end
     
@@ -410,7 +410,7 @@ module Geokit
         Geokit::Bounds.new(sw,ne)
       end
       
-      # Takes two main combinations of arguements to create a bounds:
+      # Takes two main combinations of arguments to create a bounds:
       # point,point   (this is the only one which takes two arguments
       # [point,point]
       # . . . where a point is anything LatLng#normalize can handle (which is quite a lot)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: andre-geokit
 version: !ruby/object:Gem::Version 
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Andre Lewis and Bill Eisenhauer
@@ -29,17 +29,15 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- History.txt
 - Manifest.txt
 - README.markdown
 files: 
-- History.txt
 - Manifest.txt
 - README.markdown
 - Rakefile
-- lib/geocoders.rb
+- lib/geokit/geocoders.rb
 - lib/geokit.rb
-- lib/mappable.rb
+- lib/geokit/mappable.rb
 - test/test_base_geocoder.rb
 - test/test_bounds.rb
 - test/test_ca_geocoder.rb

data/History.txt

@@ -1,5 +0,0 @@
-=== 1.0.0 / 2008-11-30
-
-* Extracted geocoding and mappable functionality and tests from original GeoKit Rails plugin.
-
-