README.rdoc

= Geocoder

Geocoder is a simple plugin for Rails that provides object geocoding (via Google Maps) and some utilities for working with geocoded objects. The code can be used as a standalone method provider or included in a class to give objects geographic awareness.

== Setup

Use the Rails plugin install script:

  script/plugin install git://github.com/alexreisner/geocoder.git

To add geocoding features to a class:

  geocoded_by :location

Be sure your class defines read/write attributes +latitude+ and +longitude+ as well as a method called +location+ (or whatever name you pass to +geocoded_by+) that returns a string suitable for passing to a Google Maps search, for example:

  714 Green St, Big Town, MO

If your model has +address+, +city+, +state+, and +country+ attributes your +location+ method might look something like this:

  def location
    [address, city, state, country].compact.join(', ')
  end


== Examples

Look up coordinates of an object:

  obj.fetch_coordinates            # returns an array [lat, lon]
  obj.fetch_and_assign_coordinates # writes values to +latitude+ and +longitude+

Find distance between object and a point:

  obj.distance_to(40.71432, -100.23487)      # in miles
  obj.distance_to(40.71432, -100.23487, :km) # in kilometers

Find objects within 20 miles of a point:

  Venue.find_near('Omaha, NE, US', 20)  # Venue is a geocoded model

Please see the code for more methods and detailed information about arguments.

  
Copyright (c) 2009 Alex Reisner, released under the MIT license