easy to use • supports Ruby 2.x and JRuby • compatible with ActiveRecord, Mongoid, MongoMapper • result caching • proxy support • multi-lingual • Nominatim, Google, Bing, Yandex, MaxMind, and more • works with Rails, Sinatra, any Rack framework • command line interface
gem install geocoder
"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 |
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
(Mongoid and MongoMapper are very similar; please see README for details.)
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
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
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 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? }
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
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
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).
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
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")
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
Map: https://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
.