README.markdown in geokit-1.8.5 vs README.markdown in geokit-1.9.0

@@ -9,11 +9,11 @@
 
 ## DESCRIPTION
 
 The Geokit gem provides:
 
- * Distance calculations between two points on the earth. Calculate the distance in miles, kilometers, or nautical miles, with all the trigonometry abstracted away by Geokit.
+ * Distance calculations between two points on the earth. Calculate the distance in miles, kilometers, meters, or nautical miles, with all the trigonometry abstracted away by Geokit.
  * Geocoding from multiple providers. It supports Google, Yahoo, Geocoder.us, and Geocoder.ca geocoders, and others. It provides a uniform response structure from all of them.
    It also provides a fail-over mechanism, in case your input fails to geocode in one service.
  * Rectangular bounds calculations: is a point within a given rectangular bounds?
  * Heading and midpoint calculations
 
@@ -43,15 +43,19 @@
 * Geonames - a free geocoder
 * Bing
 * Yandex
 * MapQuest
 * Geocod.io
+* Mapbox - requires an access token
+* [OpenCage](http://geocoder.opencagedata.com) - requires an API key
 
 ### address geocoders that also provide reverse geocoding
 * Google - Supports multiple results and bounding box/country code biasing.  Also supports Maps API for Business keys; see the configuration section below.
 * FCC
-* Open Street Map
+* OpenStreetMap
+* Mapbox
+* OpenCage
 
 ### IP address geocoders
 * IP - geocodes an IP address using hostip.info's web service.
 * Geoplugin.net -- another IP address geocoder
 * RIPE
@@ -62,10 +66,12 @@
 * Google
 * Yahoo
 * Bing
 * FCC
 * MapQuest
+* Mapbox
+* OpenCage
 
 Options to control the use of HTTPS are described below in the Configuration section.
 
 ## QUICK START
 
@@ -98,11 +104,11 @@
 
 If you're using this gem by itself, here are the configuration options:
 
 ```ruby
     # These defaults are used in Geokit::Mappable.distance_to and in acts_as_mappable
-    Geokit::default_units = :miles
+    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.
@@ -150,16 +156,27 @@
     # 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'
+
     # Most other geocoders need either no setup or a key
     Geokit::Geocoders::BingGeocoder.key = ''
-    Geokit::Geocoders::GeonamesGeocoder.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
@@ -174,15 +191,15 @@
     # 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 
-    
+    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 
+    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.
 ```
 
 ### Google Geocoder Tricks
@@ -194,22 +211,22 @@
     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 Syracuse in Italy. A normal geocoding query would look like this:
+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('Syracuse')
+    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Toledo')
     irb> res.full_address
-    => "Syracuse, NY, USA"
+    => "Toledo, OH, USA"
 ```
 
-Not exactly what we were looking for. We know that Syracuse is in Italy, so we can tell the Google Geocoder to prefer results from Italy first, and then wander the Syracuses of the world. To do that, we have to pass Italy's ccTLD (country code top-level domain) to the `:bias` option of the `geocode` method. You can find a comprehensive list of all ccTLDs here: http://en.wikipedia.org/wiki/CcTLD.
+Not exactly what we were looking for. We know that Toledo is in Spain, so we can tell the Google Geocoder to prefer results from Spain first, and then wander the Toledos of the world. To do that, we have to pass Italy's ccTLD (country code top-level domain) to the `:bias` option of the `geocode` method. You can find a comprehensive list of all ccTLDs here: http://en.wikipedia.org/wiki/CcTLD.
 
 ```ruby
-    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Syracuse', :bias => 'it')
+    irb> res = Geokit::Geocoders::GoogleGeocoder.geocode('Toledo', :bias => 'es')
     irb> res.full_address
-    => "Syracuse, Italy"
+    => "Toledo, Toledo, Spain"
 ```
 
 Alternatively, we can specify the geocoding bias as a bounding box object. Say we wanted to geocode the Winnetka district in Los Angeles.
 
 ```ruby