acts_as_geocodable 1.0.0

data/.gitignore

@@ -0,0 +1,2 @@
+debug.log
+pkg

data/CHANGELOG

@@ -0,0 +1,13 @@
+0.2.1 - 2008-8-8
+* Results are now WillPaginate compatible
+
+0.2.0 - 2007-10-27
+* Added validates_as_geocodable (Mark Van Holstyn)
+* Allow address mapping to be a single field (Mark Van Holstyn)
+
+0.1.0
+* Added remote_location to get a users location based on their remote_ip
+* renamed :city to :locality in address mapping to be consistent with Graticule 0.2
+  create a migration with:
+    rename_column :geocodes, :city, :locality
+* replace #full_address with #to_location

data/MIT-LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2006 Daniel Morrison, Collective Idea 
+http://collectiveidea.com
+
+Testing code was heavily influenced by Rick Olson.  Thanks, Rick!
+Testing Portions Copyright (c) 2006 Rick Olson
+http://techno-weenie.net
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,104 @@
+= acts_as_geocodable
+
+acts_as_geocodable is a plugin to help build geo-aware applications. It automatically geocodes your models when they are saved, giving you the ability to search by location and calculate distances between records.
+
+== Usage
+
+  event = Event.create :street => "777 NE Martin Luther King, Jr. Blvd.",
+    :locality => "Portland", :region => "Oregon", :postal_code => 97232
+    
+  event.geocode.latitude                                #=> 45.529100000000
+  event.geocode.longitude                               #=> -122.644200000000
+  
+  event.distance_to "49423"                             #=> 1807.66560483205
+  
+  Event.find(:all, :within => 50, :origin => "97232")
+  
+  Event.find(:nearest, :origin => "Portland, OR")
+  
+== Upgrading
+
+If you're upgrading from a previous version of this plugin, note that :city has been renamed to :locality to be consistent with Graticule 0.2.  Create a migration that has:
+
+  rename_column :geocodes, :city, :locality
+
+Also remember to change your mapping in your geocodable classes to use the :locality key instead of :city:
+
+class Event < ActiveRecord::Base
+	acts_as_geocodable :address => {:street => :address1, :locality => :city,
+	  :region => :state, :postal_code => :zip}
+end
+
+== Installation
+
+Graticule[link:http://rubyforge.org/projects/graticule] is used for all the heavy lifting.
+
+  gem install graticule --include-dependencies
+
+Install as a plugin
+
+  script/plugin install git://github.com/collectiveidea/acts_as_geocodable.git
+  
+Or, install as a gem
+  
+  gem install acts_as_geocodable --source=http://gemcutter.org
+  
+
+== Upgrading
+  
+Before October 2008, precision wasn't included in the Geocode model. Make sure you add a string precision column to your geocode table if you're upgrading from an older version, and update Graticule.
+
+== Configuration
+
+Create the required tables
+  
+  script/generate geocodable_migration add_geocodable_tables
+  rake db:migrate
+
+Set the default geocoder in your environment.rb file.
+
+  Geocode.geocoder = Graticule.service(:yahoo).new 'your_api_key'
+
+Then, in each model you want to make geocodable, add acts_as_geocodable.
+
+  class Event < ActiveRecord::Base
+  	acts_as_geocodable
+  end
+
+The only requirement is that your model must have address fields. By default, acts_as_geocodable looks for attributes called +street+, +locality+, +region+, +postal_code+, and +country+.  To change these, you can provide a mapping in the <tt>:address</tt> option:
+
+  class Event < ActiveRecord::Base
+  	acts_as_geocodable :address => {:street => :address1, :locality => :city, :region => :state, :postal_code => :zip}
+  end
+
+If that doesn't meet your needs, simply override the default +to_location+ method in your model, and return a Graticule::Location with those attributes set.
+
+acts_as_geocodable can also update your address fields with the data returned from the geocoding service:
+
+  class Event < ActiveRecord::Base
+  	acts_as_geocodable :normalize_address => true
+  end
+
+== IP-based Geocoding
+
+acts_as_geocodable adds a remote_location method in your controllers that uses http://hostip.info to guess remote users location based on their IP address.
+
+  def index
+    @nearest = Store.find(:nearest, :origin => remote_location) if remote_location
+    @stores = Store.find(:all)
+  end
+
+Keep in mind that IP-based geocoding is not always accurate, and often will not return any results.
+
+== Development
+
+The source code is available at:
+   http://github.com/collectiveidea/acts_as_geocodable
+   git://github.com/collectiveidea/acts_as_geocodable.git
+
+Patches and suggestions are welcome!
+
+== To Do
+
+* Documentation!!!
+* configurable formulas

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'load_multi_rails_rake_tasks'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the acts_as_geocodable plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the acts_as_geocodable plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActsAsGeocodable'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'acts_as_geocodable'
+    gemspec.summary = 'Simple geocoding for Rails ActiveRecord models'
+    gemspec.description = 'Simple geocoding for Rails ActiveRecord models. See the README for more details.'
+    gemspec.email = 'info@collectiveidea.com'
+    gemspec.homepage = 'http://github.com/collectiveidea/acts_as_geocodable'
+    gemspec.authors = ['Daniel Morrison', 'Brandon Keepers']
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/about.yml

@@ -0,0 +1,7 @@
+author: 
+    name: Brandon Keepers and Daniel Morrison, Collective Idea
+    homepage: http://collectiveidea.com
+summary: A plugin to help build geo-aware applications
+homepage: http://opensoul.org/2007/2/13/geocoding-as-easy-as-1-2
+plugin: http://source.collectiveidea.com/public/rails/plugins/acts_as_geocodable
+license: MIT

data/acts_as_geocodable.gemspec

@@ -0,0 +1,69 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{acts_as_geocodable}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Daniel Morrison", "Brandon Keepers"]
+  s.date = %q{2009-10-21}
+  s.description = %q{Simple geocoding for Rails ActiveRecord models. See the README for more details.}
+  s.email = %q{info@collectiveidea.com}
+  s.extra_rdoc_files = [
+    "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "CHANGELOG",
+     "MIT-LICENSE",
+     "README",
+     "Rakefile",
+     "VERSION",
+     "about.yml",
+     "acts_as_geocodable.gemspec",
+     "generators/geocodable_migration/USAGE",
+     "generators/geocodable_migration/geocodable_migration_generator.rb",
+     "generators/geocodable_migration/templates/migration.rb",
+     "install.rb",
+     "lib/acts_as_geocodable.rb",
+     "lib/acts_as_geocodable/geocode.rb",
+     "lib/acts_as_geocodable/geocoding.rb",
+     "lib/acts_as_geocodable/remote_location.rb",
+     "lib/acts_as_geocodable/tasks/acts_as_geocodable_tasks.rake",
+     "rails/init.rb",
+     "test/acts_as_geocodable_test.rb",
+     "test/db/database.yml",
+     "test/db/schema.rb",
+     "test/fixtures/cities.yml",
+     "test/fixtures/geocodes.yml",
+     "test/fixtures/geocodings.yml",
+     "test/fixtures/vacations.yml",
+     "test/geocode_test.rb",
+     "test/test_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/collectiveidea/acts_as_geocodable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Simple geocoding for Rails ActiveRecord models}
+  s.test_files = [
+    "test/acts_as_geocodable_test.rb",
+     "test/db/schema.rb",
+     "test/geocode_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/generators/geocodable_migration/USAGE

@@ -0,0 +1,12 @@
+Description:
+	The geocodable migration generator creates a migration which you can use to generate two tables:
+	
+		geocodes - Contains the latitude and longitude coordinates, with the address they refer to.
+		geocodings - The polymorphic join table.
+	
+	
+Example:
+    ./script/generate geocodable_migration add_geocodable_tables
+
+    With 4 existing migrations, this will create an AddGeocodableTables migration in the
+    file db/migrate/5_add_geocodable_tables.rb

data/generators/geocodable_migration/geocodable_migration_generator.rb

@@ -0,0 +1,7 @@
+class GeocodableMigrationGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      m.migration_template 'migration.rb', 'db/migrate'
+    end
+  end
+end

data/generators/geocodable_migration/templates/migration.rb

@@ -0,0 +1,40 @@
+class <%= class_name %> < ActiveRecord::Migration
+  def self.up
+    create_table "geocodes" do |t|
+      t.column "latitude", :decimal, :precision => 15, :scale => 12
+      t.column "longitude", :decimal, :precision => 15, :scale => 12
+      t.column "query", :string
+      t.column "street", :string
+      t.column "locality", :string
+      t.column "region", :string
+      t.column "postal_code", :string
+      t.column "country", :string
+      t.column "precision", :string
+    end
+
+    add_index "geocodes", ["longitude"], :name => "geocodes_longitude_index"
+    add_index "geocodes", ["latitude"], :name => "geocodes_latitude_index"
+    add_index "geocodes", ["query"], :name => "geocodes_query_index", :unique => true
+    add_index "geocodes", ["locality"], :name => "geocodes_locality_index"
+    add_index "geocodes", ["region"], :name => "geocodes_region_index"
+    add_index "geocodes", ["postal_code"], :name => "geocodes_postal_code_index"
+    add_index "geocodes", ["country"], :name => "geocodes_country_index"
+    add_index "geocodes", ["precision"], :name => "geocodes_precision_index"
+    
+
+    create_table "geocodings" do |t|
+      t.column "geocodable_id", :integer
+      t.column "geocode_id", :integer
+      t.column "geocodable_type", :string
+    end
+
+    add_index "geocodings", ["geocodable_type"], :name => "geocodings_geocodable_type_index"
+    add_index "geocodings", ["geocode_id"], :name => "geocodings_geocode_id_index"
+    add_index "geocodings", ["geocodable_id"], :name => "geocodings_geocodable_id_index"
+  end
+
+  def self.down
+    drop_table  :geocodes
+    drop_table  :geocodings
+  end
+end

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/acts_as_geocodable.rb

@@ -0,0 +1,286 @@
+require 'acts_as_geocodable/geocoding'
+require 'acts_as_geocodable/geocode'
+require 'acts_as_geocodable/remote_location'
+
+module CollectiveIdea #:nodoc:
+  module Acts #:nodoc:
+    module Geocodable #:nodoc:
+      
+      def self.included(mod)
+        mod.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        
+        # Make a model geocodable.
+        #
+        #  class Event < ActiveRecord::Base
+        #    acts_as_geocodable
+        #  end
+        #
+        # == Options
+        # * <tt>:address</tt>: A hash that maps geocodable attirbutes (<tt>:street</tt>,
+        #   <tt>:locality</tt>, <tt>:region</tt>, <tt>:postal_code</tt>, <tt>:country</tt>)
+        #   to your model's address fields, or a symbol to store the entire address in one field
+        # * <tt>:normalize_address</tt>: If set to true, you address fields will be updated
+        #   using the address fields returned by the geocoder. (Default is +false+)
+        # * <tt>:units</tt>: Default units-<tt>:miles</tt> or <tt>:kilometers</tt>-used for
+        #   distance calculations and queries. (Default is <tt>:miles</tt>)
+        #
+        def acts_as_geocodable(options = {})
+          options = {
+            :address => {
+              :street => :street, :locality => :locality, :region => :region,
+              :postal_code => :postal_code, :country => :country},
+            :normalize_address => false,
+            :distance_column => 'distance',
+            :units => :miles
+          }.merge(options)
+          
+          write_inheritable_attribute :acts_as_geocodable_options, options
+          class_inheritable_reader :acts_as_geocodable_options
+          
+          define_callbacks :after_geocoding
+          
+          has_one :geocoding, :as => :geocodable, :include => :geocode, :dependent => :destroy
+          
+          after_save :attach_geocode          
+          
+          include CollectiveIdea::Acts::Geocodable::InstanceMethods
+          extend CollectiveIdea::Acts::Geocodable::SingletonMethods
+        end
+        
+      end
+
+      module SingletonMethods
+        
+        # Extends ActiveRecord's find method to be geo-aware.
+        #
+        #   Model.find(:all, :within => 10, :origin => "Chicago, IL")
+        #
+        # Whenever find is called with an <tt>:origin</tt>, a +distance+ attribute
+        # indicating the distance to the origin is added to each of the results:
+        #
+        #   Model.find(:first, :origin => "Portland, OR").distance #=> 388.383
+        #
+        # +acts_as_geocodable+ adds 2 other retrieval approaches to ActiveRecord's default
+        # find by id, find <tt>:first</tt>, and find <tt>:all</tt>:
+        #
+        # * <tt>:nearest</tt>: find the nearest location to the given origin
+        # * <tt>:farthest</tt>: find the farthest location from the given origin
+        #
+        #   Model.find(:nearest, :origin => "Grand Rapids, MI")
+        #
+        # == Options
+        #
+        # * <tt>:origin</tt>: A Geocode, String, or geocodable model that specifies
+        #   the origin
+        # * <tt>:within</tt>: Limit to results within this radius of the origin
+        # * <tt>:beyond</tt>: Limit to results outside of this radius from the origin
+        # * <tt>:units</tt>: Units to use for <tt>:within</tt> or <tt>:beyond</tt>.
+        #   Default is <tt>:miles</tt> unless specified otherwise in the +acts_as_geocodable+
+        #   declaration.
+        #
+        def find(*args)
+          options = args.extract_options!
+          origin = location_to_geocode options.delete(:origin)
+          if origin
+            options[:units] ||= acts_as_geocodable_options[:units]
+            add_distance_to_select!(origin, options)
+            with_proximity!(args, options) do
+              geocode_conditions!(options, origin) do
+                join_geocodes { super *args.push(options) }
+              end
+            end
+          else
+            super *args.push(options)
+          end
+        end
+        
+        # Extends ActiveRecord's count method to be geo-aware.
+        #
+        #   Model.count(:within => 10, :origin => "Chicago, IL")
+        #
+        # == Options
+        #
+        # * <tt>:origin</tt>: A Geocode, String, or geocodable model that specifies
+        #   the origin
+        # * <tt>:within</tt>: Limit to results within this radius of the origin
+        # * <tt>:beyond</tt>: Limit to results outside of this radius from the origin
+        # * <tt>:units</tt>: Units to use for <tt>:within</tt> or <tt>:beyond</tt>.
+        #   Default is <tt>:miles</tt> unless specified otherwise in the +acts_as_geocodable+
+        #   declaration.
+        #
+        def count(*args)
+          options = args.extract_options!
+          origin = location_to_geocode options.delete(:origin)
+          if origin
+            options[:units] ||= acts_as_geocodable_options[:units]
+            with_proximity!(args, options) do
+              geocode_conditions!(options, origin) do
+                join_geocodes { super *args.push(options) }
+              end
+            end
+          else
+            super *args.push(options)
+          end
+        end
+  
+        # Convert the given location to a Geocode
+        def location_to_geocode(location)
+          case location
+          when Geocode then location
+          when InstanceMethods then location.geocode
+          when String, Fixnum then Geocode.find_or_create_by_query(location)
+          end
+        end
+        
+        def validates_as_geocodable(options = {})
+          options = options.reverse_merge :message => "Address could not be geocoded.", :allow_nil => false
+          validate do |geocodable|
+            if !(options[:allow_nil] && geocodable.to_location.attributes.all?(&:blank?)) &&
+                !Geocode.find_or_create_by_location(geocodable.to_location)
+              geocodable.errors.add_to_base options[:message]
+            end
+          end
+        end
+      
+      private
+      
+        def add_distance_to_select!(origin, options)
+          (options[:select] ||= "#{table_name}.*") <<
+            ", #{sql_for_distance(origin, options[:units])} AS
+            #{acts_as_geocodable_options[:distance_column]}"
+        end
+      
+        def with_proximity!(args, options)
+          if [:nearest, :farthest].include?(args.first)
+            raise ArgumentError, ":include cannot be specified with :nearest and :farthest" if options[:include]
+            direction = args.first == :nearest ? "ASC" : "DESC"
+            args[0] = :first
+            with_scope :find => { :order => "#{acts_as_geocodable_options[:distance_column]} #{direction}"} do
+              yield
+            end
+          else
+            yield
+          end
+        end
+        
+        def join_geocodes(&block)
+          with_scope :find => { :joins => "JOIN geocodings ON
+              #{table_name}.#{primary_key} = geocodings.geocodable_id AND
+                geocodings.geocodable_type = '#{class_name}'
+              JOIN geocodes ON geocodings.geocode_id = geocodes.id" } do
+            yield
+          end
+        end
+        
+        def geocode_conditions!(options, origin)
+          units = options.delete(:units)
+          conditions = []
+          conditions << "#{sql_for_distance(origin, units)} <= #{options.delete(:within)}" if options[:within]
+          conditions << "#{sql_for_distance(origin, units)} > #{options.delete(:beyond)}" if options[:beyond]
+          if conditions.empty?
+            yield
+          else
+            with_scope(:find => { :conditions => conditions.join(" AND ") }) { yield }
+          end
+        end
+        
+        def sql_for_distance(origin, units = acts_as_geocodable_options[:units])
+          Graticule::Distance::Spherical.to_sql(
+            :latitude => origin.latitude,
+            :longitude => origin.longitude,
+            :latitude_column => "geocodes.latitude",
+            :longitude_column => "geocodes.longitude",
+            :units => units
+          )
+        end
+        
+      end
+
+      module InstanceMethods
+        
+        # Get the geocode for this model
+        def geocode
+          geocoding.geocode if geocoding
+        end
+        
+        # Create a Graticule::Location
+        def to_location
+          returning Graticule::Location.new do |location|
+            [:street, :locality, :region, :postal_code, :country].each do |attr|
+              location.send "#{attr}=", geo_attribute(attr)
+            end
+          end
+        end
+        
+        # Get the distance to the given destination. The destination can be an
+        # acts_as_geocodable model, a Geocode, or a string
+        #
+        #   myhome.distance_to "Chicago, IL"
+        #   myhome.distance_to "49423"
+        #   myhome.distance_to other_model
+        #
+        # == Options
+        # * <tt>:units</tt>: <tt>:miles</tt> or <tt>:kilometers</tt>
+        # * <tt>:formula</tt>: The formula to use to calculate the distance. This can
+        #   be any formula supported by Graticule. The default is <tt>:haversine</tt>.
+        #  
+        def distance_to(destination, options = {})
+          units = options[:units] || acts_as_geocodable_options[:units]
+          formula = options[:formula] || :haversine
+          
+          geocode = self.class.location_to_geocode(destination)
+          self.geocode.distance_to(geocode, units, formula)
+        end
+        
+      protected
+        
+        # Perform the geocoding
+        def attach_geocode
+          new_geocode = Geocode.find_or_create_by_location self.to_location unless self.to_location.blank?
+          if new_geocode && self.geocode != new_geocode
+            self.geocoding = Geocoding.new :geocode => new_geocode
+            self.update_address self.acts_as_geocodable_options[:normalize_address]
+            callback :after_geocoding
+          elsif !new_geocode && self.geocoding
+            self.geocoding.destroy
+          end
+        rescue Graticule::Error => e
+          logger.warn e.message
+        end
+        
+        
+        def update_address(force = false)
+          unless self.geocode.blank?
+            if self.acts_as_geocodable_options[:address].is_a? Symbol
+              method = self.acts_as_geocodable_options[:address]
+              if self.respond_to?("#{method}=") && (self.send(method).blank? || force)
+                self.send "#{method}=", self.geocode.to_location.to_s
+              end
+            else
+              self.acts_as_geocodable_options[:address].each do |attribute,method|
+                if self.respond_to?("#{method}=") && (self.send(method).blank? || force)
+                  self.send "#{method}=", self.geocode.send(attribute)
+                end
+              end
+            end
+            
+            update_without_callbacks
+          end
+        end
+        
+        def geo_attribute(attr_key)
+          if self.acts_as_geocodable_options[:address].is_a? Symbol
+            attr_name = self.acts_as_geocodable_options[:address]
+            attr_key == :street ? self.send(attr_name) : nil
+          else
+            attr_name = self.acts_as_geocodable_options[:address][attr_key]
+            attr_name && self.respond_to?(attr_name) ? self.send(attr_name) : nil
+          end
+        end
+      end
+    end
+  end
+end