== drifter

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

=== Installation

gem install drifter require 'rubygems' require 'drifter'

if you're using rails:

gem install drifter gem 'drifter' # in Gemfile

=== Usage

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

=== License

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