README.md in geocoder-1.1.6 vs README.md in geocoder-1.1.7

@@ -107,10 +107,12 @@
 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
 
+Note that this will usually return `nil` in your test and development environments because things like "localhost" and "0.0.0.0" are not an Internet IP addresses.
+
 See _Advanced Geocoding_ below for more information about `Geocoder::Result` objects.
 
 
 Location-Aware Database Queries
 -------------------------------
@@ -176,11 +178,11 @@
 
     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`).
+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`, `:km`, or `:nm` for nautical miles).
 
 
 Model Configuration
 -------------------
 
@@ -380,10 +382,21 @@
 * **Languages**: English
 * **Documentation**: http://www.mapquestapi.com/geocoding/
 * **Terms of Service**: http://info.mapquest.com/terms-of-use/
 * **Limitations**: ?
 
+#### Ovi/Nokia (`:ovi`)
+
+* **API key**: not required, but performance restricted without it
+* **Quota**: ?
+* **Region**: world
+* **SSL support**: no
+* **Languages**: English
+* **Documentation**: http://api.maps.ovi.com/devguide/overview.html
+* **Terms of Service**: http://www.developer.nokia.com/Develop/Maps/TC.html
+* **Limitations**: ?
+
 #### FreeGeoIP (`: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
@@ -401,12 +414,24 @@
 * **SSL support**: yes
 * **Languages**: English
 * **Documentation**: http://www.maxmind.com/app/web_services
 * **Terms of Service**: ?
 * **Limitations**: ?
+* **Notes**: You must specify which MaxMind service you are using in your configuration. For example: `Geocoder.configure(:maxmind => {:service => :omni})`.
 
+#### ESRI (`:esri`)
 
+* **API key**: none
+* **Quota**: Required for some scenarios (see Terms of Service)
+* **Region**: world
+* **SSL support**: yes
+* **Languages**: English
+* **Documentation**: http://resources.arcgis.com/en/help/arcgis-online-geocoding-rest-api/
+* **Terms of Service**: http://www.esri.com/software/arcgis/arcgisonline/services/geoservices
+* **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:
 
@@ -469,11 +494,35 @@
       reverse_geocoded_by :latitude, :longitude
     end
 
 The reason for this is that we don't want ambiguity when doing distance calculations. We need a single, authoritative source for coordinates!
 
+Once both forward and reverse geocoding has been applied, it is possible to call them sequentially.
 
+For example:
+
+    class Venue
+
+      after_validation :geocode, :reverse_geocode
+
+    end
+
+For certain geolocation services such as Google geolocation API this may cause issues during subsequent updates to database records if the longtitude and latitude coordinates cannot be associated known location address (on a large body of water for example). On subsequent callbacks the following call:
+
+     after_validation :geocode
+
+will alter the longtitude and latitude attributes based on the location field, which would be the closest known location to the original coordinates. In this case it is better to add conditions to each call, as not to override coordinates that do not have known location addresses associated with them.
+
+For example:
+
+    class Venue
+
+      after_validation :reverse_geocode, :if => :has_coordinates
+      after_validation :geocode, :if => :has_location, :unless => :has_coordinates
+
+    end  
+
 Use Outside of Rails
 --------------------
 
 You can use Geocoder outside of Rails by calling the `Geocoder.search` method:
 
@@ -501,13 +550,30 @@
           'country_code' => 'US'
         }
       ]
     )
 
-Now, any time Geocoder looks up "New York, NY" its results array will contain one result with the above attributes.
+Now, any time Geocoder looks up "New York, NY" its results array will contain one result with the above attributes. You can also set a default stub:
 
+    Geocoder.configure(:lookup => :test)
 
+    Geocoder::Lookup::Test.set_default_stub(
+      [
+        {
+          'latitude'     => 40.7143528,
+          'longitude'    => -74.0059731,
+          'address'      => 'New York, NY, USA',
+          'state'        => 'New York',
+          'state_code'   => 'NY',
+          'country'      => 'United States',
+          'country_code' => 'US'
+        }
+      ]
+    )
+
+Any query that hasn't been explicitly stubbed will return that result.
+
 Command Line Interface
 ----------------------
 
 When you install the Geocoder gem it adds a `geocode` command to your shell. You can search for a street address, IP address, postal code, coordinates, etc just like you can with the Geocoder.search method for example:
 
@@ -627,9 +693,23 @@
 
 A lot of debugging time can be saved by understanding how Geocoder works with ActiveRecord. When you use the `near` scope or the `nearbys` method of a geocoded object, Geocoder creates an ActiveModel::Relation object which adds some attributes (eg: distance, bearing) to the SELECT clause. It also adds a condition to the WHERE clause to check that distance is within the given radius. Because the SELECT clause is modified, anything else that modifies the SELECT clause may produce strange results, for example:
 
 * using the `pluck` method (selects only a single column)
 * specifying another model through `includes` (selects columns from other tables)
+
+### Unexpected Responses from Geocoding Services
+
+Take a look at the server's raw JSON response. You can do this by getting the request URL in an app console:
+
+    Geocoder::Lookup.get(:google).query_url(Geocoder::Query.new("..."))
+
+Replace `:google` with the lookup you are using and replace `...` with the address you are trying to geocode. Then visit the returned URL in your web browser. Often the API will return an error message that helps you resolve the problem. If, after reading the raw response, you believe there is a problem with Geocoder, please post an issue and include both the URL and raw response body.
+
+
+Reporting Issues
+----------------
+
+When reporting an issue, please list the version of Geocoder you are using and any relevant information about your application (Rails version, database type and version, etc). Also avoid vague language like "it doesn't work." Please describe as specifically as you can what behavior your are actually seeing (eg: an error message? a nil return value?).
 
 
 Known Issue
 -----------