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.
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
A) Get a Google Maps API key (see code.google.com/apis/maps/signup.html) and store it in a constant:
# eg, in config/initializers/google_maps.rb GOOGLE_MAPS_API_KEY = "..."
B) Add latitude
and longitude
columns to your model:
script/generate migration AddLatitudeAndLongitudeToYourModel latitude:float longitude:float rake db:migrate
C) Tell geocoder where your model stores its address:
geocoded_by :address
D) Optionally, auto-fetch coordinates every time your model is saved:
after_validation :fetch_coordinates
Note that you are not stuck with the latitude
and longitude
column names, or the address
method. See “More On Configuration” below for details.
Assuming obj
is an instance of a geocoded class, you can get its coordinates:
obj.fetch_coordinates # fetches and assigns coordinates obj.fetch_coordinates! # also saves lat, lon attributes
If you have a lot of objects you can use this Rake task to geocode them all:
rake geocode:all CLASS=YourModel
Once obj
is geocoded you can do things like this:
obj.nearbys(30) # other objects within 30 miles obj.distance_to(40.714, -100.234) # distance to arbitrary point
To find objects by location, use 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
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")
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).
-
install.rb
should do some setup when installed as a plugin
Copyright © 2009 Alex Reisner, released under the MIT license