artofmission-Geokit 1.0.1

data/lib/geo_kit/defaults.rb

@@ -0,0 +1,21 @@
+module GeoKit
+  # These defaults are used in GeoKit::Mappable.distance_to and in acts_as_mappable
+  @@default_units = :miles
+  @@default_formula = :sphere
+
+  [:default_units, :default_formula].each do |sym|
+    class_eval <<-EOS, __FILE__, __LINE__
+      def self.#{sym}
+        if defined?(#{sym.to_s.upcase})
+          #{sym.to_s.upcase}
+        else
+          @@#{sym}
+        end
+      end
+
+      def self.#{sym}=(obj)
+        @@#{sym} = obj
+      end
+    EOS
+  end
+end

data/lib/geo_kit/geocoders.rb

@@ -0,0 +1,348 @@
+require 'net/http'
+require 'rexml/document'
+require 'yaml'
+require 'timeout'
+
+module GeoKit
+  # Contains a set of geocoders which can be used independently if desired.  The list contains:
+  # 
+  # * Google Geocoder - requires an API key.
+  # * 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.
+  # * IP Geocoder - geocodes an IP address using hostip.info's web service.
+  # * 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.
+  module Geocoders
+    @@proxy_addr = nil
+    @@proxy_port = nil
+    @@proxy_user = nil
+    @@proxy_pass = nil
+    @@timeout = nil    
+    @@yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
+    @@google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+    @@geocoder_us = false
+    @@geocoder_ca = false
+    @@provider_order = [:google,:us]
+    
+    [:yahoo, :google, :geocoder_us, :geocoder_ca, :provider_order, :timeout, 
+     :proxy_addr, :proxy_port, :proxy_user, :proxy_pass].each do |sym|
+      class_eval <<-EOS, __FILE__, __LINE__
+        def self.#{sym}
+          if defined?(#{sym.to_s.upcase})
+            #{sym.to_s.upcase}
+          else
+            @@#{sym}
+          end
+        end
+
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+    
+    # Error which is thrown in the event a geocoding error occurs.
+    class GeocodeError < StandardError; end
+    
+    # The Geocoder base class which defines the interface to be used by all
+    # other geocoders.
+    class Geocoder   
+      # Main method which calls the do_geocode template method which subclasses
+      # are responsible for implementing.  Returns a populated GeoLoc or an
+      # empty one with a failed success code.
+      def self.geocode(address)  
+        res = do_geocode(address)
+        return res.success ? res : GeoLoc.new
+      end  
+      
+      # Call the geocoder service using the timeout if configured.
+      def self.call_geocoder_service(url)
+        timeout(GeoKit::Geocoders::timeout) { return self.do_get(url) } if GeoKit::Geocoders::timeout        
+        return self.do_get(url)
+      rescue TimeoutError
+        return nil  
+      end
+
+      protected
+
+      def self.logger() RAILS_DEFAULT_LOGGER; end
+      
+      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))          
+      end
+      
+      # Adds subclass' geocode method making it conveniently available through 
+      # the base class.
+      def self.inherited(clazz)
+        class_name = clazz.name.split('::').last
+        src = <<-END_SRC
+          def self.#{class_name.underscore}(address)
+            #{class_name}.geocode(address)
+          end
+        END_SRC
+        class_eval(src)
+      end
+    end
+    
+    # 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 
+    # interface set by the Geocoder class.
+    #
+    # Returns a response like:
+    # <?xml version="1.0" encoding="UTF-8" ?>
+    # <geodata>
+    #   <latt>49.243086</latt>
+    #   <longt>-123.153684</longt>
+    # </geodata>
+    class CaGeocoder < Geocoder
+
+      private
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        raise ArgumentError('Geocoder.ca requires a GeoLoc argument') unless address.is_a?(GeoLoc)
+        url = construct_request(address)
+        res = self.call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        logger.debug "Geocoder.ca geocoding. Address: #{address}. Result: #{xml}"
+        # Parse the document.
+        doc = REXML::Document.new(xml)    
+        address.lat = doc.elements['//latt'].text
+        address.lng = doc.elements['//longt'].text
+        address.success = true
+        return address
+      rescue
+        logger.error "Caught an error during Geocoder.ca geocoding call: "+$!
+        return GeoLoc.new  
+      end  
+
+      # Formats the request in the format acceptable by the CA geocoder.
+      def self.construct_request(location)
+        url = ""
+        url += add_ampersand(url) + "stno=#{location.street_number}" if location.street_address
+        url += add_ampersand(url) + "addresst=#{CGI.escape(location.street_name)}" if location.street_address
+        url += add_ampersand(url) + "city=#{CGI.escape(location.city)}" if location.city
+        url += add_ampersand(url) + "prov=#{location.state}" if location.state
+        url += add_ampersand(url) + "postal=#{location.zip}" if location.zip
+        url += add_ampersand(url) + "auth=#{GeoKit::Geocoders::geocoder_ca}" if GeoKit::Geocoders::geocoder_ca
+        url += add_ampersand(url) + "geoit=xml"
+        'http://geocoder.ca/?' + url
+      end
+
+      def self.add_ampersand(url)
+        url && url.length > 0 ? "&" : ""
+      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 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=#{CGI.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=#{CGI.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}"
+        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
+          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.
+    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=#{CGI.escape(address_str)}"
+        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  
+          res=GeoLoc.new
+          res.lat,res.lng,res.street_address,res.city,res.state,res.zip=array
+          res.country_code='US'
+          res.success=true 
+          return res
+        else 
+          logger.info "geocoder.us was unable to geocode address: "+address
+          return GeoLoc.new      
+        end
+        rescue 
+          logger.error "Caught an error during geocoder.us geocoding call: "+$!
+          return GeoLoc.new
+      end
+    end
+    
+    # Yahoo geocoder implementation.  Requires the GeoKit::Geocoders::YAHOO variable to
+    # contain a Yahoo API key.  Conforms to the interface set by the Geocoder class.
+    class YahooGeocoder < 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
+        url="http://api.local.yahoo.com/MapsService/V1/geocode?appid=#{GeoKit::Geocoders::yahoo}&location=#{CGI.escape(address_str)}"
+        res = self.call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = res.body
+        doc = REXML::Document.new(xml)
+        logger.debug "Yahoo geocoding. Address: #{address}. Result: #{xml}"
+
+        if doc.elements['//ResultSet']
+          res=GeoLoc.new
+
+          #basic      
+          res.lat=doc.elements['//Latitude'].text
+          res.lng=doc.elements['//Longitude'].text
+          res.country_code=doc.elements['//Country'].text
+          res.provider='yahoo'  
+
+          #extended - false if not available
+          res.city=doc.elements['//City'].text if doc.elements['//City'] && doc.elements['//City'].text != nil
+          res.state=doc.elements['//State'].text if doc.elements['//State'] && doc.elements['//State'].text != nil
+          res.zip=doc.elements['//Zip'].text if doc.elements['//Zip'] && doc.elements['//Zip'].text != nil
+          res.street_address=doc.elements['//Address'].text if doc.elements['//Address'] && doc.elements['//Address'].text != nil
+          res.precision=doc.elements['//Result'].attributes['precision'] if doc.elements['//Result']
+          res.success=true
+          return res
+        else 
+          logger.info "Yahoo was unable to geocode address: "+address
+          return GeoLoc.new
+        end   
+
+        rescue 
+          logger.info "Caught an error during Yahoo geocoding call: "+$!
+          return GeoLoc.new
+      end
+    end
+    
+    # Provides methods to geocode with a variety of geocoding service providers, plus failover
+    # among providers in the order you configure.
+    # 
+    # Goal:
+    # - homogenize the results of multiple geocoders
+    # 
+    # 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
+
+      # 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|
+          begin
+            klass = GeoKit::Geocoders.const_get "#{provider.to_s.capitalize}Geocoder"
+            res = klass.send :geocode, address
+            return res if res.success
+          rescue
+            logger.error("Something has gone very wrong during geocoding, OR you have configured an invalid class name in GeoKit::Geocoders::provider_order. Address: #{address}. Provider: #{provider}")
+          end
+        end
+        # If we get here, we failed completely.
+        GeoLoc.new
+      end
+    end   
+  end
+end

data/lib/geo_kit/ip_geocode_lookup.rb

@@ -0,0 +1,46 @@
+require 'yaml'
+
+module GeoKit 
+  # Contains a class method geocode_ip_address which can be used to enable automatic geocoding
+  # for request IP addresses.  The geocoded information is stored in a cookie and in the 
+  # session to minimize web service calls.  The point of the helper is to enable location-based
+  # websites to have a best-guess for new visitors.
+  module IpGeocodeLookup
+    # Mix below class methods into ActionController.
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+    end
+    
+    # Class method to mix into active record.
+    module ClassMethods # :nodoc:
+      def geocode_ip_address(filter_options = {})
+        before_filter :store_ip_location, filter_options
+      end
+    end
+ 
+    private   
+         
+    # Places the IP address' geocode location into the session if it 
+    # can be found.  Otherwise, looks for a geo location cookie and
+    # uses that value.  The last resort is to call the web service to
+    # get the value.
+    def store_ip_location
+      session[:geo_location] ||= retrieve_location_from_cookie_or_service
+      cookies[:geo_location] = { :value => session[:geo_location].to_yaml, :expires => 30.days.from_now } if session[:geo_location]
+    end    
+    
+    # Uses the stored location value from the cookie if it exists.  If
+    # no cookie exists, calls out to the web service to get the location. 
+    def retrieve_location_from_cookie_or_service
+      return YAML.load(cookies[:geo_location]) if cookies[:geo_location]
+      location = Geocoders::IpGeocoder.geocode(get_ip_address)
+      return location.success ? location : nil
+    end
+    
+    # Returns the real ip address, though this could be the localhost ip
+    # address.  No special handling here anymore.
+    def get_ip_address
+      request.remote_ip
+    end
+  end
+end

data/lib/geo_kit/mappable.rb

@@ -0,0 +1,432 @@
+require 'geo_kit/defaults'
+
+module GeoKit
+  # Contains class and instance methods providing distance calcuation services.  This
+  # module is meant to be mixed into classes containing lat and lng attributes where
+  # distance calculation is desired.  
+  # 
+  # At present, two forms of distance calculations are provided:
+  # 
+  # * Pythagorean Theory (flat Earth) - which assumes the world is flat and loses accuracy over long distances.
+  # * Haversine (sphere) - which is fairly accurate, but at a performance cost.
+  # 
+  # Distance units supported are :miles and :kms.
+  module Mappable
+    PI_DIV_RAD = 0.0174
+    KMS_PER_MILE = 1.609
+    EARTH_RADIUS_IN_MILES = 3963.19
+    EARTH_RADIUS_IN_KMS = EARTH_RADIUS_IN_MILES * KMS_PER_MILE
+    MILES_PER_LATITUDE_DEGREE = 69.1
+    KMS_PER_LATITUDE_DEGREE = MILES_PER_LATITUDE_DEGREE * KMS_PER_MILE
+    LATITUDE_DEGREES = EARTH_RADIUS_IN_MILES / MILES_PER_LATITUDE_DEGREE  
+    
+    # Mix below class methods into the includer.
+    def self.included(receiver) # :nodoc:
+      receiver.extend ClassMethods
+    end   
+    
+    module ClassMethods #:nodoc:
+      # Returns the distance between two points.  The from and to parameters are
+      # required to have lat and lng attributes.  Valid options are:
+      # :units - valid values are :miles or :kms (GeoKit::default_units is the default)
+      # :formula - valid values are :flat or :sphere (GeoKit::default_formula is the default)
+      def distance_between(from, to, options={})
+        from=GeoKit::LatLng.normalize(from)
+        to=GeoKit::LatLng.normalize(to)
+        return 0.0 if from == to # fixes a "zero-distance" bug
+        units = options[:units] || GeoKit::default_units
+        formula = options[:formula] || GeoKit::default_formula
+        case formula
+        when :sphere          
+          units_sphere_multiplier(units) * 
+              Math.acos( Math.sin(deg2rad(from.lat)) * Math.sin(deg2rad(to.lat)) + 
+              Math.cos(deg2rad(from.lat)) * Math.cos(deg2rad(to.lat)) * 
+              Math.cos(deg2rad(to.lng) - deg2rad(from.lng)))   
+        when :flat
+          Math.sqrt((units_per_latitude_degree(units)*(from.lat-to.lat))**2 + 
+              (units_per_longitude_degree(from.lat, units)*(from.lng-to.lng))**2)
+        end
+      end
+
+      # Returns heading in degrees (0 is north, 90 is east, 180 is south, etc)
+      # from the first point to the second point. Typicaly, the instance methods will be used 
+      # instead of this method.
+      def heading_between(from,to)
+        from=GeoKit::LatLng.normalize(from)
+        to=GeoKit::LatLng.normalize(to)
+
+        d_lng=deg2rad(to.lng-from.lng)
+        from_lat=deg2rad(from.lat)
+        to_lat=deg2rad(to.lat) 
+        y=Math.sin(d_lng) * Math.cos(to_lat)
+        x=Math.cos(from_lat)*Math.sin(to_lat)-Math.sin(from_lat)*Math.cos(to_lat)*Math.cos(d_lng)
+        heading=to_heading(Math.atan2(y,x))
+      end
+  
+      # Given a start point, distance, and heading (in degrees), provides
+      # an endpoint. Returns a LatLng instance. Typically, the instance method
+      # will be used instead of this method.
+      def endpoint(start,heading, distance, options={})
+        units = options[:units] || GeoKit::default_units
+        radius = units == :miles ? EARTH_RADIUS_IN_MILES : EARTH_RADIUS_IN_KMS
+        start=GeoKit::LatLng.normalize(start)        
+        lat=deg2rad(start.lat)
+        lng=deg2rad(start.lng)
+        heading=deg2rad(heading)
+        distance=distance.to_f
+        
+        end_lat=Math.asin(Math.sin(lat)*Math.cos(distance/radius) +
+                          Math.cos(lat)*Math.sin(distance/radius)*Math.cos(heading))
+
+        end_lng=lng+Math.atan2(Math.sin(heading)*Math.sin(distance/radius)*Math.cos(lat),
+                               Math.cos(distance/radius)-Math.sin(lat)*Math.sin(end_lat))
+
+        LatLng.new(rad2deg(end_lat),rad2deg(end_lng))
+      end
+
+      # Returns the midpoint, given two points. Returns a LatLng. 
+      # Typically, the instance method will be used instead of this method.
+      # Valid option:
+      #   :units - valid values are :miles or :kms (:miles is the default)
+      def midpoint_between(from,to,options={})
+        from=GeoKit::LatLng.normalize(from)
+
+        units = options[:units] || GeoKit::default_units
+        
+        heading=from.heading_to(to)
+        distance=from.distance_to(to,options)
+        midpoint=from.endpoint(heading,distance/2,options)
+      end
+  
+      # Geocodes a location using the multi geocoder.
+      def geocode(location)
+        res = Geocoders::MultiGeocoder.geocode(location)
+        return res if res.success
+        raise GeoKit::Geocoders::GeocodeError      
+      end
+    
+      protected
+    
+      def deg2rad(degrees)
+        degrees.to_f / 180.0 * Math::PI
+      end
+      
+      def rad2deg(rad)
+        rad.to_f * 180.0 / Math::PI 
+      end
+      
+      def to_heading(rad)
+        (rad2deg(rad)+360)%360
+      end
+
+      # Returns the multiplier used to obtain the correct distance units.
+      def units_sphere_multiplier(units)
+        units == :miles ? EARTH_RADIUS_IN_MILES : EARTH_RADIUS_IN_KMS
+      end
+
+      # Returns the number of units per latitude degree.
+      def units_per_latitude_degree(units)
+        units == :miles ? MILES_PER_LATITUDE_DEGREE : KMS_PER_LATITUDE_DEGREE
+      end
+    
+      # Returns the number units per longitude degree.
+      def units_per_longitude_degree(lat, units)
+        miles_per_longitude_degree = (LATITUDE_DEGREES * Math.cos(lat * PI_DIV_RAD)).abs
+        units == :miles ? miles_per_longitude_degree : miles_per_longitude_degree * KMS_PER_MILE
+      end  
+    end
+  
+    # -----------------------------------------------------------------------------------------------
+    # Instance methods below here
+    # -----------------------------------------------------------------------------------------------
+  
+    # Extracts a LatLng instance. Use with models that are acts_as_mappable
+    def to_lat_lng
+      return self if instance_of?(GeoKit::LatLng) || instance_of?(GeoKit::GeoLoc)
+      return LatLng.new(send(self.class.lat_column_name),send(self.class.lng_column_name)) if self.class.respond_to?(:acts_as_mappable)
+      return nil
+    end
+
+    # Returns the distance from another point.  The other point parameter is
+    # required to have lat and lng attributes.  Valid options are:
+    # :units - valid values are :miles or :kms (:miles is the default)
+    # :formula - valid values are :flat or :sphere (:sphere is the default)
+    def distance_to(other, options={})
+      self.class.distance_between(self, other, options)
+    end  
+    alias distance_from distance_to
+
+    # Returns heading in degrees (0 is north, 90 is east, 180 is south, etc)
+    # to the given point. The given point can be a LatLng or a string to be Geocoded 
+    def heading_to(other)
+      self.class.heading_between(self,other)
+    end
+
+    # Returns heading in degrees (0 is north, 90 is east, 180 is south, etc)
+    # FROM the given point. The given point can be a LatLng or a string to be Geocoded 
+    def heading_from(other)
+      self.class.heading_between(other,self)
+    end
+ 
+    # Returns the endpoint, given a heading (in degrees) and distance.  
+    # Valid option:
+    # :units - valid values are :miles or :kms (:miles is the default)
+    def endpoint(heading,distance,options={})
+      self.class.endpoint(self,heading,distance,options)  
+    end
+
+    # Returns the midpoint, given another point on the map.  
+    # Valid option:
+    # :units - valid values are :miles or :kms (:miles is the default)    
+    def midpoint_to(other, options={})
+      self.class.midpoint_between(self,other,options)
+    end
+    
+  end
+
+  class LatLng 
+    include Mappable
+
+    attr_accessor :lat, :lng
+
+    # Accepts latitude and longitude or instantiates an empty instance
+    # if lat and lng are not provided. Converted to floats if provided
+    def initialize(lat=nil, lng=nil)
+      lat = lat.to_f if lat && !lat.is_a?(Numeric)
+      lng = lng.to_f if lng && !lng.is_a?(Numeric)
+      @lat = lat
+      @lng = lng
+    end 
+
+    # Latitude attribute setter; stored as a float.
+    def lat=(lat)
+      @lat = lat.to_f if lat
+    end
+
+    # Longitude attribute setter; stored as a float;
+    def lng=(lng)
+      @lng=lng.to_f if lng
+    end  
+
+    # Returns the lat and lng attributes as a comma-separated string.
+    def ll
+      "#{lat},#{lng}"
+    end
+    
+    #returns a string with comma-separated lat,lng values
+    def to_s
+      ll
+    end
+  
+    #returns a two-element array
+    def to_a
+      [lat,lng]
+    end
+    # Returns true if the candidate object is logically equal.  Logical equivalence
+    # is true if the lat and lng attributes are the same for both objects.
+    def ==(other)
+      other.is_a?(LatLng) ? self.lat == other.lat && self.lng == other.lng : false
+    end
+    
+    # A *class* method to take anything which can be inferred as a point and generate
+    # a LatLng from it. You should use this anything you're not sure what the input is,
+    # and want to deal with it as a LatLng if at all possible. Can take:
+    #  1) two arguments (lat,lng)
+    #  2) a string in the format "37.1234,-129.1234" or "37.1234 -129.1234"
+    #  3) a string which can be geocoded on the fly
+    #  4) an array in the format [37.1234,-129.1234]
+    #  5) a LatLng or GeoLoc (which is just passed through as-is)
+    #  6) anything which acts_as_mappable -- a LatLng will be extracted from it
+    def self.normalize(thing,other=nil)
+      # if an 'other' thing is supplied, normalize the input by creating an array of two elements
+      thing=[thing,other] if other
+      
+      if thing.is_a?(String)
+        thing.strip!
+        if match=thing.match(/(\-?\d+\.?\d*)[, ] ?(\-?\d+\.?\d*)$/)
+          return GeoKit::LatLng.new(match[1],match[2])
+        else
+          res = GeoKit::Geocoders::MultiGeocoder.geocode(thing)
+          return res if res.success
+          raise GeoKit::Geocoders::GeocodeError  
+        end
+      elsif thing.is_a?(Array) && thing.size==2
+        return GeoKit::LatLng.new(thing[0],thing[1])
+      elsif thing.is_a?(LatLng) # will also be true for GeoLocs
+        return thing
+      elsif thing.class.respond_to?(:acts_as_mappable) && thing.class.respond_to?(:distance_column_name)
+        return thing.to_lat_lng
+      end
+      
+      throw ArgumentError.new("#{thing} (#{thing.class}) cannot be normalized to a LatLng. We tried interpreting it as an array, string, Mappable, etc., but no dice.")
+    end
+    
+  end
+
+  # This class encapsulates the result of a geocoding call
+  # It's primary purpose is to homogenize the results of multiple
+  # geocoding providers. It also provides some additional functionality, such as 
+  # the "full address" method for geocoders that do not provide a 
+  # full address in their results (for example, Yahoo), and the "is_us" method.
+  class GeoLoc < LatLng
+    # Location attributes.  Full address is a concatenation of all values.  For example:
+    # 100 Spear St, San Francisco, CA, 94101, US
+    attr_accessor :street_address, :city, :state, :zip, :country_code, :full_address
+    # Attributes set upon return from geocoding.  Success will be true for successful
+    # geocode lookups.  The provider will be set to the name of the providing geocoder.
+    # Finally, precision is an indicator of the accuracy of the geocoding.
+    attr_accessor :success, :provider, :precision
+    # Street number and street name are extracted from the street address attribute.
+    attr_reader :street_number, :street_name
+
+    # Constructor expects a hash of symbols to correspond with attributes.
+    def initialize(h={})
+      @street_address=h[:street_address] 
+      @city=h[:city] 
+      @state=h[:state] 
+      @zip=h[:zip] 
+      @country_code=h[:country_code] 
+      @success=false
+      @precision='unknown'
+      super(h[:lat],h[:lng])
+    end
+
+    # Returns true if geocoded to the United States.
+    def is_us?
+      country_code == 'US'
+    end
+
+    # full_address is provided by google but not by yahoo. It is intended that the google
+    # geocoding method will provide the full address, whereas for yahoo it will be derived
+    # from the parts of the address we do have.
+    def full_address
+      @full_address ? @full_address : to_geocodeable_s
+    end
+
+    # Extracts the street number from the street address if the street address
+    # has a value.
+    def street_number
+      street_address[/(\d*)/] if street_address
+    end
+
+    # Returns the street name portion of the street address.
+    def street_name
+       street_address[street_number.length, street_address.length].strip if street_address
+    end
+
+    # gives you all the important fields as key-value pairs
+    def hash
+      res={}
+      [:success,:lat,:lng,:country_code,:city,:state,:zip,:street_address,:provider,:full_address,:is_us?,:ll,:precision].each { |s| res[s] = self.send(s.to_s) }
+      res
+    end
+    alias to_hash hash
+
+    # Sets the city after capitalizing each word within the city name.
+    def city=(city)
+      @city = city.titleize if city
+    end
+
+    # Sets the street address after capitalizing each word within the street address.
+    def street_address=(address)
+      @street_address = address.titleize if address
+    end  
+
+    # Returns a comma-delimited string consisting of the street address, city, state,
+    # zip, and country code.  Only includes those attributes that are non-blank.
+    def to_geocodeable_s
+      a=[street_address, city, state, zip, country_code].compact
+      a.delete_if { |e| !e || e == '' }
+      a.join(', ')      
+    end
+
+    # 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}"
+    end
+  end
+  
+  # Bounds represents a rectangular bounds, defined by the SW and NE corners
+  class Bounds
+    # sw and ne are LatLng objects
+    attr_accessor :sw, :ne
+    
+    # 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))
+      @sw,@ne=sw,ne
+    end
+    
+    #returns the a single point which is the center of the rectangular bounds
+    def center
+      @sw.midpoint_to(@ne)
+    end
+  
+    # a simple string representation:sw,ne
+    def to_s
+      "#{@sw.to_s},#{@ne.to_s}"   
+    end
+    
+    # a two-element array of two-element arrays: sw,ne
+    def to_a
+      [@sw.to_a, @ne.to_a]
+    end
+    
+    # Returns true if the bounds contain the passed point.
+    # allows for bounds which cross the meridian
+    def contains?(point)
+      point=GeoKit::LatLng.normalize(point)
+      res = point.lat > @sw.lat && point.lat < @ne.lat
+      if crosses_meridian?
+        res &= point.lng < @ne.lng || point.lng > @sw.lng
+      else
+        res &= point.lng < @ne.lng && point.lng > @sw.lng
+      end
+      res
+    end
+    
+    # returns true if the bounds crosses the international dateline
+    def crosses_meridian?
+      @sw.lng > @ne.lng 
+    end
+
+    # Returns true if the candidate object is logically equal.  Logical equivalence
+    # is true if the lat and lng attributes are the same for both objects.
+    def ==(other)
+      other.is_a?(Bounds) ? self.sw == other.sw && self.ne == other.ne : false
+    end
+    
+    class <<self
+      
+      # returns an instance of bounds which completely encompases the given circle
+      def from_point_and_radius(point,radius,options={})
+        point=LatLng.normalize(point)
+        p0=point.endpoint(0,radius,options)
+        p90=point.endpoint(90,radius,options)
+        p180=point.endpoint(180,radius,options)
+        p270=point.endpoint(270,radius,options)
+        sw=GeoKit::LatLng.new(p180.lat,p270.lng)
+        ne=GeoKit::LatLng.new(p0.lat,p90.lng)
+        GeoKit::Bounds.new(sw,ne)
+      end
+      
+      # Takes two main combinations of arguements 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)
+      #
+      # NOTE: everything combination is assumed to pass points in the order sw, ne
+      def normalize (thing,other=nil)   
+        # maybe this will be simple -- an actual bounds object is passed, and we can all go home
+        return thing if thing.is_a? Bounds
+        
+        # no? OK, if there's no "other," the thing better be a two-element array        
+        thing,other=thing if !other && thing.is_a?(Array) && thing.size==2
+
+        # Now that we're set with a thing and another thing, let LatLng do the heavy lifting.
+        # Exceptions may be thrown
+        Bounds.new(GeoKit::LatLng.normalize(thing),GeoKit::LatLng.normalize(other))
+      end
+    end
+  end
+end