Hi, I'm Andre Lewis and I'm on the Internet

Following up on our recent release of GeoKit, Bill and I are working on some posts highlighting some of GeoKit's cool features. This post is on distance calculations. GeoKit can calculate distance in memory, and it can calculate distance as part of a database query.

In-memory distance calculation

The basic syntax for in-memory distance calculations is: d = first_loc.distance_to(second_loc)

What class is first_loc and second_loc? They should be either LatLng (Geokit::LatLng), or GeoLoc. If you open up the mappable.rb file, you're see that GeoLoc inherits from LatLng. If you're looking for the distance_to method, you'll find it in the Mappable module (the code for which is also in mappable.rb). The Mappable module is mixed in to LatLng, and imbues it with the distance_to method.

Distance in miles and kilometers

By default, distance_to yields a result in miles. If you want a distance in kilometers instead, just pass the optional units argument:

>>d = first_loc.distance_to(second_loc, :units=>:kilos)

A full example

>ruby script/console
Loading development environment.
>> include GeoKit
>> first_loc=LatLng.new(37.775,-122.418)
>> second_loc=LatLng.new(32.813,-96.948)
>> first_loc.distance_to(second_loc)
=> 1473.29189341352

. . . and with geocoding

Here we are starting with just the addresses, geocoding them through Google's geocoding service, and then calculating the distance. Calls to any of the Geocoders in GeoKit return the GeoLoc object. Recall that GeoLoc inherits from LatLng though, so it has all of LatLngs methods, including distance_to.

>>ruby script/console Loading development environment. 
>> include GeoKit::Geocoders 
>> sf=GoogleGeocoder.geocode('San Francisco,CA') 
>> puts sf.ll 
37.775,-122.418333 
>> irving=GoogleGeocoder.geocode('Irving,TX') 
>> puts irving.ll 
32.813889,-96.948611 
>> sf.distance_to(irving) 
=> 1473.25508451219 
>> sf.distance_to(irving, :units=>:kilometers)
=> 2370.46743098012

Flat vs. Spherical distances

If it turns out the earth is actually flat, GeoLoc still has us covered:

sf.distance_to(irving, :formula=>:flat)
=> 1206.13692230874

In case you're wondering, the spherical formula uses the Haversine method, and flat formula just uses the pythagorian therorum. You can find both implementations in the Mappable module in mappable.rb.

So there you have in-memory distance calculations provided by Geokit. Next, let's look at distance calculations in your database through ActiveRecord finder extensions provided by ActsAsMappable.

Database Distance Calculations

I have a model named Shop, which mixes in the ActsAsMappable module:

class Shop < ActiveRecord::Base 
acts_as_mappable 
... end 

>> loc=GoogleGeocoder.geocode('94117')
>> puts loc.full_address
"San Francisco, CA 94117, USA"
>> shops=Shop.find :all, :origin=>loc, :order=>'distance asc', :limit=>10

Now, each of the shops that has a bonus attribute, 'distance'. This represents the distance from the origin provided in the query.

>> puts shops[0].distance
0.22292201411219
>> puts shops[9].distance
0.61426029124168
>> shops.each {|shop| puts "#{shop.name} -- #{shop.distance} miles from #{loc.full_address}"}
Coffee to the People -- 0.22292201411219 miles from San Francisco, CA 94117, USA
Central Coffee, Tea & Spice -- 0.24258501247455 miles from San Francisco, CA 94117, USA
Bean Bag Cafe -- 0.33106086315379 miles from San Francisco, CA 94117, USA
Cafe Abir -- 0.42131954288221 miles from San Francisco, CA 94117, USA
Cole Valley Cafe -- 0.53454381452665 miles from San Francisco, CA 94117, USA
Jumping Java -- 0.5419605766772 miles from San Francisco, CA 94117, USA
Cafe Reverie -- 0.59076205971555 miles from San Francisco, CA 94117, USA
Cafe Du Soleil -- 0.60029433169774 miles from San Francisco, CA 94117, USA
Tully's (Cole Valley) -- 0.61426029124168 miles from San Francisco, CA 94117, USA

Since distance is being calculated in the database, you can use it in the conditions like any other column:

>> shops=Shop.find :all, :origin=>loc, :order=>'distance asc', 
                         :conditions=>'distance>20 AND distance <25'

Database and memory distance calculations together

Since my Shop class mixes in the Mappable module (through the acts_as_mappable call), I can also calculate its distance from any arbitrary location:

shops=Shop.find :all, :origin=>loc, :order=>'distance asc',
                         :conditions=>'distance>20 AND distance <25'
>> other_loc=GoogleGeocoder.geocode('100 Spear St, San Francisco, CA')
>> puts shops[0].distance_to(other_loc) # distance to an arbitrary location
=> 19.6377479942219
>> puts shops[0].distance # distance to the origin given in the query
22.581680094216

In case you're wondering, the math happening behind the scenes is essentially the same as outlined in sorting your queries by geographic distance -- they math is now nicely hidden, thanks to Bill Eisenhaurer's work in abstracting it away.

Summary

GeoKit supports both in-memory and in-database distance calculations. You can use units of miles or kilometers, and a flat or spherical formula.

Coming up next, I’m going to talk more about the find’s :origin argument.

Bill is also putting up some more GeoKit documentation and examples -- check out his live example of IP-based geocoding. It’s very cool stuff which allows you to determine roughly where your visitors are based on their IP address. GeoKit makes it easy for any Rails controller to employ the functionality.