Geocoder (Ruby)

Geocoder

Original author(s)	Alex Reisner
Initial release	8 February 2006 (2006-02-08)
Stable release	1.3.0 / 30 January 2016 (2016-01-30)
Written in	Ruby
Operating system	Linux, OS X, Windows
Type	Ruby Library
License	MIT License
Website	http://www.rubygeocoder.com/

Geocoder (Ruby) is a geocoding library for Ruby. Geocoding helps to enhance webpages by presenting location relevant information to the user. When used with Rails, Geocoder adds geocoding functionality such as finding coordinates with street addresses or vice versa in addition to distance calculations for ActiveRecord objects. Since the functionality does not rely on proprietary database functions, finding different geocoded objects in an area works out-of-the-box for databases like MySQL, PostgreSQL and SQLite.

Compatibility

Geocoder has been fully tested with Ruby 1.8.7, 1.9.2, and JRuby 1.5.3.

Geocoder is compatible with Rails 3, but there is only limited functionality with Rails 2.

Installation

The Prerequisites to installing Geocoder are Ruby and RubyGems.

Geocoder gem can be installed with the following command:

gem install geocoder

Or, if you're using Bundler for Rails, you may add this to your Gemfile:

gem 'geocoder'

and run at the command prompt:

bundle install

It can be used as a plugin with rails too:

rails plugin install git://github.com/alexreisner/geocoder.git

Configuration

In order to use Geocoder with objects, the project must be set up as follows:

Required attributes

ActiveRecord

In order to use Geocoding with ActiveRecord objects, they must have two additional attributes, latitude and longitude coordinates. When stored in the table they should be called latitude and longitude but they may be changed as explained below. When using reverse geocoding (translating a user's location coordinates into a physical address), the model must implement a method that returns an address. The address may be a single attribute; however, it can also be a method which returns a string assembled from different attributes such as city, state, and country.

Mongoid

When using Mongoid, the model only needs to add the address, latitude and longitudes as fields. The model must also include Geocoder::Model::Mongoid before making any calls to the geocoded_by: method.

Model behavior

In the rails model, Geocoder must be told which method returns the object's full address:

geocoded_by :full_street_address     # can also be an IP address
 
after_validation :geocode       # auto-fetch coordinates

For reverse geocoding, Geocoder must know which method returns latitude and longitude coordinates. If :address option is not provided, it fetches the address automatically in the address attribute. Else, it fetches the address into the location attribute like the example given below.

reverse_geocoded_by :latitude, :longitude, 
  :address => :location
 
after_validation: reverse_geocode     # auto-fetch address

Forward and Reverse Geocoding on the same model is possible.

geocoded_by :address
reverse_geocoded_by :latitude, :longitude
after_validation :geocode, :reverse_geocode

In order to use different names for latitude and longitude in the model, the following change may be done when implementing geocoded_by:

geocoded_by :address, :latitude => :lat, :longitude => :lon

Additionally, the address method may return any string that would be used to search Google Maps. Any of the following examples will work:

• "123 Sample St, New York, NY"
• "Eiffel Tower, Paris, FR"
• "Raleigh, NC, US"

Services

By default, Geocoder makes use of Google's geocoding API to retrieve addresses and coordinates. Currently, these address geocoding services are supported:

• Google: :google
• Yahoo: :yahoo
• Geocoder.ca: :geocoder_ca (US & Canada only)

Examples

Here are some examples to demonstrate Geocoder functionality:

Hotel.near("Raleigh, North Carolina")

Finds hotels near Raleigh.

@restaurant.distance_to("Empire State Building")

Finds the distance from @restaurant to the Empire State Building.

Applications

• Developers may also use Geocoder to convert a user's IP Address to their city location. By making such a conversion you may be able to offer user's content relevant to their current location without requiring to ask for it beforehand.
• It may be used for geo-spatial analysis in order to recognize patterns within the information. This is very useful in data mining applications.
• Web based GIS tools such as Google Maps, Yahoo Maps etc. include geocoding functionality.