Ruby Geocoder

Complete Ruby geocoding solution.

easy to use • supports Ruby 1.8 - 2.1, JRuby, Rubinius • compatible with ActiveRecord, Mongoid, MongoMapper • result caching • proxy support • multi-lingual • Google, Yahoo, Bing, Nominatim, Yandex.ru, FreeGeoIP, MaxMind, and more • works with Rails, Sinatra, any Rack framework • command line interface

Tutorial video
Railscast #273
Install
gem install geocoder
Source code
github.com
API docs
rdoc.info
Contribute
github issues

Look up street addresses, IP addresses,
and geographic coordinates

"Eiffel Tower"
place name or address
48.8582, 2.2945
latitude, longitude
44.9817, -93.2783
latitude, longitude
350 7th St N, Minneapolis, MN
street address
24.193.83.1
IP address
Brooklyn, NY, US
street address

Perform geographic queries using objects

Hotel.near(”Vancouver, Canada”)
find hotels near Vancouver

@event.nearbys
find other events near @event

@restaurant.distance_to(”Eiffel Tower”)
find distance from @restaurant to Eiffel Tower

@restaurant.bearing_to(”Eiffel Tower”)
find direction from @restaurant to Eiffel Tower

Geocoder::Calculations.geographic_center([
  @brooklyn_bridge,
  @chrysler_building,
  @madison_square_garden])

find geographic center of multiple places

ActiveRecord Examples

(Mongoid and MongoMapper are very similar; please see README for details.)

Simple Geocoding by Street Address

Given a Venue model with known street address, automatically fetch coordinates after validation and store in latitude and longitude attributes:

# app/models/venue.rb
geocoded_by :address
after_validation :geocode

Simple Geocoding by IP Address

Given a User model with known IP address, automatically fetch coordinates and store in lat and lon attributes:

# app/models/user.rb
geocoded_by :ip_address,
  :latitude => :lat, :longitude => :lon
after_validation :geocode

Simple Reverse Geocoding by Coordinates

Given a Place model with known latitude/longitude coordinates, automatically fetch address and store in location attribute (stored in address attribute if :address option omitted):

# app/models/place.rb
reverse_geocoded_by :latitude, :longitude,
  :address => :location
after_validation :reverse_geocode

Only Geocode When Attributes Have Changed

Only look up coordinates if address changed since last save:

# app/models/venue.rb
geocoded_by :address
after_validation :geocode,
  :if => lambda{ |obj| obj.address_changed? }

Custom Handling of Detailed Reverse Geocoding Results

Given a Place model with known latitude/longitude coordinates, automatically fetch address components and store in separate attributes:

# app/models/place.rb
reverse_geocoded_by :lat, :lon do |obj,results|
  if geo = results.first
    obj.city    = geo.city
    obj.zipcode = geo.postal_code
    obj.country = geo.country_code
  end
end
after_validation :reverse_geocode

Forward and Reverse Geocoding on Same Model

Given a Place model, objects of which sometimes have a street address and sometimes have coordinates, automatically fetch and fill in whatever's missing, based on what's provided:

# app/models/place.rb
geocoded_by :address
reverse_geocoded_by :latitude, :longitude
after_validation :geocode, :reverse_geocode

Find the Bearing (Direction) Between Places

Given a Place model with geocoded objects, find the distance and direction of the closest ones:

nearbys = Place.near("Omaha, NE", 50,
  :order => "distance")
bearing = nearbys.first.bearing # => 46.12
Geocoder::Calculations.compass_point(
  bearing) # => "NE"

The bearing attribute is a number between 0 and 360 indicating the number of degrees clockwise from due North (eg: 180 = South, 270 = West).

In Any Rack-Based Framework

Detect Location of HTTP Request

Get current user's city and country (using IP address). A location method is added to the standard Rack::Request which returns a Geocoder::Result object:

# Rails controller or Sinatra app
city = request.location.city
country = request.location.country_code

Outside of Any Framework

Search Geocoding API

Search for geographic information about a street address, IP address, or set of coordinates (Geocoder.search returns an array of Geocoder::Result objects):

Geocoder.search("1 Twins Way, Minneapolis")
Geocoder.search("44.981667,-93.27833")
Geocoder.search("204.57.220.1")

Command Line Interface

Search Geocoding API

The command line interface works just like the Geocoder.search method and allows you to set various configuration options like geocoding service, language, etc. You can also get the raw JSON response (or URL) from the geocoding API:

$ geocode -s geocoder_ca "44.981667,-93.27833"
Latitude:        44.981165
Longitude:       -93.279225
Full address:    380 7th St N, Minneapolis, ...
City:            Minneapolis
State/province:  MN
Postal code:     55403
Country:         United States
Google map:      http://maps.google.com/maps?...

$ geocode --json "1 Twins Way, Minneapolis"
{
  "status": "OK",
  "results": [ {
    "types": [ "street_address" ],
    "formatted_address": "536 1/2 N 3rd St...",
    ...
  } ]
}

For details see geocode -h.

Geocoder gem and this web site by Alex Reisner.

blog code personal business