Geocoder (Ruby)

Geocoder (Ruby)

Geocoder is a geocoding library for Ruby. 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.

Compatability

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

Geocoder is also compatible with Rails 3. However, it there is limited functionality with Rails 2.

Installation

Geocoder gem can be installed with the following command:

gem install geocoder

Or, if you're using Rails/Bundler, 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 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, 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 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 coorindates

reverse_geocoded_by: :lat, :lon

after_validation: reverse_geocode     #auto-fetch address

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 retreive addresses and coordinates. However any of the following street address geocoding services are currently 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

Other Uses

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.