= acts_as_geocodable acts_as_geocodable helps you 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. Beginning with version 2, we require Rails 3. Use one of the 1.0.x tags to work with Rails 2.3. Also, we've adopted the ARel style syntax for finding 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.origin("97232", :within => 50) Event.origin("Portland, OR").nearest == Installation Install as a gem gem install acts_as_geocodable Graticule[link:http://rubyforge.org/projects/graticule] is used for all the heavy lifting and will be installed too. == 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. Also, 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 == Configuration Create the required tables rails generate acts_as_geocodable 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.origin(remote_location).nearest if remote_location @stores = Store.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 * configurable formulas