README.rdoc

= Geocoder

Geocoder is a plugin for Rails that provides database-agnostic object geocoding (via Google) and some utilities for working with geocoded objects. It does not rely on proprietary database functions so reasonably accurate distances can be calculated in MySQL or even SQLite.

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


== Features

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_and_assign_coordinates      # writes coordinates to object

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

  obj.nearbys(30)                       # other objects within radius
  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