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

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

A geocodable string is basically 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.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 values 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