drifter is a simple geocoding library with support for the Google Geocoder API and the Yahoo Placefinder API. It also supports IP address geocoding using the hostip.info API

gem install drifter
require 'rubygems'
require 'drifter'

# if you're using rails:
gem install drifter
gem 'drifter' # in Gemfile

Drifter.geocode() takes a string representing an address or location and returns an array of Drifter::Location objects

>> london = Drifter.geocode("London, UK").first
=> <#Drifter::Location>

Drifter::Location objects hold common address attributes like city, state, post_code country_code, lat and lng:

>> [london.country_code, london.lat, london.lng]
=> ['GB', 51.5001524, -0.1262362]

Reverse geocoding is also supported. Instead of passing a string to geocode(), you can pass a two item array or an object that responds to lat() and lng()

>> loc = Drifter.geocode( [53.4807125, -2.2343765] ).first
=> [loc.city, loc.state].join(', ')
=> "Manchester, England"

IP address gecoding is supported using the hostip.info api. Just pass the IP as the location parameter

>> loc = Drifter.geocode('1.2.3.4').first
=> <#Drifter::Location>

hostip.info only provides the city, country, lat and lng. If you need more info, you can reverse geocode the result:

>> loc = Drifter.geocode('1.2.3.4').first
>> loc = Drifter.geocode(loc).first
>> loc.state_code
=> 'CA'

Google is the default geocoding provider and works out of the box. Yahoo’s placefinder is also supported but you’ll need an api key (they call it an appid)

>> Drifter.default_geocoder = :yahoo
>> Drifter::Geocoders::Yahoo.api_key = 'my_key'

>> bh = Drifter.geocode("90210").first
=> <#Drifter::Location>

You can change the geocoder per request:

>> Drifter.geocode("springfield", :geocoder => :yahoo)
>> Drifter.geocode("springfield", :geocoder => :google)

Both Yahoo and Google return a lot more info than is held in Drifter::Location’s standard attributes. You can access the extra data using the data() method which returns a Hash

# using google as the provider:
>> london.data["geometry"]["location_type"]
=> "APPROXIMATE"

The key => value pairs in the data Hash are specific to each provider, so you’ll have to check their docs to see what’s available. You can also modify the query sent to the geocoder to customise the results. Any option other than :geocoder will be URL encoded and sent as a query string parameter e.g. Yahoo’s service returns a timezone if you pass a ‘flags’ parameter containing a ‘T’:

>> Drifter.default_geocoder = :yahoo
>> paris = Drifter.geocode("Paris", :flags => 'T').first
>> paris.data["timezone"]
=> "Europe/paris"

Drifter.geocode() always returns an array if the request was processed successfully by the geocoding service. An empty array indicates that the service returned no results.

If the geocoding service returns an error, Drifter.geocode() returns nil and Drifter.last_error() returns a hash with the error :code and :message

MIT License. Copyright 2011 Ahmed Adam (github.com/ahmedrb)