README.rdoc



Geocoder¶ ↑


Geocoder is a complete geocoding solution for Ruby. With Rails it adds geocoding (by street or IP address), reverse geocoding (find street address based on given coordinates), and distance queries. It’s as simple as calling geocode on your objects, and then using a scope like Venue.near("Billings, MT").

Compatibility¶ ↑


Supports multiple Ruby versions: Ruby 1.8.7, 1.9.2, and JRuby.


Supports multiple databases: MySQL, PostgreSQL, SQLite, and MongoDB (1.7.0 and higher).


Supports Rails 3. If you need to use it with Rails 2 please see the rails2 branch (no longer maintained, limited feature set).


Works very well outside of Rails, you just need to install either the json (for MRI) or json_pure (for JRuby) gem.


Install¶ ↑


As a Gem¶ ↑


Add to your Gemfile:

gem "geocoder"


and run at the command prompt:

bundle install


Or As a Plugin¶ ↑


At the command prompt:

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

Configure Object Geocoding¶ ↑


In the below, note that addresses may be street or IP addresses.

ActiveRecord¶ ↑


Your model must have two attributes (database columns) for storing latitude and longitude coordinates. By default they should be called latitude and longitude but this can be changed (see “More on Configuration” below):

rails generate migration AddLatitudeAndLongitudeToModel latitude:float longitude:float
rake db:migrate

For reverse geocoding your model must provide a method that returns an address. This can be a single attribute, but it can also be a method that returns a string assembled from different attributes (eg: city, state, and country).

Next, your model must tell Geocoder which method returns your object’s geocodable address:

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


For reverse geocoding, tell Geocoder which attributes store latitude and longitude:

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


Mongoid¶ ↑


First, your model must have an array field for storing coordinates:

field :coordinates, :type => Array


You may also want an address field, like this:

field :address


but if you store address components (city, state, country, etc) in separate fields you can instead define a method called address that combines them into a single string which will be used to query the geocoding service.

Once your fields are defined, include the Geocoder::Model::Mongoid module and then call geocoded_by:

include Geocoder::Model::Mongoid
geocoded_by :address               # can also be an IP address
after_validation :geocode          # auto-fetch coordinates


Reverse geocoding is similar:

include Geocoder::Model::Mongoid
reverse_geocoded_by :coordinates
after_validation :reverse_geocode  # auto-fetch address


Be sure to read Latitude/Longitude Order in the Notes on MongoDB section below on how to properly retrieve latitude/longitude coordinates from your objects.

MongoMapper¶ ↑


MongoMapper is very similar to Mongoid, just be sure to include Geocoder::Model::MongoMapper.

Mongo Indices¶ ↑


By default, the methods geocoded_by and reverse_geocoded_by create a geospatial index. You can avoid index creation with the :skip_index option, for example:

include Geocoder::Model::Mongoid
geocoded_by :address, :skip_index => true


Bulk Geocoding¶ ↑


If you have just added geocoding to an existing application with a lot of objects you can use this Rake task to geocode them all:

rake geocode:all CLASS=YourModel

Geocoder will print warnings if you exceed the rate limit for your geocoding service.

Request Geocoding by IP Address¶ ↑


Geocoder adds a location method to the standard Rack::Request object so you can easily look up the location of any HTTP request by IP address. For example, in a Rails controller or a Sinatra app:

# returns Geocoder::Result object
result = request.location


See “Advanced Geocoding” below for more information about Geocoder::Result objects.

Location-Aware Database Queries¶ ↑


To find objects by location, use the following scopes:

Venue.near('Omaha, NE, US', 20)    # venues within 20 miles of Omaha
Venue.near([40.71, 100.23], 20)    # venues within 20 miles of a point
Venue.geocoded                     # venues with coordinates
Venue.not_geocoded                 # venues without coordinates


With geocoded objects you can do things like this:

obj.nearbys(30)                      # other objects within 30 miles
obj.distance_from([40.714,-100.234]) # distance from arbitrary point to object
obj.bearing_to("Paris, France")      # direction from object to arbitrary point


Some utility methods are also available:

# look up coordinates of some location (like searching Google Maps)
Geocoder.coordinates("25 Main St, Cooperstown, NY")
 => [42.700149, -74.922767]

# distance (in miles) between Eiffel Tower and Empire State Building
Geocoder::Calculations.distance_between([47.858205,2.294359], [40.748433,-73.985655])
 => 3619.77359999382

# find the geographic center (aka center of gravity) of objects or points
Geocoder::Calculations.geographic_center([city1, city2, [40.22,-73.99], city4])
 => [35.14968, -90.048929]

Please see the code for more methods and detailed information about arguments (eg, working with kilometers).

Distance and Bearing¶ ↑


When you run a location-aware query the returned objects have two attributes added to them (only w/ ActiveRecord):


obj.distance - number of miles from the search point to this object


obj.bearing - direction from the search point to this object


Results are automatically sorted by distance from the search point, closest to farthest. Bearing is given as a number of clockwise degrees from due north, for example:


0 - due north


180 - due south


90 - due east


270 - due west


230.1 - southwest


359.9 - almost due north


You can convert these numbers to compass point names by using the utility method provided:

Geocoder::Calculations.compass_point(355) # => "N"
Geocoder::Calculations.compass_point(45)  # => "NE"
Geocoder::Calculations.compass_point(208) # => "SW"


Note: when using SQLite distance and bearing values are provided for interface consistency only. They are not very accurate.

To calculate accurate distance and bearing with SQLite or MongoDB:

obj.distance_to([43.9,-98.6])  # distance from obj to point
obj.bearing_to([43.9,-98.6])   # bearing from obj to point
obj.bearing_from(obj2)         # bearing from obj2 to obj


The bearing_from/to methods take a single argument which can be: a [lat,lon] array, a geocoded object, or a geocodable address (string). The distance_from/to methods also take a units argument (:mi or :km).

More on Configuration¶ ↑


You are not stuck with using the latitude and longitude database column names (with ActiveRecord) or the coordinates array (Mongo) for storing coordinates. For example:

geocoded_by :address, :latitude  => :lat, :longitude => :lon # ActiveRecord
geocoded_by :address, :coordinates => :coords                # MongoDB


The address method can return any string you’d use to search Google Maps. For example, any of the following are acceptable:


“714 Green St, Big Town, MO”


“Eiffel Tower, Paris, FR”


“Paris, TX, US”


If your model has street, city, state, and country attributes you might do something like this:

geocoded_by :address

def address
  [street, city, state, country].compact.join(', ')
end


For reverse geocoding you can also specify an alternate name attribute where the address will be stored, for example:

reverse_geocoded_by :latitude, :longitude, :address => :location  # ActiveRecord
reverse_geocoded_by :coordinates, :address => :loc                # MongoDB


Advanced Geocoding¶ ↑


So far we have looked at shortcuts for assigning geocoding results to object attributes. However, if you need to do something fancy you can skip the auto-assignment by providing a block (takes the object to be geocoded and an array of Geocoder::Result objects) in which you handle the parsed geocoding result any way you like, for example:

reverse_geocoded_by :latitude, :longitude 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


Every Geocoder::Result object, result, provides the following data:


result.latitude - float


result.longitude - float


result.coordinates - array of the above two


result.address - string


result.city - string


result.state - string


result.state_code - string


result.postal_code - string


result.country - string


result.country_code - string


If you’re familiar with the results returned by the geocoding service you’re using you can access even more data, but you’ll need to be familiar with the particular Geocoder::Result object you’re using and the structure of your geocoding service’s responses. (See below for links to geocoding service documentation.)

Geocoding Services¶ ↑


By default Geocoder uses Google’s geocoding API to fetch coordinates and street addresses (FreeGeoIP is used for IP address info). However there are several other APIs supported, as well as a variety of settings. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). Some common configuration options are:

# config/initializers/geocoder.rb
Geocoder.configure do |config|

  # geocoding service (see below for supported options):
  config.lookup = :yahoo

  # to use an API key:
  config.api_key = "..."

  # geocoding service request timeout, in seconds (default 3):
  config.timeout = 5

  # set default units to kilometers:
  config.units = :km

  # caching (see below for details):
  config.cache = Redis.new
  config.cache_prefix = "..."

end


Please see lib/geocoder/configuration.rb for a complete list of configuration options.

Listing and Comparison¶ ↑


The following is a comparison of the supported geocoding APIs. The “Limitations” listed for each are a very brief and incomplete summary of some special limitations beyond basic data source attribution. Please read the official Terms of Service for a service before using it.

Google (:google)¶ ↑


API key


optional (required for Premier)

Key signup


code.google.com/apis/maps/signup.html

Quota


2,500 requests/day, 100,000 with Google Maps API Premier

Region


world

SSL support


yes

Languages


ar, eu, bg, bn, ca, cs, da, de, el, en, en-AU, en-GB, es, eu, fa, fi, fil, fr, gl, gu, hi, hr, hu, id, it, iw, ja, kn, ko, lt, lv, ml, mr, nl, no, pl, pt, pt-BR, pt-PT, ro, ru, sk, sl, sr, sv, tl, ta, te, th, tr, uk, vi, zh-CN, zh-TW (see spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1)

Documentation


code.google.com/apis/maps/documentation/geocoding/#JSON

Terms of Service


code.google.com/apis/maps/terms.html#section_10_12

Limitations


“You must not use or display the Content without a corresponding Google map, unless you are explicitly permitted to do so in the Maps APIs Documentation, or through written permission from Google.” “You must not pre-fetch, cache, or store any Content, except that you may store: (i) limited amounts of Content for the purpose of improving the performance of your Maps API Implementation…”

Notes


To use Google Premier set Geocoder::Configuration.lookup = :google_premier and Geocoder::Configuration.api_key = [key, client, channel].


Yahoo (:yahoo)¶ ↑


API key


optional in development (required for production apps)

Key signup


developer.apps.yahoo.com/wsregapp

Quota


50,000 requests/day, more available by special arrangement

Region


world

SSL support


no

Languages


?

Documentation


developer.yahoo.com/geo/placefinder/guide/responses.html

Terms of Service


info.yahoo.com/legal/us/yahoo/maps/mapsapi/mapsapi-2141.html

Limitations


“YOU SHALL NOT… (viii) store or allow end users to store map imagery, map data or geocoded location information from the Yahoo! Maps APIs for any future use; (ix) use the stand-alone geocoder for any use other than displaying Yahoo! Maps or displaying points on Yahoo! Maps;”


Bing (:bing)¶ ↑


API key


required

Key signup


www.bingmapsportal.com

Quota


50,000 requests/24 hrs

Region


world

SSL support


no

Languages


?

Documentation


msdn.microsoft.com/en-us/library/ff701715.aspx

Terms of Service


www.microsoft.com/maps/product/terms.html

Limitations


No country codes or state names. Must be used on “public-facing, non-password protected web sites,” “in conjunction with Bing Maps or an application that integrates Bing Maps.”


Nominatim (:nominatim)¶ ↑


API key


none

Quota


1 request/second

Region


world

SSL support


no

Languages


?

Documentation


wiki.openstreetmap.org/wiki/Nominatim

Terms of Service


wiki.openstreetmap.org/wiki/Nominatim_usage_policy

Limitations


Please limit request rate to 1 per second and include your contact information in User-Agent headers. Data licensed under CC-BY-SA (you must provide attribution).


Yandex (:yandex)¶ ↑


API key


required

Key signup


api.yandex.ru/maps/intro/concepts/intro.xml#apikey

Quota


?

Region


Russia

SSL support


no

Languages


Russian, Belarusian, and Ukrainian

Documentation


api.yandex.ru/maps/geocoder/doc/desc/concepts/response_structure.xml

Terms of Service


api.yandex.com/direct/eula.xml?ncrnd=8453

Limitations


?


Geocoder.ca (:geocoder_ca)¶ ↑


API key


none

Quota


?

Region


US and Canada

SSL support


no

Languages


English

Documentation


?

Terms of Service


geocoder.ca/?terms=1

Limitations


“Under no circumstances can our data be re-distributed or re-sold by anyone to other parties without our written permission.”


FreeGeoIP¶ ↑


API key


none

Quota


1000 requests per hour.  After reaching the hourly quota, all of your requests will result in HTTP 403 (Forbidden) until it clears up on the next roll over.

Region


world

SSL support


no

Languages


English

Documentation


github.com/fiorix/freegeoip/blob/master/README.rst

Terms of Service


?

Limitations


?


Caching¶ ↑


It’s a good idea, when relying on any external service, to cache retrieved data. When implemented correctly it improves your app’s response time and stability. It’s easy to cache geocoding results with Geocoder, just configure a cache store:

Geocoder::Configuration.cache = Redis.new


This example uses Redis, but the cache store can be any object that supports these methods:


store#[](key)         - retrieves a value


store#[]=(key, value) - stores a value


store#keys            - lists all keys


Even a plain Ruby hash will work, though it’s not a great choice (cleared out when app is restarted, not shared between app instances, etc).

You can also set a custom prefix to be used for cache keys:

Geocoder::Configuration.cache_prefix = "..."


By default the prefix is geocoder: