rails-geocoder 0.9.6 → 0.9.7

data/CHANGELOG.rdoc

@@ -2,10 +2,15 @@
 
 Per-release changes to Geocoder.
 
+== 0.9.7 (2011 Feb 1)
+
+* Add reverse geocoding (+reverse_geocoded_by+).
+* Prevent exception (uninitialized constant Geocoder::Net) when net/http not already required (sleepycat).
+
 == 0.9.6 (2011 Jan 19)
 
 * Fix incompatibility with will_paginate gem.
-* Include table names in GROUP BY clause of nearby scope to avoid ambiguity in joins.
+* Include table names in GROUP BY clause of nearby scope to avoid ambiguity in joins (matchu).
 
 == 0.9.5 (2010 Oct 15)
 

data/README.rdoc

@@ -68,13 +68,13 @@ To find objects by location, use the following scopes:
 Some utility methods are also available:
 
   # distance (in miles) between Eiffel Tower and Empire State Building
-  Geocoder.distance_between( 48.858205,2.294359,  40.748433,-73.985655 )
+  Geocoder::Calculations.distance_between( 48.858205,2.294359,  40.748433,-73.985655 )
 
   # look up coordinates of some location (like searching Google Maps)
   Geocoder.fetch_coordinates("25 Main St, Cooperstown, NY")
 
   # find the geographic center (aka center of gravity) of objects or points
-  Geocoder.geographic_center([ city1, city2, city3, [40.22,-73.99], city4 ])
+  Geocoder::Calculations.geographic_center([ city1, city2, city3, [40.22,-73.99], city4 ])
 
 
 == More On Configuration
@@ -101,6 +101,45 @@ If your model has +address+, +city+, +state+, and +country+ attributes you might
 Please see the code for more methods and detailed information about arguments (eg, working with kilometers).
 
 
+== Reverse Geocoding
+
+If you need reverse geocoding (lat/long coordinates to address), do something like the following in your model:
+
+  reverse_geocoded_by :latitude, :longitude
+  after_validation :fetch_address
+
+and make sure it has +latitude+ and +longitude+ attributes, as well as an +address+ attribute. As with regular geocoding, you can specify alternate names for all of these attributes, for example:
+
+  reverse_geocoded_by :lat, :lon, :address => :location
+
+
+== Forward and Reverse Geocoding in the Same Model
+
+If you apply both forward and reverse geocoding functionality to the same model, you can provide different methods for storing the fetched address (reverse geocoding) and providing an address to use when fetching coordinates (forward geocoding), for example:
+
+  class Venue
+
+    # build an address from street, city, and state attributes
+    geocoded_by :address_from_components
+
+    # store the Google-provided address in the full_address attribute
+    reverse_geocoded_by :latitude, :longitude, :address => :full_address
+  end
+
+However, there can be only one set of latitude/longitude attributes, and whichever you specify last will be used. For example:
+
+  class Venue
+
+    geocoded_by :address,
+      :latitude  => :fetched_latitude,  # this will be overridden by the below
+      :longitude => :fetched_longitude  # same here
+
+    reverse_geocoded_by :latitude, :longitude
+  end
+
+The reason for this is that we don't want ambiguity when doing distance calculations. We need a single, authoritative source for coordinates!
+
+
 == SQLite
 
 SQLite's lack of trigonometric functions requires an alternate implementation of the +near+ method (scope). When using SQLite, Geocoder will automatically use a less accurate algorithm for finding objects near a given point. Results of this algorithm should not be trusted too much as it will return objects that are outside the given radius.
@@ -114,9 +153,9 @@ There are few options for finding objects near a given point in SQLite without i
 
 1. Use a square instead of a circle for finding nearby points. For example, if you want to find points near 40.71, 100.23, search for objects with latitude between 39.71 and 41.71 and longitude between 99.23 and 101.23. One degree of latitude or longitude is at most 69 miles so divide your radius (in miles) by 69.0 to get the amount to add and subtract from your center coordinates to get the upper and lower bounds. The results will not be very accurate (you'll get points outside the desired radius--at worst 29% farther away), but you will get all the points within the required radius.
 
-2. Load all objects into memory and compute distances between them using the <tt>Geocoder.distance_between</tt> method. This will produce accurate results but will be very slow (and use a lot of memory) if you have a lot of objects in your database.
+2. Load all objects into memory and compute distances between them using the <tt>Geocoder::Calculations.distance_between</tt> method. This will produce accurate results but will be very slow (and use a lot of memory) if you have a lot of objects in your database.
 
-3. If you have a large number of objects (so you can't use approach #2) and you need accurate results (better than approach #1 will give), you can use a combination of the two. Get all the objects within a square around your center point, and then eliminate the ones that are too far away using <tt>Geocoder.distance_between</tt>.
+3. If you have a large number of objects (so you can't use approach #2) and you need accurate results (better than approach #1 will give), you can use a combination of the two. Get all the objects within a square around your center point, and then eliminate the ones that are too far away using <tt>Geocoder::Calculations.distance_between</tt>.
 
 Because Geocoder needs to provide this functionality as a scope, we must go with option #1, but feel free to implement #2 or #3 if you need more accuracy.
 
@@ -136,7 +175,6 @@ If anyone has a more elegant solution to this problem I am very interested in se
 * use completely separate "drivers" for different AR adapters?
   * seems reasonable since we're using very DB-specific features
   * also need to make sure 'mysql2' is supported
-* add reverse geocoding
 * make 'near' scope work with AR associations
   * http://stackoverflow.com/questions/3266358/geocoder-rails-plugin-near-search-problem-with-activerecord
 * prepend table names to column names in SQL distance expression (required

data/lib/geocoder.rb

@@ -1,361 +1,53 @@
+require "geocoder/calculations"
+require "geocoder/lookup"
+require "geocoder/active_record"
+
 ##
-# Add geocoding functionality (via Google) to any object.
+# Add geocoded_by method to ActiveRecord::Base so Geocoder is accessible.
 #
-module Geocoder
-
-  ##
-  # Implementation of 'included' hook method.
-  #
-  def self.included(base)
-    base.extend ClassMethods
-    base.class_eval do
-
-      # scope: geocoded objects
-      scope :geocoded,
-        :conditions => "#{geocoder_options[:latitude]} IS NOT NULL " +
-          "AND #{geocoder_options[:longitude]} IS NOT NULL"
-
-      # scope: not-geocoded objects
-      scope :not_geocoded,
-        :conditions => "#{geocoder_options[:latitude]} IS NULL " +
-          "OR #{geocoder_options[:longitude]} IS NULL"
-
-      ##
-      # Find all objects within a radius (in miles) of the given location
-      # (address string). Location (the first argument) may be either a string
-      # to geocode or an array of coordinates (<tt>[lat,long]</tt>).
-      #
-      scope :near, lambda{ |location, *args|
-        latitude, longitude = location.is_a?(Array) ?
-          location : Geocoder.fetch_coordinates(location)
-        if latitude and longitude
-          near_scope_options(latitude, longitude, *args)
-        else
-          {}
-        end
-      }
-    end
-  end
-
-  ##
-  # Methods which will be class methods of the including class.
-  #
-  module ClassMethods
-
-    ##
-    # Get options hash suitable for passing to ActiveRecord.find to get
-    # records within a radius (in miles) of the given point.
-    # Options hash may include:
-    #
-    # +units+   :: <tt>:mi</tt> (default) or <tt>:km</tt>
-    # +exclude+ :: an object to exclude (used by the #nearbys method)
-    # +order+   :: column(s) for ORDER BY SQL clause
-    # +limit+   :: number of records to return (for LIMIT SQL clause)
-    # +offset+  :: number of records to skip (for OFFSET SQL clause)
-    # +select+  :: string with the SELECT SQL fragment (e.g. “id, name”)
-    #
-    def near_scope_options(latitude, longitude, radius = 20, options = {})
-      radius *= km_in_mi if options[:units] == :km
-      if ActiveRecord::Base.connection.adapter_name == "SQLite"
-        approx_near_scope_options(latitude, longitude, radius, options)
-      else
-        full_near_scope_options(latitude, longitude, radius, options)
-      end
-    end
-
-
-    private # ----------------------------------------------------------------
-
-    ##
-    # Scope options hash for use with a database that supports POWER(),
-    # SQRT(), PI(), and trigonometric functions (SIN(), COS(), and ASIN()).
-    #
-    # Taken from the excellent tutorial at:
-    # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
-    #
-    def full_near_scope_options(latitude, longitude, radius, options)
-      lat_attr = geocoder_options[:latitude]
-      lon_attr = geocoder_options[:longitude]
-      distance = "3956 * 2 * ASIN(SQRT(" +
-        "POWER(SIN((#{latitude} - #{lat_attr}) * " +
-        "PI() / 180 / 2), 2) + COS(#{latitude} * PI()/180) * " +
-        "COS(#{lat_attr} * PI() / 180) * " +
-        "POWER(SIN((#{longitude} - #{lon_attr}) * " +
-        "PI() / 180 / 2), 2) ))"
-      options[:order] ||= "#{distance} ASC"
-      default_near_scope_options(latitude, longitude, radius, options).merge(
-        :select => "#{options[:select] || '*'}, #{distance} AS distance",
-        :having => "#{distance} <= #{radius}"
-      )
-    end
-
-    ##
-    # Scope options hash for use with a database without trigonometric
-    # functions, like SQLite. Approach is to find objects within a square
-    # rather than a circle, so results are very approximate (will include
-    # objects outside the given radius).
-    #
-    def approx_near_scope_options(latitude, longitude, radius, options)
-      default_near_scope_options(latitude, longitude, radius, options).merge(
-        :select => options[:select] || nil
-      )
-    end
-
-    ##
-    # Options used for any near-like scope.
-    #
-    def default_near_scope_options(latitude, longitude, radius, options)
-      lat_attr = geocoder_options[:latitude]
-      lon_attr = geocoder_options[:longitude]
-      conditions = \
-        ["#{lat_attr} BETWEEN ? AND ? AND #{lon_attr} BETWEEN ? AND ?"] +
-        coordinate_bounds(latitude, longitude, radius)
-      if obj = options[:exclude]
-        conditions[0] << " AND id != ?"
-        conditions << obj.id
-      end
-      {
-        :group  => columns.map{ |c| "#{table_name}.#{c.name}" }.join(','),
-        :order  => options[:order],
-        :limit  => options[:limit],
-        :offset => options[:offset],
-        :conditions => conditions
-      }
-    end
-
-    ##
-    # Get the rough high/low lat/long bounds for a geographic point and
-    # radius. Returns an array: <tt>[lat_lo, lat_hi, lon_lo, lon_hi]</tt>.
-    # Used to constrain search to a (radius x radius) square.
-    #
-    def coordinate_bounds(latitude, longitude, radius)
-      radius = radius.to_f
-      factor = (Math::cos(latitude * Math::PI / 180.0) * 69.0).abs
-      [
-        latitude  - (radius / 69.0),
-        latitude  + (radius / 69.0),
-        longitude - (radius / factor),
-        longitude + (radius / factor)
-      ]
-    end
-
-    ##
-    # Conversion factor: km to mi.
-    #
-    def km_in_mi
-      0.621371192
-    end
-  end
-
-  ##
-  # Read the coordinates [lat,lon] of an object. This is not great but it
-  # seems cleaner than polluting the instance method namespace.
-  #
-  def read_coordinates
-    [:latitude, :longitude].map{ |i| send self.class.geocoder_options[i] }
-  end
-
-  ##
-  # Is this object geocoded? (Does it have latitude and longitude?)
-  #
-  def geocoded?
-    read_coordinates.compact.size > 0
-  end
-
-  ##
-  # Calculate the distance from the object to a point (lat,lon).
-  # Valid units are defined in <tt>distance_between</tt> class method.
-  #
-  def distance_to(lat, lon, units = :mi)
-    return nil unless geocoded?
-    mylat,mylon = read_coordinates
-    Geocoder.distance_between(mylat, mylon, lat, lon, :units => units)
-  end
-
-  ##
-  # Get other geocoded objects within a given radius.
-  # Valid units are defined in <tt>distance_between</tt> class method.
-  #
-  def nearbys(radius = 20, units = :mi)
-    return [] unless geocoded?
-    options = {:exclude => self, :units => units}
-    self.class.near(read_coordinates, radius, options)
-  end
+ActiveRecord::Base.class_eval do
 
   ##
-  # Fetch coordinates and assign +latitude+ and +longitude+. Also returns
-  # coordinates as an array: <tt>[lat, lon]</tt>.
+  # Set attribute names and include the Geocoder module.
   #
-  def fetch_coordinates(save = false)
-    coords = Geocoder.fetch_coordinates(
-      send(self.class.geocoder_options[:method_name])
+  def self.geocoded_by(address_attr, options = {})
+    _geocoder_init(
+      :user_address => address_attr,
+      :latitude  => options[:latitude]  || :latitude,
+      :longitude => options[:longitude] || :longitude
     )
-    unless coords.blank?
-      method = (save ? "update" : "write") + "_attribute"
-      send method, self.class.geocoder_options[:latitude],  coords[0]
-      send method, self.class.geocoder_options[:longitude], coords[1]
-    end
-    coords
-  end
-
-  ##
-  # Fetch coordinates and update (save) +latitude+ and +longitude+ data.
-  #
-  def fetch_coordinates!
-    fetch_coordinates(true)
   end
 
   ##
-  # Calculate the distance between two points on Earth (Haversine formula).
-  # Takes two sets of coordinates and an options hash:
-  #
-  # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+  # Set attribute names and include the Geocoder module.
   #
-  def self.distance_between(lat1, lon1, lat2, lon2, options = {})
-
-    # set default options
-    options[:units] ||= :mi
-
-    # define conversion factors
-    conversions = { :mi => 3956, :km => 6371 }
-
-    # convert degrees to radians
-    lat1 = to_radians(lat1)
-    lon1 = to_radians(lon1)
-    lat2 = to_radians(lat2)
-    lon2 = to_radians(lon2)
-
-    # compute distances
-    dlat = (lat1 - lat2).abs
-    dlon = (lon1 - lon2).abs
-
-    a = (Math.sin(dlat / 2))**2 + Math.cos(lat1) *
-        (Math.sin(dlon / 2))**2 * Math.cos(lat2)
-    c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
-    c * conversions[options[:units]]
+  def self.reverse_geocoded_by(latitude_attr, longitude_attr, options = {})
+    _geocoder_init(
+      :fetched_address => options[:address] || :address,
+      :latitude  => latitude_attr,
+      :longitude => longitude_attr
+    )
   end
 
-  ##
-  # Compute the geographic center (aka geographic midpoint, center of
-  # gravity) for an array of geocoded objects and/or [lat,lon] arrays
-  # (can be mixed). Any objects missing coordinates are ignored. Follows
-  # the procedure documented at http://www.geomidpoint.com/calculation.html.
-  #
-  def self.geographic_center(points)
-
-    # convert objects to [lat,lon] arrays and remove nils
-    points = points.map{ |p|
-      p.is_a?(Array) ? p : (p.geocoded?? p.read_coordinates : nil)
-    }.compact
-
-    # convert degrees to radians
-    points.map!{ |p| [to_radians(p[0]), to_radians(p[1])] }
-
-    # convert to Cartesian coordinates
-    x = []; y = []; z = []
-    points.each do |p|
-      x << Math.cos(p[0]) * Math.cos(p[1])
-      y << Math.cos(p[0]) * Math.sin(p[1])
-      z << Math.sin(p[0])
+  def self._geocoder_init(options)
+    unless _geocoder_initialized?
+      class_inheritable_reader :geocoder_options
+      class_inheritable_hash_writer :geocoder_options
     end
-
-    # compute average coordinate values
-    xa, ya, za = [x,y,z].map do |c|
-      c.inject(0){ |tot,i| tot += i } / c.size.to_f
+    self.geocoder_options = options
+    unless _geocoder_initialized?
+      include Geocoder::ActiveRecord
     end
-
-    # convert back to latitude/longitude
-    lon = Math.atan2(ya, xa)
-    hyp = Math.sqrt(xa**2 + ya**2)
-    lat = Math.atan2(za, hyp)
-
-    # return answer in degrees
-    [to_degrees(lat), to_degrees(lon)]
-  end
-
-  ##
-  # Convert degrees to radians.
-  #
-  def self.to_radians(degrees)
-    degrees * (Math::PI / 180)
-  end
-
-  ##
-  # Convert radians to degrees.
-  #
-  def self.to_degrees(radians)
-    (radians * 180.0) / Math::PI
-  end
-
-  ##
-  # Query Google for geographic information about the given phrase.
-  # Returns a hash representing a valid geocoder response.
-  # Returns nil if non-200 HTTP response, timeout, or other error.
-  #
-  def self.search(query)
-    doc = _fetch_parsed_response(query)
-    doc && doc['status'] == "OK" ? doc : nil
   end
 
-  ##
-  # Query Google for the coordinates of the given phrase.
-  # Returns array [lat,lon] if found, nil if not found or if network error.
-  #
-  def self.fetch_coordinates(query)
-    return nil unless doc = self.search(query)
-    # blindly use the first results (assume they are most accurate)
-    place = doc['results'].first['geometry']['location']
-    ['lat', 'lng'].map{ |i| place[i] }
+  def self._geocoder_initialized?
+    included_modules.include? Geocoder::ActiveRecord
   end
+end
 
-  ##
-  # Returns a parsed Google geocoder search result (hash).
-  # This method is not intended for general use (prefer Geocoder.search).
-  #
-  def self._fetch_parsed_response(query)
-    if doc = _fetch_raw_response(query)
-      ActiveSupport::JSON.decode(doc)
-    end
-  end
-
-  ##
-  # Returns a raw Google geocoder search result (JSON).
-  # This method is not intended for general use (prefer Geocoder.search).
-  #
-  def self._fetch_raw_response(query)
-    return nil if query.blank?
-
-    # build URL
-    params = { :address => query, :sensor  => "false" }
-    url = "http://maps.google.com/maps/api/geocode/json?" + params.to_query
 
-    # query geocoder and make sure it responds quickly
-    begin
-      resp = nil
-      timeout(3) do
-        Net::HTTP.get_response(URI.parse(url)).body
-      end
-    rescue SocketError, TimeoutError
-      return nil
-    end
-  end
+class GeocoderError < StandardError
 end
 
-##
-# Add geocoded_by method to ActiveRecord::Base so Geocoder is accessible.
-#
-ActiveRecord::Base.class_eval do
-
-  ##
-  # Set attribute names and include the Geocoder module.
-  #
-  def self.geocoded_by(method_name = :location, options = {})
-    class_inheritable_reader :geocoder_options
-    write_inheritable_attribute :geocoder_options, {
-      :method_name => method_name,
-      :latitude    => options[:latitude]  || :latitude,
-      :longitude   => options[:longitude] || :longitude
-    }
-    include Geocoder
-  end
+class GeocoderConfigurationError < GeocoderError
 end

data/lib/geocoder/active_record.rb

@@ -0,0 +1,235 @@
+##
+# Add geocoding functionality to any ActiveRecord object.
+#
+module Geocoder
+  module ActiveRecord
+
+    ##
+    # Implementation of 'included' hook method.
+    #
+    def self.included(base)
+      base.extend ClassMethods
+      base.class_eval do
+
+        # scope: geocoded objects
+        scope :geocoded,
+          :conditions => "#{geocoder_options[:latitude]} IS NOT NULL " +
+            "AND #{geocoder_options[:longitude]} IS NOT NULL"
+
+        # scope: not-geocoded objects
+        scope :not_geocoded,
+          :conditions => "#{geocoder_options[:latitude]} IS NULL " +
+            "OR #{geocoder_options[:longitude]} IS NULL"
+
+        ##
+        # Find all objects within a radius (in miles) of the given location
+        # (address string). Location (the first argument) may be either a string
+        # to geocode or an array of coordinates (<tt>[lat,long]</tt>).
+        #
+        scope :near, lambda{ |location, *args|
+          latitude, longitude = location.is_a?(Array) ?
+            location : Geocoder::Lookup.coordinates(location)
+          if latitude and longitude
+            near_scope_options(latitude, longitude, *args)
+          else
+            {}
+          end
+        }
+      end
+    end
+
+    ##
+    # Methods which will be class methods of the including class.
+    #
+    module ClassMethods
+
+      ##
+      # Get options hash suitable for passing to ActiveRecord.find to get
+      # records within a radius (in miles) of the given point.
+      # Options hash may include:
+      #
+      # +units+   :: <tt>:mi</tt> (default) or <tt>:km</tt>
+      # +exclude+ :: an object to exclude (used by the #nearbys method)
+      # +order+   :: column(s) for ORDER BY SQL clause
+      # +limit+   :: number of records to return (for LIMIT SQL clause)
+      # +offset+  :: number of records to skip (for OFFSET SQL clause)
+      # +select+  :: string with the SELECT SQL fragment (e.g. “id, name”)
+      #
+      def near_scope_options(latitude, longitude, radius = 20, options = {})
+        radius *= Geocoder::Calculations.km_in_mi if options[:units] == :km
+        if ::ActiveRecord::Base.connection.adapter_name == "SQLite"
+          approx_near_scope_options(latitude, longitude, radius, options)
+        else
+          full_near_scope_options(latitude, longitude, radius, options)
+        end
+      end
+
+
+      private # ----------------------------------------------------------------
+
+      ##
+      # Scope options hash for use with a database that supports POWER(),
+      # SQRT(), PI(), and trigonometric functions (SIN(), COS(), and ASIN()).
+      #
+      # Taken from the excellent tutorial at:
+      # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
+      #
+      def full_near_scope_options(latitude, longitude, radius, options)
+        lat_attr = geocoder_options[:latitude]
+        lon_attr = geocoder_options[:longitude]
+        distance = "3956 * 2 * ASIN(SQRT(" +
+          "POWER(SIN((#{latitude} - #{lat_attr}) * " +
+          "PI() / 180 / 2), 2) + COS(#{latitude} * PI()/180) * " +
+          "COS(#{lat_attr} * PI() / 180) * " +
+          "POWER(SIN((#{longitude} - #{lon_attr}) * " +
+          "PI() / 180 / 2), 2) ))"
+        options[:order] ||= "#{distance} ASC"
+        default_near_scope_options(latitude, longitude, radius, options).merge(
+          :select => "#{options[:select] || '*'}, #{distance} AS distance",
+          :having => "#{distance} <= #{radius}"
+        )
+      end
+
+      ##
+      # Scope options hash for use with a database without trigonometric
+      # functions, like SQLite. Approach is to find objects within a square
+      # rather than a circle, so results are very approximate (will include
+      # objects outside the given radius).
+      #
+      def approx_near_scope_options(latitude, longitude, radius, options)
+        default_near_scope_options(latitude, longitude, radius, options).merge(
+          :select => options[:select] || nil
+        )
+      end
+
+      ##
+      # Options used for any near-like scope.
+      #
+      def default_near_scope_options(latitude, longitude, radius, options)
+        lat_attr = geocoder_options[:latitude]
+        lon_attr = geocoder_options[:longitude]
+        conditions = \
+          ["#{lat_attr} BETWEEN ? AND ? AND #{lon_attr} BETWEEN ? AND ?"] +
+          coordinate_bounds(latitude, longitude, radius)
+        if obj = options[:exclude]
+          conditions[0] << " AND id != ?"
+          conditions << obj.id
+        end
+        {
+          :group  => columns.map{ |c| "#{table_name}.#{c.name}" }.join(','),
+          :order  => options[:order],
+          :limit  => options[:limit],
+          :offset => options[:offset],
+          :conditions => conditions
+        }
+      end
+
+      ##
+      # Get the rough high/low lat/long bounds for a geographic point and
+      # radius. Returns an array: <tt>[lat_lo, lat_hi, lon_lo, lon_hi]</tt>.
+      # Used to constrain search to a (radius x radius) square.
+      #
+      def coordinate_bounds(latitude, longitude, radius)
+        radius = radius.to_f
+        factor = (Math::cos(latitude * Math::PI / 180.0) * 69.0).abs
+        [
+          latitude  - (radius / 69.0),
+          latitude  + (radius / 69.0),
+          longitude - (radius / factor),
+          longitude + (radius / factor)
+        ]
+      end
+    end
+
+    ##
+    # Read the coordinates [lat,lon] of an object. This is not great but it
+    # seems cleaner than polluting the instance method namespace.
+    #
+    def read_coordinates
+      [:latitude, :longitude].map{ |i| send self.class.geocoder_options[i] }
+    end
+
+    ##
+    # Is this object geocoded? (Does it have latitude and longitude?)
+    #
+    def geocoded?
+      read_coordinates.compact.size > 0
+    end
+
+    ##
+    # Calculate the distance from the object to a point (lat,lon).
+    #
+    # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+    #
+    def distance_to(lat, lon, units = :mi)
+      return nil unless geocoded?
+      mylat,mylon = read_coordinates
+      Geocoder::Calculations.distance_between(mylat, mylon, lat, lon, :units => units)
+    end
+
+    ##
+    # Get other geocoded objects within a given radius.
+    #
+    # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+    #
+    def nearbys(radius = 20, units = :mi)
+      return [] unless geocoded?
+      options = {:exclude => self, :units => units}
+      self.class.near(read_coordinates, radius, options)
+    end
+
+    ##
+    # Fetch coordinates and assign +latitude+ and +longitude+. Also returns
+    # coordinates as an array: <tt>[lat, lon]</tt>.
+    #
+    def fetch_coordinates(save = false)
+      address_method = self.class.geocoder_options[:user_address]
+      unless address_method.is_a? Symbol
+        raise GeocoderConfigurationError,
+          "You are attempting to fetch coordinates but have not specified " +
+          "a method which provides an address for the object."
+      end
+      coords = Geocoder::Lookup.coordinates(send(address_method))
+      unless coords.blank?
+        method = (save ? "update" : "write") + "_attribute"
+        send method, self.class.geocoder_options[:latitude],  coords[0]
+        send method, self.class.geocoder_options[:longitude], coords[1]
+      end
+      coords
+    end
+
+    ##
+    # Fetch coordinates and update (save) +latitude+ and +longitude+ data.
+    #
+    def fetch_coordinates!
+      fetch_coordinates(true)
+    end
+
+    ##
+    # Fetch address and assign +address+ attribute. Also returns
+    # address as a string.
+    #
+    def fetch_address(save = false)
+      lat_attr = self.class.geocoder_options[:latitude]
+      lon_attr = self.class.geocoder_options[:longitude]
+      unless lat_attr.is_a?(Symbol) and lon_attr.is_a?(Symbol)
+        raise GeocoderConfigurationError,
+          "You are attempting to fetch an address but have not specified " +
+          "attributes which provide coordinates for the object."
+      end
+      address = Geocoder::Lookup.address(send(lat_attr), send(lon_attr))
+      unless address.blank?
+        method = (save ? "update" : "write") + "_attribute"
+        send method, self.class.geocoder_options[:fetched_address], address
+      end
+      address
+    end
+
+    ##
+    # Fetch address and update (save) +address+ data.
+    #
+    def fetch_address!
+      fetch_address(true)
+    end
+  end
+end

data/lib/geocoder/calculations.rb

@@ -0,0 +1,94 @@
+module Geocoder
+  module Calculations
+    extend self
+
+    ##
+    # Calculate the distance between two points on Earth (Haversine formula).
+    # Takes two sets of coordinates and an options hash:
+    #
+    # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
+    #
+    def distance_between(lat1, lon1, lat2, lon2, options = {})
+
+      # set default options
+      options[:units] ||= :mi
+
+      # define conversion factors
+      conversions = { :mi => 3956, :km => 6371 }
+
+      # convert degrees to radians
+      lat1 = to_radians(lat1)
+      lon1 = to_radians(lon1)
+      lat2 = to_radians(lat2)
+      lon2 = to_radians(lon2)
+
+      # compute distances
+      dlat = (lat1 - lat2).abs
+      dlon = (lon1 - lon2).abs
+
+      a = (Math.sin(dlat / 2))**2 + Math.cos(lat1) *
+          (Math.sin(dlon / 2))**2 * Math.cos(lat2)
+      c = 2 * Math.atan2( Math.sqrt(a), Math.sqrt(1-a))
+      c * conversions[options[:units]]
+    end
+
+    ##
+    # Compute the geographic center (aka geographic midpoint, center of
+    # gravity) for an array of geocoded objects and/or [lat,lon] arrays
+    # (can be mixed). Any objects missing coordinates are ignored. Follows
+    # the procedure documented at http://www.geomidpoint.com/calculation.html.
+    #
+    def geographic_center(points)
+
+      # convert objects to [lat,lon] arrays and remove nils
+      points = points.map{ |p|
+        p.is_a?(Array) ? p : (p.geocoded?? p.read_coordinates : nil)
+      }.compact
+
+      # convert degrees to radians
+      points.map!{ |p| [to_radians(p[0]), to_radians(p[1])] }
+
+      # convert to Cartesian coordinates
+      x = []; y = []; z = []
+      points.each do |p|
+        x << Math.cos(p[0]) * Math.cos(p[1])
+        y << Math.cos(p[0]) * Math.sin(p[1])
+        z << Math.sin(p[0])
+      end
+
+      # compute average coordinate values
+      xa, ya, za = [x,y,z].map do |c|
+        c.inject(0){ |tot,i| tot += i } / c.size.to_f
+      end
+
+      # convert back to latitude/longitude
+      lon = Math.atan2(ya, xa)
+      hyp = Math.sqrt(xa**2 + ya**2)
+      lat = Math.atan2(za, hyp)
+
+      # return answer in degrees
+      [to_degrees(lat), to_degrees(lon)]
+    end
+
+    ##
+    # Convert degrees to radians.
+    #
+    def to_radians(degrees)
+      degrees * (Math::PI / 180)
+    end
+
+    ##
+    # Convert radians to degrees.
+    #
+    def to_degrees(radians)
+      (radians * 180.0) / Math::PI
+    end
+
+    ##
+    # Conversion factor: km to mi.
+    #
+    def km_in_mi
+      0.621371192
+    end
+  end
+end

data/lib/geocoder/lookup.rb

@@ -0,0 +1,78 @@
+require 'net/http'
+
+module Geocoder
+  module Lookup
+    extend self
+
+    ##
+    # Query Google for the coordinates of the given address.
+    # Returns array [lat,lon] if found, nil if not found or if network error.
+    #
+    def coordinates(address)
+      return nil if address.blank?
+      return nil unless doc = search(address, false)
+      # blindly use first result (assume it is most accurate)
+      place = doc['results'].first['geometry']['location']
+      ['lat', 'lng'].map{ |i| place[i] }
+    end
+
+    ##
+    # Query Google for the address of the given coordinates.
+    # Returns string if found, nil if not found or if network error.
+    #
+    def address(latitude, longitude)
+      return nil if latitude.blank? || longitude.blank?
+      return nil unless doc = search("#{latitude},#{longitude}", true)
+      # blindly use first result (assume it is most accurate)
+      doc['results'].first['formatted_address']
+    end
+
+
+    private # ---------------------------------------------------------------
+
+    ##
+    # Query Google for geographic information about the given phrase.
+    # Returns a hash representing a valid geocoder response.
+    # Returns nil if non-200 HTTP response, timeout, or other error.
+    #
+    def search(query, reverse = false)
+      doc = fetch_parsed_response(query, reverse)
+      doc && doc['status'] == "OK" ? doc : nil
+    end
+
+    ##
+    # Returns a parsed Google geocoder search result (hash).
+    # This method is not intended for general use (prefer Geocoder.search).
+    #
+    def fetch_parsed_response(query, reverse = false)
+      if doc = fetch_raw_response(query, reverse)
+        ActiveSupport::JSON.decode(doc)
+      end
+    end
+
+    ##
+    # Returns a raw Google geocoder search result (JSON).
+    # This method is not intended for general use (prefer Geocoder.search).
+    #
+    def fetch_raw_response(query, reverse = false)
+      return nil if query.blank?
+
+      # name parameter based on forward/reverse geocoding
+      param = reverse ? :latlng : :address
+
+      # build URL
+      params = { param => query, :sensor  => "false" }
+      url = "http://maps.google.com/maps/api/geocode/json?" + params.to_query
+
+      # query geocoder and make sure it responds quickly
+      begin
+        resp = nil
+        timeout(3) do
+          Net::HTTP.get_response(URI.parse(url)).body
+        end
+      rescue SocketError, TimeoutError
+        return nil
+      end
+    end
+  end
+end

data/test/geocoder_test.rb

@@ -10,14 +10,21 @@ class GeocoderTest < Test::Unit::TestCase
 
   # sanity check
   def test_distance_between
-    assert_equal 69, Geocoder.distance_between(0,0, 0,1).round
+    assert_equal 69, Geocoder::Calculations.distance_between(0,0, 0,1).round
   end
 
   # sanity check
   def test_geographic_center
     assert_equal [0.0, 0.5],
-      Geocoder.geographic_center([[0,0], [0,1]])
+      Geocoder::Calculations.geographic_center([[0,0], [0,1]])
     assert_equal [0.0, 1.0],
-      Geocoder.geographic_center([[0,0], [0,1], [0,2]])
+      Geocoder::Calculations.geographic_center([[0,0], [0,1], [0,2]])
+  end
+
+  def test_exception_raised_for_unconfigured_geocoding
+    l = Landmark.new("Mount Rushmore", 43.88, -103.46)
+    assert_raises GeocoderConfigurationError do
+      l.fetch_coordinates
+    end
   end
 end

data/test/test_helper.rb

@@ -35,11 +35,13 @@ end
 require 'geocoder'
 
 ##
-# Mock HTTP request to Google.
+# Mock HTTP request to geocoding service.
 #
 module Geocoder
-  def self._fetch_raw_response(query)
-    File.read(File.join("test", "fixtures", "madison_square_garden.json"))
+  module Lookup
+    def self.fetch_raw_response(query, reverse = false)
+      File.read(File.join("test", "fixtures", "madison_square_garden.json"))
+    end
   end
 end
 
@@ -63,6 +65,27 @@ class Venue < ActiveRecord::Base
   end
 end
 
+##
+# Reverse geocoded model.
+#
+class Landmark < ActiveRecord::Base
+  reverse_geocoded_by :latitude, :longitude
+
+  def initialize(name, latitude, longitude)
+    super()
+    write_attribute :name, name
+    write_attribute :latitude, latitude
+    write_attribute :longitude, longitude
+  end
+
+  ##
+  # If method not found, assume it's an ActiveRecord attribute reader.
+  #
+  def method_missing(name, *args, &block)
+    @attributes[name]
+  end
+end
+
 class Test::Unit::TestCase
   def venue_params(abbrev)
     {

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rails-geocoder
 version: !ruby/object:Gem::Version 
-  hash: 55
+  hash: 53
   prerelease: false
   segments: 
   - 0
   - 9
-  - 6
-  version: 0.9.6
+  - 7
+  version: 0.9.7
 platform: ruby
 authors: 
 - Alex Reisner
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-18 00:00:00 -05:00
+date: 2011-02-01 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -30,6 +30,9 @@ extra_rdoc_files: []
 
 files: 
 - lib/geocoder.rb
+- lib/geocoder/lookup.rb
+- lib/geocoder/calculations.rb
+- lib/geocoder/active_record.rb
 - test/test_helper.rb
 - test/geocoder_test.rb
 - CHANGELOG.rdoc