Geocoder¶ ↑

Geocoder adds object geocoding and database-agnostic distance calculations to Ruby on Rails. It’s as simple as calling fetch_coordinates! on your objects, and then using a named scope like Venue.near("Billings, MT").

Geocoder 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¶ ↑

First, you must get a Google Maps API key (to get one go to code.google.com/apis/maps/signup.html) and store it in a constant:

# eg, in config/initializers/google_maps.rb
GOOGLE_MAPS_API_KEY = "..."

Add latitude and longitude columns to your model:

script/generate migration AddLatitudeAndLongitudeToModel \
  latitude:float longitude:float
rake db:migrate

Then tell your model about it:

geocoded_by :address                  # attribute/method to use for geocoding
after_validation :fetch_coordinates!  # fetch and assign coordinates before saving

You are not stuck with the latitude and longitude column names, or the address method. See “More On Configuration” below for details.

3. Use¶ ↑

Assuming Venue is a geocoded model, it has the following named scopes:

Venue.near('Omaha, NE, US', 20)    # venues within 20 miles of Omaha
Venue.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")

More On Configuration¶ ↑

You are not stuck with using the latitude and longitude database column names for storing coordinates. For example, to use lat and lon:

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

The string to use for geocoding can be anything you’d use to search Google Maps. For example, 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 you might do something like this:

geocoded_by :location

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

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

To-do List¶ ↑

• rake task for geocoding all non-geocoded objects

• install.rb should do some setup when installed as a plugin

• make fetch_coordinates assign coordinates; fetch_coordinates! should also save object

Copyright © 2009 Alex Reisner, released under the MIT license