Original author(s) Written in Ruby | Development status Active Operating system | |
Initial release 8 February 2006; 11 years ago (2006-02-08) Stable release 1.3.0 / 30 January 2016; 13 months ago (2016-01-30) | ||
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.
Contents
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 geocoderOr, if you're using Bundler for Rails, you may add this to your Gemfile:
gem 'geocoder'and run at the command prompt:
bundle installIt can be used as a plugin with rails too:
Configuration
In order to use Geocoder with objects, the project must be set up as follows:
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:
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.
Forward and Reverse Geocoding on the same model is possible.
geocoded_by :address reverse_geocoded_by :latitude, :longitude after_validation :geocode, :reverse_geocodeIn order to use different names for latitude and longitude in the model, the following change may be done when implementing geocoded_by:
Additionally, the address method may return any string that would be used to search Google Maps. Any of the following examples will work:
Services
By default, Geocoder makes use of Google's geocoding API to retrieve addresses and coordinates. Currently, these address geocoding services are supported:
:google:yahoo: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.