rails-geocoder 0.8.5 → 0.8.6

data/CHANGELOG.rdoc

@@ -2,6 +2,11 @@
 
 Per-release changes to Geocoder.
 
+== 0.8.6 (2009 Oct 27)
+
+* The fetch_coordinates method now assigns coordinates to attributes (behaves like fetch_coordinates! used to) and fetch_coordinates! both assigns and saves the attributes.
+* Added geocode:all rake task.
+
 == 0.8.5 (2009 Oct 26)
 
 * Avoid calling deprecated method from within Geocoder itself.

data/README.rdoc

@@ -1,6 +1,9 @@
 = Geocoder
 
-Geocoder adds object geocoding and database-agnostic distance calculations to Ruby on Rails. It does not rely on proprietary database functions so finding geocoded objects in a given area is easily done using out-of-the-box MySQL or even SQLite.
+Geocoder adds object geocoding and database-agnostic distance calculations to Ruby on Rails. It's as simple as calling <tt>fetch_coordinates!</tt> on your objects, and then using a named scope like <tt>Venue.near("Billings, MT")</tt>.
+
+Geocoder does not rely on proprietary database functions so finding geocoded objects in a given area is easily done using out-of-the-box MySQL or even SQLite.
+
 
 == 1. Install
 
@@ -16,51 +19,53 @@ or as a gem:
   # at command prompt:
   sudo rake gems:install
 
+
 == 2. Configure
 
-First, you must get a Google Maps API key (to get one go to http://code.google.com/apis/maps/signup.html) and store it in a constant:
+A) Get a Google Maps API key (see http://code.google.com/apis/maps/signup.html) and store it in a constant:
 
+  # eg, in config/initializers/google_maps.rb
   GOOGLE_MAPS_API_KEY = "..."
 
-To add geocoding features to a class:
+B) Add +latitude+ and +longitude+ columns to your model:
 
-  geocoded_by :location
+  script/generate migration AddLatitudeAndLongitudeToYourModel latitude:float longitude:float
+  rake db:migrate
 
-Be sure your class defines attributes for storing latitude and longitude (use +float+ or +double+ database columns) and a location (human-readable address to be geocoded). These attribute names are all configurable; for example, to use +address+, +lat+, and +lon+ respectively:
+C) Tell geocoder where your model stores its address:
 
-  geocoded_by :address, :latitude  => :lat, :longitude => :lon
+  geocoded_by :address
 
-A geocodable string is anything you'd use to search Google Maps. Any of the following are acceptable:
+D) Optionally, auto-fetch coordinates every time your model is saved:
 
-  714 Green St, Big Town, MO
-  Eiffel Tower, Paris, FR
-  Paris, TX, US
+  after_validation :fetch_coordinates
 
-If your model has +address+, +city+, +state+, and +country+ attributes your +location+ method might look something like this:
+<i>Note that you are not stuck with the +latitude+ and +longitude+ column names, or the +address+ method. See "More On Configuration" below for details.</i>
 
-  def location
-    [address, city, state, country].compact.join(', ')
-  end
 
 == 3. Use
 
-Assuming +Venue+ is a geocoded model, it has the following named scopes:
+Assuming +obj+ is an instance of a geocoded class, you can get its coordinates:
 
-  Venue.near('Omaha, NE, US', 20)    # venues within 20 miles of Omaha
-  Venue.near([40.71, 100.23], 20)    # venues within 20 miles of a point
-  Venue.geocoded                     # venues with coordinates
-  Venue.not_geocoded                 # venues without coordinates
+  obj.fetch_coordinates              # fetches and assigns coordinates
+  obj.fetch_coordinates!             # also saves lat, lon attributes
 
-Assuming +obj+ has a valid string for its +location+:
+If you have a lot of objects you can use this Rake task to geocode them all:
 
-  obj.fetch_coordinates              # returns coordinates [lat, lon]
-  obj.fetch_coordinates!             # also writes coordinates to object
+  rake geocode:all CLASS=YourModel
 
-Assuming +obj+ is geocoded (has latitude and longitude):
+Once +obj+ is geocoded you can do things like this:
 
   obj.nearbys(30)                    # other objects within 30 miles
   obj.distance_to(40.714, -100.234)  # distance to arbitrary point
 
+To find objects by location, use the following named scopes:
+
+  Venue.near('Omaha, NE, US', 20)    # venues within 20 miles of Omaha
+  Venue.near([40.71, 100.23], 20)    # venues within 20 miles of a point
+  Venue.geocoded                     # venues with coordinates
+  Venue.not_geocoded                 # venues without coordinates
+
 Some utility methods are also available:
 
   # distance (in miles) between Eiffel Tower and Empire State Building
@@ -70,7 +75,33 @@ Some utility methods are also available:
   Geocoder.fetch_coordinates("25 Main St, Cooperstown, NY")
 
 
+== More On Configuration
+
+You are not stuck with using the +latitude+ and +longitude+ database column names for storing coordinates. For example, to use +lat+ and +lon+:
+
+  geocoded_by :address, :latitude  => :lat, :longitude => :lon
+
+The string to use for geocoding can be anything you'd use to search Google Maps. For example, any of the following are acceptable:
+
+  714 Green St, Big Town, MO
+  Eiffel Tower, Paris, FR
+  Paris, TX, US
+
+If your model has +address+, +city+, +state+, and +country+ attributes you might do something like this:
+
+  geocoded_by :location
+
+  def location
+    [address, city, state, country].compact.join(', ')
+  end
+
+
 Please see the code for more methods and detailed information about arguments (eg, working with kilometers).
 
-  
+
+== To-do List
+
+* <tt>install.rb</tt> should do some setup when installed as a plugin
+
+
 Copyright (c) 2009 Alex Reisner, released under the MIT license

data/VERSION

@@ -1 +1 @@
-0.8.5
+0.8.6

data/lib/geocoder.rb

@@ -121,8 +121,8 @@ module Geocoder
   end
   
   ##
-  # Calculate the distance from the object to a point (lat,lon). Valid units
-  # are defined in <tt>distance_between</tt> class method.
+  # 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?
@@ -131,34 +131,37 @@ module Geocoder
   end
   
   ##
-  # Get other geocoded objects within a given radius.
-  # The object must be geocoded before this method is called.
+  # Get other geocoded objects within a given radius (in miles). Takes a
+  # radius (in miles) and options for passing to the +near+ named scope
+  # (<tt>:order</tt>, <tt>:limit</tt>, and <tt>:offset</tt>).
   #
-  def nearbys(radius = 20)
+  def nearbys(radius = 20, options = {})
     return [] unless geocoded?
-    lat,lon = self.class._get_coordinates(self)
-    self.class.near([lat, lon], radius) - [self]
+    coords  = self.class._get_coordinates(self)
+    options = {:conditions => ["id != ?", id]}.merge(options)
+    self.class.near(coords, radius, options) - [self]
   end
   
   ##
-  # Fetch coordinates based on the object's location.
-  # Returns an array <tt>[lat,lon]</tt>.
+  # Fetch coordinates and assign +latitude+ and +longitude+. Also returns
+  # coordinates as an array: <tt>[lat, lon]</tt>.
   #
-  def fetch_coordinates
+  def fetch_coordinates(save = false)
     location = send(self.class.geocoder_options[:method_name])
-    Geocoder.fetch_coordinates(location)
+    returning Geocoder.fetch_coordinates(location) do |c|
+      unless c.blank?
+        method = (save ? "update" : "write") + "_attribute"
+        send method, self.class.geocoder_options[:latitude], c[0]
+        send method, self.class.geocoder_options[:longitude], c[1]
+      end
+    end
   end
-  
+
   ##
-  # Fetch coordinates and assign +latitude+ and +longitude+.
+  # Fetch coordinates and update (save) +latitude+ and +longitude+ data.
   #
   def fetch_coordinates!
-    returning fetch_coordinates do |c|
-      unless c.blank?
-        write_attribute(self.class.geocoder_options[:latitude], c[0])
-        write_attribute(self.class.geocoder_options[:longitude], c[1])
-      end
-    end
+    fetch_coordinates(true)
   end
 
   ##
@@ -184,7 +187,7 @@ module Geocoder
   # Calculate the distance between two points on Earth (Haversine formula).
   # Takes two sets of coordinates and an options hash:
   # 
-  # +units+ :: <tt>:mi</tt> for miles (default), <tt>:km</tt> for kilometers
+  # <tt>:units</tt> :: <tt>:mi</tt> (default) or <tt>:km</tt>
   #
   def self.distance_between(lat1, lon1, lat2, lon2, options = {})
     

data/rails-geocoder.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rails-geocoder}
-  s.version = "0.8.5"
+  s.version = "0.8.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Reisner"]
-  s.date = %q{2009-10-26}
+  s.date = %q{2009-10-27}
   s.description = %q{Geocoder adds object geocoding and database-agnostic distance calculations to Ruby on Rails. It does not rely on proprietary database functions so finding geocoded objects in a given area is easily done using out-of-the-box MySQL or even SQLite.}
   s.email = %q{alex@alexreisner.com}
   s.extra_rdoc_files = [
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
      "init.rb",
      "lib/geocoder.rb",
      "rails-geocoder.gemspec",
+     "tasks/geocoder_tasks.rake",
      "test/fixtures/madison_square_garden.xml",
      "test/geocoder_test.rb",
      "test/test_helper.rb"

data/tasks/geocoder_tasks.rake

@@ -0,0 +1,15 @@
+def klass
+  class_name = ENV['CLASS'] || ENV['class']
+  raise "Please specify a CLASS (model)" unless class_name
+  Object.const_get(class_name)
+end
+
+namespace :geocode do
+
+  desc "Geocode all objects without coordinates."
+  task :all => :environment do
+    klass.not_geocoded.each do |obj|
+      obj.fetch_coordinates!
+    end
+  end
+end

data/test/geocoder_test.rb

@@ -5,11 +5,6 @@ class GeocoderTest < Test::Unit::TestCase
   def test_fetch_coordinates
     v = Venue.new(*venue_params(:msg))
     assert_equal [40.7495760, -73.9916733], v.fetch_coordinates
-  end
-
-  def test_fetch_coordinates!
-    v = Venue.new(*venue_params(:msg))
-    v.fetch_coordinates!
     assert_equal [40.7495760, -73.9916733], [v.latitude, v.longitude]
   end
 end

data/test/test_helper.rb

@@ -24,6 +24,10 @@ module ActiveRecord
       @attributes[attr_name] = value
     end
     
+    def update_attribute(attr_name, value)
+      write_attribute(attr_name, value)
+    end
+    
     def self.named_scope(*args); end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rails-geocoder
 version: !ruby/object:Gem::Version 
-  version: 0.8.5
+  version: 0.8.6
 platform: ruby
 authors: 
 - Alex Reisner
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-26 00:00:00 -04:00
+date: 2009-10-27 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -33,6 +33,7 @@ files:
 - init.rb
 - lib/geocoder.rb
 - rails-geocoder.gemspec
+- tasks/geocoder_tasks.rake
 - test/fixtures/madison_square_garden.xml
 - test/geocoder_test.rb
 - test/test_helper.rb