Official Geokit Gem. Geokit gem provides geocoding and distance/heading calculations. Pair with the geokit-rails plugin for full-fledged location-based app functionality.

gem install geokit

    irb> require 'rubygems'
    irb> require 'geokit'
    irb> a=Geokit::Geocoders::GoogleGeocoder.geocode '140 Market St, San Francisco, CA'
    irb> a.ll
     => 37.79363,-122.396116
    irb> b=Geokit::Geocoders::GoogleGeocoder.geocode '789 Geary St, San Francisco, CA'
    irb> b.ll
     => 37.786217,-122.41619
    irb> a.distance_to(b)
     => 1.21120007413626
    irb> a.heading_to(b)
    => 244.959832435678
    irb(main):006:0> c=a.midpoint_to(b)      # what's halfway from a to b?
    irb> c.ll
    => "37.7899239257175,-122.406153503469"
    irb(main):008:0> d=c.endpoint(90,10)     # what's 10 miles to the east of c?
    irb> d.ll
    => "37.7897825005142,-122.223214776155"

    # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
    Geokit::default_units = :miles # others :kms, :nms, :meters
    Geokit::default_formula = :sphere

    # This is the timeout value in seconds to be used for calls to the geocoder web
    # services.  For no timeout at all, comment out the setting.  The timeout unit
    # is in seconds.
    Geokit::Geocoders::request_timeout = 3

    # This setting can be used if web service calls must be routed through a proxy.
    # These setting can be nil if not needed, otherwise, a valid URI must be
    # filled in at a minimum.  If the proxy requires authentication, the username
    # and password can be provided as well.
    Geokit::Geocoders::proxy = 'https://user:password@host:port'

    # This setting can be used if a web service blocks requests by certain user agents.
    # If not set Geokit uses the default useragent header set by the different net adapter libs.
    Geokit::Geocoders::useragent = 'my agent string'

    # This is your yahoo application key for the Yahoo Geocoder.
    # See http://developer.yahoo.com/faq/index.html#appid
    # and http://developer.yahoo.com/maps/rest/V1/geocode.html
    Geokit::Geocoders::YahooGeocoder.key = 'REPLACE_WITH_YOUR_YAHOO_KEY'
    Geokit::Geocoders::YahooGeocoder.secret = 'REPLACE_WITH_YOUR_YAHOO_SECRET'

    # This is your Google Maps geocoder keys (all optional).
    # See http://www.google.com/apis/maps/signup.html
    # and http://www.google.com/apis/maps/documentation/#Geocoding_Examples
    Geokit::Geocoders::GoogleGeocoder.client_id = ''
    Geokit::Geocoders::GoogleGeocoder.cryptographic_key = ''
    Geokit::Geocoders::GoogleGeocoder.channel = ''

    # You can also use the free API key instead of signed requests
    # See https://developers.google.com/maps/documentation/geocoding/#api_key
    Geokit::Geocoders::GoogleGeocoder.api_key = ''

    # You can also set multiple API KEYS for different domains that may be directed to this same application.
    # The domain from which the current user is being directed will automatically be updated for Geokit via
    # the GeocoderControl class, which gets it's begin filter mixed into the ActionController.
    # You define these keys with a Hash as follows:
    #Geokit::Geocoders::google = { 'rubyonrails.org' => 'RUBY_ON_RAILS_API_KEY', 'ruby-docs.org' => 'RUBY_DOCS_API_KEY' }

    # This is your username and password for geocoder.us.
    # To use the free service, the value can be set to nil or false.  For
    # usage tied to an account, the value should be set to username:password.
    # See http://geocoder.us
    # and http://geocoder.us/user/signup
    Geokit::Geocoders::UsGeocoder.key = 'username:password'

    # This is your authorization key for geocoder.ca.
    # To use the free service, the value can be set to nil or false.  For
    # usage tied to an account, set the value to the key obtained from
    # Geocoder.ca.
    # See http://geocoder.ca
    # and http://geocoder.ca/?register=1
    Geokit::Geocoders::CaGeocoder.key = 'KEY'

    # This is your username key for geonames.
    # To use this service either free or premium, you must register a key.
    # See http://www.geonames.org
    Geokit::Geocoders::GeonamesGeocoder.key = 'KEY'

    # This is your access key for ipstack.
    # To use this service either free or premium, you must register a key.
    # See https://ipstack.com
    Geokit::Geocoders::IpstackGeocoder.api_key = 'API_KEY'

    # Most other geocoders need either no setup or a key
    Geokit::Geocoders::BingGeocoder.key = ''
    Geokit::Geocoders::MapQuestGeocoder.key = ''
    Geokit::Geocoders::YandexGeocoder.key = ''
    Geokit::Geocoders::MapboxGeocoder.key = 'ACCESS_TOKEN'
    Geokit::Geocoders::OpencageGeocoder.key = 'some_api_key'

    # Geonames has a free service and a premium service, each using a different URL
    # GeonamesGeocoder.premium = true will use http://ws.geonames.net (premium)
    # GeonamesGeocoder.premium = false will use http://api.geonames.org (free)
    Geokit::Geocoders::GeonamesGeocoder.premium = false

    # require "external_geocoder.rb"
    # Please see the section "writing your own geocoders" for more information.
    # Geokit::Geocoders::external_key = 'REPLACE_WITH_YOUR_API_KEY'

    # This is the order in which the geocoders are called in a failover scenario
    # If you only want to use a single geocoder, put a single symbol in the array.
    #
    # Valid symbols are: :bing, :ca, :fcc, :geocodio, :geonames, :google,
    # :map_quest, :mapbox, :maxmind, :opencage, :osm, :us, :yahoo, and :yandex.
    #
    # Be aware that there are Terms of Use restrictions on how you can use the
    # various geocoders.  Make sure you read up on relevant Terms of Use for each
    # geocoder you are going to use.
    Geokit::Geocoders::provider_order = [:google,:us]

    # The IP provider order.
    #
    # Valid symbols are :ipstack, :geo_plugin, :geobytes, :ip, and :ripe.
    #
    # As before, make sure you read up on relevant Terms of Use for each.
    # Geokit::Geocoders::ip_provider_order = [:external,:geo_plugin,:ip]

	# Disable HTTPS globally.  This option can also be set on individual
	# geocoder classes.
    Geokit::Geocoders::secure = false

    # Control verification of the server certificate for geocoders using HTTPS
    Geokit::Geocoders::ssl_verify_mode = OpenSSL::SSL::VERIFY_(PEER/NONE)
    # Setting this to VERIFY_NONE may be needed on systems that don't have
    # a complete or up to date root certificate store. Only applies to
    # the Net::HTTP adapter.

    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('140 Market St, San Francisco, CA')
    irb> pp res.suggested_bounds
    #<Geokit::Bounds:0x53b36c
     @ne=#<Geokit::LatLng:0x53b204 @lat=37.7968528, @lng=-122.3926933>,
     @sw=#<Geokit::LatLng:0x53b2b8 @lat=37.7905576, @lng=-122.3989885>>

In addition, you can use viewport or country code biasing to make sure the geocoders prefers results within a specific area. Say we wanted to geocode the city of Toledo in Spain. A normal geocoding query would look like this:

    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Toledo')
    irb> res.full_address
    => "Toledo, OH, USA"

    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Toledo', :bias => 'es')
    irb> res.full_address
    => "Toledo, Toledo, Spain"

    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Winnetka')
    irb> res.full_address
    => "Winnetka, IL, USA"

    irb> la_bounds = Geokit::Geocoders::GoogleGeocoder.geocode('Los Angeles').suggested_bounds
    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Winnetka', :bias => la_bounds)
    irb> res.full_address
    => "Winnetka, California, USA"

    irb>res = Geokit::Geocoders::GoogleGeocoder.geocode("austin", components: { administrative_area: 'IL', country: 'US' })
    irb>res.full_address
    => "Austin, Chicago, IL, USA"

    Geokit::Geocoders::MultiGeocoder.geocode("900 Sycamore Drive")

    Geokit::Geocoders::MultiGeocoder.geocode("12.12.12.12")

    Geokit::Geocoders::MultiGeocoder.geocode("Hamburg, Germany", :provider_order => [:osm, :mapbox, :google])

    irb> geo=Geokit::Geocoders::GoogleGeocoder.geocode("900 Sycamore Drive")
    irb> geo.full_address
    => "900 Sycamore Dr, Arkadelphia, AR 71923, USA"
    irb> geo.all.size
    irb> geo.all.each { |e| puts e.full_address }
    900 Sycamore Dr, Arkadelphia, AR 71923, USA
    900 Sycamore Dr, Burkburnett, TX 76354, USA
    900 Sycamore Dr, TN 38361, USA
    ....

  require "geokit"

  module Geokit
    module Geocoders

      # and use :my to specify this geocoder in your list of geocoders.
      class MyGeocoder < Geocoder

        # Use via: Geokit::Geocoders::MyGeocoder.key = 'MY KEY'
        config :key

        private

        def self.do_geocode(address, options = {})
          # Main geocoding method
        end

        def self.parse_json(json)
          # Helper method to parse http response. See geokit/geocoders.rb.
        end
      end

    end
  end