In the opening installment of this series, you learned how to integrate Google Maps into your Rails applications by using the powerful YM4R/GM plugin. YM4R/GM makes it trivial to add maps and map features such as icons and information windows, but requires you to first derive the latitudinal and longitudinal coordinates of the desired locations. But what if you don't know these coordinates? Enter the GeoKit plugin.
In this tutorial, I'll introduce you to GeoKit, showing you not only how to retrieve coordinates using GeoKit, but also to take advantage of several other fascinating GeoKit features to perform tasks such as calculating the distance between two points, finding all points within a specified radius, and identifying user locations simply by ascertaining their IP address.
Introducing the GeoKit Plugin
Created by Bill Eisenhauer and Andre Lewis, GeoKit makes the process of determining the latitudinal and longitudinal coordinates of addresses (known as geocoding) a snap, not to mention performing a variety of complex distance calculations that would otherwise leave you searching for those old college geometry textbooks. But first, you need to install GeoKit. To do so, execute the following command from your project directory:
%>ruby script/plugin install svn://rubyforge.org/var/svn/
geokit/trunk
Once installed, you need to open your project's environment.rb file and assign your Google Maps API key to the GeoKit::Geocoders::google directive. That's it! You're ready to begin using GeoKit. Finally, place the following line at the top of any controller where you'd like to use GeoKit's geocoder:
include GeoKit::Geocoders
If you're only interested in the distance calculation features, insert the following line:
include GeoKit::Mappable
Geocoding a Street Address
It makes sense to begin with GeoKit's most obvious feature: geocoding. Geocoding an address is surprisingly simple; just pass an address into the GoogleGeocoder.geocode method. GoogleGeocoder.geocode returns a GeoLoc object containing lat and lng attributes (representing latitude and longitude, respectively). From here, you're free to use these coordinates within Ym4r to build the map (Ym4r was introduced in this series' previous installment).
The following controller method demonstrates how to use GoogleGeocoder.geocode to retrieve the coordinates for the Columbus Museum of Art, in addition to preparing a Google Map for rendering in the view that follows:
def map
coordinates = GoogleGeocoder.geocode("480 E Broad St,
Columbus, Ohio 43215")
@map = GMap.new("map")
@map.center_zoom_init([coordinates.lat, coordinates.lng], 14)
end
Executing this action produces the map shown in Figure 1.
Figure 1: Centering the Map on the Columbus Art Museum's Location
Automatically Geocoding Model Addresses
Chances are you're going to want to repeatedly refer to the coordinates of addresses stored in a model. For instance, suppose you were building the world's largest pizzeria directory, and wanted to map the pizzeria locations. Continuously geocoding the pizzeria addresses doesn't make sense, so you'll probably want to modify your pizzeria model to include two additional attributes, lat and lng. Understanding the importance of such a feature, GeoKit's creators added the ability to automatically geocode addresses at the time they're added to the database through acts_as_mappable:
class Pizzeria << ActiveRecord::Base
acts_as_mappable :auto_geocode=>{:field=>:street_address}
end
This has the effect of examining the street_address attribute at creation time, geocoding the address, and saving the coordinates to the model's lat and lng attributes.
Calculating the Distance Between Two Points
Although GeoKit's geocoding features are great, its ability to perform complex distance-finding calculations is particularly fascinating. For instance, suppose you were considering having a drink at the swanky Mitchell's Steakhouse in downtown Columbus, and then walking over to the Columbus Art Museum for a stroll through the galleries. You don't want to walk too far, and so have decided to write a little script to determine the distance. Using GeoKit's Location.distance_between method, this is easily accomplished. Begin with the controller action:
IE 7
Firefox 2.0
