geocoder 1.0.1 → 1.0.2

data/CHANGELOG.rdoc

@@ -2,6 +2,12 @@
 
 Per-release changes to Geocoder.
 
+== 1.0.2 (2011 June 25)
+
+* Add support for MongoMapper (thanks github.com/spagalloco).
+* Fix: user-specified coordinates field wasn't working with Mongoid (thanks github.com/thisduck).
+* Fix: invalid location given to near scope was returning all results (Active Record) or error (Mongoid) (thanks github.com/ogennadi).
+
 == 1.0.1 (2011 May 17)
 
 * Add option to not rescue from certain exceptions (thanks github.com/ahmedrb).

data/README.rdoc

@@ -77,6 +77,10 @@ Reverse geocoding is similar:
   reverse_geocoded_by :coordinates
   after_validation :reverse_geocode  # auto-fetch address
 
+=== MongoMapper
+
+MongoMapper is very similar to Mongoid, just be sure to include <tt>Geocoder::Model::Mongoid</tt>.
+
 === Bulk Geocoding
 
 If you have just added geocoding to an existing application with a lot of objects you can use this Rake task to geocode them all:
@@ -152,7 +156,7 @@ You can convert these numbers to compass point names by using the utility method
 
 <i>Note: when using SQLite +distance+ and +bearing+ values are provided for interface consistency only. They are not very accurate.</i>
 
-To calculate accurate distance and bearing with SQLite or Mongoid:
+To calculate accurate distance and bearing with SQLite or MongoDB:
 
   obj.distance_to([43.9,-98.6])  # distance from obj to point
   obj.bearing_to([43.9,-98.6])   # bearing from obj to point
@@ -163,10 +167,10 @@ The <tt>bearing_from/to</tt> methods take a single argument which can be: a <tt>
 
 == More on Configuration
 
-You are not stuck with using the +latitude+ and +longitude+ database column names (with ActiveRecord) or the +coordinates+ array (Mongoid) for storing coordinates. For example:
+You are not stuck with using the +latitude+ and +longitude+ database column names (with ActiveRecord) or the +coordinates+ array (Mongo) for storing coordinates. For example:
 
   geocoded_by :address, :latitude  => :lat, :longitude => :lon # ActiveRecord
-  geocoded_by :address, :coordinates => :coords                # Mongoid
+  geocoded_by :address, :coordinates => :coords                # MongoDB
 
 The +address+ method can return any string you'd use to search Google Maps. For example, any of the following are acceptable:
 
@@ -185,7 +189,7 @@ If your model has +street+, +city+, +state+, and +country+ attributes you might
 For reverse geocoding you can also specify an alternate name attribute where the address will be stored, for example:
 
   reverse_geocoded_by :lat, :lon, :address => :location  # ActiveRecord
-  reverse_geocoded_by :coordinates, :address => :loc     # Mongoid
+  reverse_geocoded_by :coordinates, :address => :loc     # MongoDB
 
 
 == Advanced Geocoding
@@ -211,7 +215,7 @@ Every <tt>Geocoder::Result</tt> object, +result+, provides the following data:
 * <tt>result.state</tt> - string
 * <tt>result.state_code</tt> - string
 * <tt>result.postal_code</tt> - string
-* <tt>result.country_name</tt> - string
+* <tt>result.country</tt> - string
 * <tt>result.country_code</tt> - string
 
 If you're familiar with the results returned by the geocoding service you're using you can access even more data, but you'll need to be familiar with the particular <tt>Geocoder::Result</tt> object you're using and the structure of your geocoding service's responses. (See below for links to geocoding service documentation.)
@@ -410,15 +414,15 @@ When you install the Geocoder gem it adds a +geocode+ command to your shell. You
 There are also a number of options for setting the geocoding API, key, and language, viewing the raw JSON reponse, and more. Please run <tt>geocode -h</tt> for details.
 
 
-== Notes on Mongoid
+== Notes on MongoDB
 
 === The Near Method
 
-Mongoid document classes have a built-in +near+ scope, but since it only works two-dimensions Geocoder overrides it with its own spherical +near+ method in geocoded classes.
+Mongo document classes (Mongoid and MongoMapper) have a built-in +near+ scope, but since it only works two-dimensions Geocoder overrides it with its own spherical +near+ method in geocoded classes.
 
 === Latitude/Longitude Order
 
-Coordinates are generally printed and spoken as latitude, then logitude ([lat,lon]). Geocoder respects this convention and always expects method arguments to be given in [lat,lon] order. However, MongoDB requires that coordinates be stored in [lon,lat] order as per the GeoJSON spec (http://geojson.org/geojson-spec.html#positions), so internally they are stored "backwards." However, this does not affect order of arguments to methods when using Mongoid.
+Coordinates are generally printed and spoken as latitude, then logitude ([lat,lon]). Geocoder respects this convention and always expects method arguments to be given in [lat,lon] order. However, MongoDB requires that coordinates be stored in [lon,lat] order as per the GeoJSON spec (http://geojson.org/geojson-spec.html#positions), so internally they are stored "backwards." However, this does not affect order of arguments to methods when using Mongoid or MongoMapper.
 
 
 == Distance Queries in SQLite

data/lib/geocoder.rb

@@ -4,6 +4,7 @@ require "geocoder/cache"
 require "geocoder/request"
 require "geocoder/models/active_record"
 require "geocoder/models/mongoid"
+require "geocoder/models/mongo_mapper"
 
 module Geocoder
   extend self

data/lib/geocoder/models/mongo_base.rb

@@ -0,0 +1,55 @@
+require 'geocoder'
+
+module Geocoder
+
+  ##
+  # Methods for invoking Geocoder in a model.
+  #
+  module Model
+    module MongoBase
+
+      ##
+      # Set attribute names and include the Geocoder module.
+      #
+      def geocoded_by(address_attr, options = {}, &block)
+        geocoder_init(
+          :geocode       => true,
+          :user_address  => address_attr,
+          :coordinates   => options[:coordinates] || :coordinates,
+          :geocode_block => block
+        )
+      end
+
+      ##
+      # Set attribute names and include the Geocoder module.
+      #
+      def reverse_geocoded_by(coordinates_attr, options = {}, &block)
+        geocoder_init(
+          :reverse_geocode => true,
+          :fetched_address => options[:address] || :address,
+          :coordinates     => coordinates_attr,
+          :reverse_block   => block
+        )
+      end
+
+      private # ----------------------------------------------------------------
+
+      def geocoder_init(options)
+        unless geocoder_initialized?
+          @geocoder_options = {}
+          require "geocoder/stores/#{geocoder_file_name}"
+          include eval("Geocoder::Store::" + geocoder_module_name)
+        end
+        @geocoder_options.merge! options
+      end
+
+      def geocoder_initialized?
+        begin
+          included_modules.include? eval("Geocoder::Store::" + geocoder_module_name)
+        rescue NameError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/geocoder/models/mongo_mapper.rb

@@ -0,0 +1,24 @@
+require 'geocoder/models/base'
+require 'geocoder/models/mongo_base'
+
+module Geocoder
+  module Model
+    module MongoMapper
+      include Base
+      include MongoBase
+
+      def self.included(base); base.extend(self); end
+
+      private # --------------------------------------------------------------
+
+      def geocoder_file_name;   "mongo_mapper"; end
+      def geocoder_module_name; "MongoMapper"; end
+
+      def geocoder_init(options)
+        super(options)
+        ensure_index [[ geocoder_options[:coordinates], Mongo::GEO2D ]],
+          :min => -180, :max => 180 # create 2d index
+      end
+    end
+  end
+end

data/lib/geocoder/models/mongoid.rb

@@ -1,37 +1,14 @@
 require 'geocoder/models/base'
+require 'geocoder/models/mongo_base'
 
 module Geocoder
   module Model
     module Mongoid
       include Base
+      include MongoBase
 
       def self.included(base); base.extend(self); end
 
-      ##
-      # Set attribute names and include the Geocoder module.
-      #
-      def geocoded_by(address_attr, options = {}, &block)
-        geocoder_init(
-          :geocode       => true,
-          :user_address  => address_attr,
-          :coordinates   => options[:coordinates] || :coordinates,
-          :geocode_block => block
-        )
-      end
-
-      ##
-      # Set attribute names and include the Geocoder module.
-      #
-      def reverse_geocoded_by(coordinates_attr, options = {}, &block)
-        geocoder_init(
-          :reverse_geocode => true,
-          :fetched_address => options[:address] || :address,
-          :coordinates     => coordinates_attr,
-          :reverse_block   => block
-        )
-      end
-
-
       private # --------------------------------------------------------------
 
       def geocoder_file_name;   "mongoid"; end

data/lib/geocoder/stores/active_record.rb

@@ -36,7 +36,7 @@ module Geocoder::Store
           if latitude and longitude
             near_scope_options(latitude, longitude, *args)
           else
-            {}
+            where(:id => false) # no results if no lat/lon given
           end
         }
       end

data/lib/geocoder/stores/mongo_base.rb

@@ -0,0 +1,81 @@
+module Geocoder::Store
+  module MongoBase
+
+    def self.included_by_model(base)
+      base.class_eval do
+
+        scope :geocoded, lambda {
+          where(geocoder_options[:coordinates].ne => nil)
+        }
+
+        scope :not_geocoded, lambda {
+          where(geocoder_options[:coordinates] => nil)
+        }
+
+        scope :near, lambda{ |location, *args|
+          coords  = Geocoder::Calculations.extract_coordinates(location)
+
+          # no results if no lat/lon given
+          return where(:id => false) unless coords.is_a?(Array)
+
+          radius  = args.size > 0 ? args.shift : 20
+          options = args.size > 0 ? args.shift : {}
+
+          # Use BSON::OrderedHash if Ruby's hashes are unordered.
+          # Conditions must be in order required by indexes (see mongo gem).
+          empty = RUBY_VERSION.split('.')[1].to_i < 9 ? BSON::OrderedHash.new : {}
+
+          conds = empty.clone
+          field = geocoder_options[:coordinates]
+          conds[field] = empty.clone
+          conds[field]["$nearSphere"]  = coords.reverse
+          conds[field]["$maxDistance"] = \
+            Geocoder::Calculations.distance_to_radians(radius, options[:units] || :mi)
+
+          if obj = options[:exclude]
+            conds[:_id.ne] = obj.id
+          end
+          where(conds)
+        }
+      end
+    end
+
+    ##
+    # Coordinates [lat,lon] of the object.
+    # This method always returns coordinates in lat,lon order,
+    # even though internally they are stored in the opposite order.
+    #
+    def to_coordinates
+      coords = send(self.class.geocoder_options[:coordinates])
+      coords.is_a?(Array) ? coords.reverse : []
+    end
+
+    ##
+    # Look up coordinates and assign to +latitude+ and +longitude+ attributes
+    # (or other as specified in +geocoded_by+). Returns coordinates (array).
+    #
+    def geocode
+      do_lookup(false) do |o,rs|
+        r = rs.first
+        unless r.coordinates.nil?
+          o.send :write_attribute, self.class.geocoder_options[:coordinates], r.coordinates.reverse
+        end
+        r.coordinates
+      end
+    end
+
+    ##
+    # Look up address and assign to +address+ attribute (or other as specified
+    # in +reverse_geocoded_by+). Returns address (string).
+    #
+    def reverse_geocode
+      do_lookup(true) do |o,rs|
+        r = rs.first
+        unless r.address.nil?
+          o.send :write_attribute, self.class.geocoder_options[:fetched_address], r.address
+        end
+        r.address
+      end
+    end
+  end
+end

data/lib/geocoder/stores/mongo_mapper.rb

@@ -0,0 +1,13 @@
+require 'geocoder/stores/base'
+require 'geocoder/stores/mongo_base'
+
+module Geocoder::Store
+  module MongoMapper
+    include Base
+    include MongoBase
+
+    def self.included(base)
+      MongoBase.included_by_model(base)
+    end
+  end
+end

data/lib/geocoder/stores/mongoid.rb

@@ -1,79 +1,13 @@
 require 'geocoder/stores/base'
+require 'geocoder/stores/mongo_base'
 
 module Geocoder::Store
   module Mongoid
     include Base
+    include MongoBase
 
     def self.included(base)
-      base.class_eval do
-
-        scope :geocoded, lambda {
-          where(geocoder_options[:coordinates].ne => nil)
-        }
-
-        scope :not_geocoded, lambda {
-          where(geocoder_options[:coordinates] => nil)
-        }
-
-        scope :near, lambda{ |location, *args|
-          coords  = Geocoder::Calculations.extract_coordinates(location)
-          radius  = args.size > 0 ? args.shift : 20
-          options = args.size > 0 ? args.shift : {}
-
-          # Use BSON::OrderedHash if Ruby's hashes are unordered.
-          # Conditions must be in order required by indexes (see mongo gem).
-          empty = RUBY_VERSION.split('.')[1].to_i < 9 ? BSON::OrderedHash.new : {}
-
-          conds = empty.clone
-          conds[:coordinates] = empty.clone
-          conds[:coordinates]["$nearSphere"]  = coords.reverse
-          conds[:coordinates]["$maxDistance"] = \
-            Geocoder::Calculations.distance_to_radians(radius, options[:units] || :mi)
-
-          if obj = options[:exclude]
-            conds[:_id.ne] = obj.id
-          end
-          criteria.where(conds)
-        }
-      end
-    end
-
-    ##
-    # Coordinates [lat,lon] of the object.
-    # This method always returns coordinates in lat,lon order,
-    # even though internally they are stored in the opposite order.
-    #
-    def to_coordinates
-      coords = send(self.class.geocoder_options[:coordinates])
-      coords.is_a?(Array) ? coords.reverse : []
-    end
-
-    ##
-    # Look up coordinates and assign to +latitude+ and +longitude+ attributes
-    # (or other as specified in +geocoded_by+). Returns coordinates (array).
-    #
-    def geocode
-      do_lookup(false) do |o,rs|
-        r = rs.first
-        unless r.coordinates.nil?
-          o.send :write_attribute, self.class.geocoder_options[:coordinates], r.coordinates.reverse
-        end
-        r.coordinates
-      end
-    end
-
-    ##
-    # Look up address and assign to +address+ attribute (or other as specified
-    # in +reverse_geocoded_by+). Returns address (string).
-    #
-    def reverse_geocode
-      do_lookup(true) do |o,rs|
-        r = rs.first
-        unless r.address.nil?
-          o.send :write_attribute, self.class.geocoder_options[:fetched_address], r.address
-        end
-        r.address
-      end
+      MongoBase.included_by_model(base)
     end
   end
 end

data/lib/geocoder/version.rb

@@ -1,3 +1,3 @@
 module Geocoder
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/test/calculations_test.rb

@@ -0,0 +1,147 @@
+# encoding: utf-8
+require 'test_helper'
+
+class CalculationsTest < Test::Unit::TestCase
+
+
+  # --- degree distance ---
+
+  def test_longitude_degree_distance_at_equator
+    assert_equal 69, Geocoder::Calculations.longitude_degree_distance(0).round
+  end
+
+  def test_longitude_degree_distance_at_new_york
+    assert_equal 53, Geocoder::Calculations.longitude_degree_distance(40).round
+  end
+
+  def test_longitude_degree_distance_at_north_pole
+    assert_equal 0, Geocoder::Calculations.longitude_degree_distance(89.98).round
+  end
+
+
+  # --- distance between ---
+
+  def test_distance_between_in_miles
+    assert_equal 69, Geocoder::Calculations.distance_between([0,0], [0,1]).round
+    la_to_ny = Geocoder::Calculations.distance_between([34.05,-118.25], [40.72,-74]).round
+    assert (la_to_ny - 2444).abs < 10
+  end
+
+  def test_distance_between_in_kilometers
+    assert_equal 111, Geocoder::Calculations.distance_between([0,0], [0,1], :units => :km).round
+    la_to_ny = Geocoder::Calculations.distance_between([34.05,-118.25], [40.72,-74], :units => :km).round
+    assert (la_to_ny - 3942).abs < 10
+  end
+
+
+  # --- geographic center ---
+
+  def test_geographic_center_with_arrays
+    assert_equal [0.0, 0.5],
+      Geocoder::Calculations.geographic_center([[0,0], [0,1]])
+    assert_equal [0.0, 1.0],
+      Geocoder::Calculations.geographic_center([[0,0], [0,1], [0,2]])
+  end
+
+  def test_geographic_center_with_mixed_arguments
+    p1 = [0, 0]
+    p2 = Landmark.new("Some Cold Place", 0, 1)
+    assert_equal [0.0, 0.5], Geocoder::Calculations.geographic_center([p1, p2])
+  end
+
+
+  # --- bounding box ---
+
+  def test_bounding_box_calculation_in_miles
+    center = [51, 7] # Cologne, DE
+    radius = 10 # miles
+    dlon = radius / Geocoder::Calculations.latitude_degree_distance
+    dlat = radius / Geocoder::Calculations.longitude_degree_distance(center[0])
+    corners = [50.86, 6.77, 51.14, 7.23]
+    assert_equal corners.map{ |i| (i * 100).round },
+      Geocoder::Calculations.bounding_box(center, radius).map{ |i| (i * 100).round }
+  end
+
+  def test_bounding_box_calculation_in_kilometers
+    center = [51, 7] # Cologne, DE
+    radius = 111 # kilometers (= 1 degree latitude)
+    dlon = radius / Geocoder::Calculations.latitude_degree_distance(:km)
+    dlat = radius / Geocoder::Calculations.longitude_degree_distance(center[0], :km)
+    corners = [50, 5.41, 52, 8.59]
+    assert_equal corners.map{ |i| (i * 100).round },
+      Geocoder::Calculations.bounding_box(center, radius, :units => :km).map{ |i| (i * 100).round }
+  end
+
+  def test_bounding_box_calculation_with_object
+    center = [51, 7] # Cologne, DE
+    radius = 10 # miles
+    dlon = radius / Geocoder::Calculations.latitude_degree_distance
+    dlat = radius / Geocoder::Calculations.longitude_degree_distance(center[0])
+    corners = [50.86, 6.77, 51.14, 7.23]
+    obj = Landmark.new("Cologne", center[0], center[1])
+    assert_equal corners.map{ |i| (i * 100).round },
+      Geocoder::Calculations.bounding_box(obj, radius).map{ |i| (i * 100).round }
+  end
+
+  def test_bounding_box_calculation_with_address_string
+    assert_nothing_raised do
+      Geocoder::Calculations.bounding_box("4893 Clay St, San Francisco, CA", 50)
+    end
+  end
+
+
+  # --- bearing ---
+
+  def test_compass_points
+    assert_equal "N",  Geocoder::Calculations.compass_point(0)
+    assert_equal "N",  Geocoder::Calculations.compass_point(1.0)
+    assert_equal "N",  Geocoder::Calculations.compass_point(360)
+    assert_equal "N",  Geocoder::Calculations.compass_point(361)
+    assert_equal "N",  Geocoder::Calculations.compass_point(-22)
+    assert_equal "NW", Geocoder::Calculations.compass_point(-23)
+    assert_equal "S",  Geocoder::Calculations.compass_point(180)
+    assert_equal "S",  Geocoder::Calculations.compass_point(181)
+  end
+
+  def test_bearing_between
+    bearings = {
+      :n => 0,
+      :e => 90,
+      :s => 180,
+      :w => 270
+    }
+    points = {
+      :n => [41, -75],
+      :e => [40, -74],
+      :s => [39, -75],
+      :w => [40, -76]
+    }
+    directions = [:n, :e, :s, :w]
+    methods = [:linear, :spherical]
+
+    methods.each do |m|
+      directions.each_with_index do |d,i|
+        opp = directions[(i + 2) % 4] # opposite direction
+        b = Geocoder::Calculations.bearing_between(
+          points[d], points[opp], :method => m)
+        assert (b - bearings[opp]).abs < 1,
+          "Bearing (#{m}) should be close to #{bearings[opp]} but was #{b}."
+      end
+    end
+  end
+
+  def test_spherical_bearing_to
+    l = Landmark.new(*landmark_params(:msg))
+    assert_equal 324, l.bearing_to([50,-85], :method => :spherical).round
+  end
+
+  def test_spherical_bearing_from
+    l = Landmark.new(*landmark_params(:msg))
+    assert_equal 136, l.bearing_from([50,-85], :method => :spherical).round
+  end
+
+  def test_linear_bearing_from_and_to_are_exactly_opposite
+    l = Landmark.new(*landmark_params(:msg))
+    assert_equal l.bearing_from([50,-86.1]), l.bearing_to([50,-86.1]) - 180
+  end
+end