= 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.

== 1. Install

Install either as a plugin:

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

or as a gem:

  # add to config/environment.rb:
  config.gem "rails-geocoder", :lib => "geocoder", :source => "http://gemcutter.org/"
  
  # at command prompt:
  sudo rake gems:install

== 2. Configure

To add geocoding features to a class:

  geocoded_by :location

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:

  geocoded_by :address, :latitude  => :lat, :longitude => :lon

A geocodable string is anything you'd use to search Google Maps. 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 your +location+ method might look something like this:

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

== 3. Use

Assuming +Venue+ is a geocoded model:

  Venue.find_near('Omaha, NE, US', 20)  # venues within 20 miles of Omaha
  Venue.find_near([40.71, 100.23], 20)  # venues within 20 miles of a point
  Venue.geocoded                        # venues with coordinates
  Venue.not_geocoded                    # venues without coordinates

Assuming +obj+ has a valid string for its +location+:

  obj.fetch_coordinates                 # returns coordinates [lat, lon]
  obj.fetch_coordinates!                # also writes coordinates to object

Assuming +obj+ is geocoded (has latitude and longitude):

  obj.nearbys(30)                       # other objects within 30 miles
  obj.distance_to(40.714, -100.234)     # distance to arbitrary point

Some utility methods are also available:

  # distance (in miles) between Eiffel Tower and Empire State Building
  Geocoder.distance_between( 48.858205,2.294359,  40.748433,-73.985655 )
  
  # look up coordinates of some location (like searching Google Maps)
  Geocoder.fetch_coordinates("25 Main St, Cooperstown, NY")


Please see the code for more methods and detailed information about arguments (eg, working with kilometers).

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