geocoder 1.1.6 → 1.1.7

data/CHANGELOG.md

@@ -1,7 +1,21 @@
 Changelog
 =========
 
-Per-release changes to Geocoder.
+Per-release changes to Geocoder. Note that only major changes are summarized here. Please see the Git log for all changes.
+
+1.1.7 (2013 Apr 21)
+-------------------
+
+* Add support for Ovi/Nokia API (thanks github.com/datenimperator).
+* Add support for ESRI API (thanks github.com/rpepato).
+* Add ability to omit distance and bearing from SQL select clause (thanks github.com/nicolasdespres).
+* Add support for caches that use read/write methods (thanks github.com/eskil).
+* Add support for nautical miles (thanks github.com/vanboom).
+* Fix: bug in parsing of MaxMind responses.
+* Fix: bugs in query regular expressions (thanks github.com/boone).
+* Fix: various bugs in MaxMind implementation.
+* Fix: don't require a key for MapQuest.
+* Fix: bug in handling of HTTP_X_FORWARDED_FOR header (thanks github.com/robdimarco).
 
 1.1.6 (2012 Dec 24)
 -------------------

data/README.md

@@ -109,6 +109,8 @@ Geocoder adds a `location` method to the standard `Rack::Request` object so you
     # 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.
 
 
@@ -178,7 +180,7 @@ To calculate accurate distance and bearing with SQLite or MongoDB:
     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
@@ -382,6 +384,17 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **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
@@ -403,6 +416,18 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **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
@@ -471,6 +496,30 @@ However, there can be only one set of latitude/longitude attributes, and whichev
 
 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
 --------------------
@@ -503,8 +552,25 @@ When writing tests for an app that uses Geocoder it may be useful to avoid netwo
       ]
     )
 
-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
 ----------------------
@@ -630,6 +696,20 @@ A lot of debugging time can be saved by understanding how Geocoder works with Ac
 * 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
 -----------

data/examples/autoexpire_cache_dalli.rb

@@ -0,0 +1,62 @@
+# This class implements a cache with simple delegation to the the Dalli Memcached client
+# https://github.com/mperham/dalli
+#
+# A TTL is set on initialization
+
+class AutoexpireCacheDalli
+  def initialize(store, ttl = 86400)
+    @store = store
+    @keys = 'GeocoderDalliClientKeys'
+    @ttl = ttl
+  end
+
+  def [](url)
+    res = @store.get(url)
+    res = YAML::load(res) if res.present?
+    res
+  end
+
+  def []=(url, value)
+    if value.nil?
+      del(url)
+    else
+      key_cache_add(url) if @store.add(key, YAML::dump(value), @ttl)
+    end
+    value
+  end
+
+  def keys
+    key_cache
+  end
+
+  def del(url)
+    key_cache_delete(url) if @store.delete(key)
+  end
+
+  private
+
+  def key_cache
+    the_keys = @store.get(@keys)
+    if the_keys.nil?
+      @store.add(@keys, YAML::dump([]))
+      []
+    else
+      YAML::load(the_keys)
+    end
+  end
+
+  def key_cache_add(key)
+    @store.replace(@keys, YAML::dump(key_cache << key))
+  end
+
+  def key_cache_delete(key)
+    tmp = key_cache
+    tmp.delete(key)
+    @store.replace(@keys, YAML::dump(tmp))
+  end
+end
+
+# Here Dalli is set up as on Heroku using the Memcachier gem.
+# https://devcenter.heroku.com/articles/memcachier#ruby
+# On other setups you might have to specify your Memcached server in Dalli::Client.new
+Geocoder.configure(:cache => AutoexpireCacheDalli.new(Dalli::Client.new))

data/examples/{autoexpire_cache.rb → autoexpire_cache_redis.rb}

@@ -1,10 +1,10 @@
 # This class implements a cache with simple delegation to the Redis store, but
 # when it creates a key/value pair, it also sends an EXPIRE command with a TTL.
 # It should be fairly simple to do the same thing with Memcached.
-class AutoexpireCache
-  def initialize(store)
+class AutoexpireCacheRedis
+  def initialize(store, ttl = 86400)
     @store = store
-    @ttl = 86400
+    @ttl = ttl
   end
 
   def [](url)
@@ -25,4 +25,4 @@ class AutoexpireCache
   end
 end
 
-Geocoder.configure(:cache => AutoexpireCache.new(Redis.new))
+Geocoder.configure(:cache => AutoexpireCacheRedis.new(Redis.new))

data/lib/generators/geocoder/config/templates/initializer.rb

@@ -18,4 +18,4 @@ Geocoder.configure(
   # calculation options
   # :units     => :mi,       # :km for kilometers or :mi for miles
   # :distances => :linear    # :spherical or :linear
-end
+)

data/lib/geocoder.rb

@@ -44,7 +44,7 @@ module Geocoder
   #
   def cache
     warn "WARNING: Calling Geocoder.cache is DEPRECATED. The #cache method now belongs to the Geocoder::Lookup object."
-    Geocoder::Lookup.get(Geocoder.config.lookup).send(:configuration).cache
+    Geocoder::Lookup.get(Geocoder.config.lookup).cache
   end
 end
 

data/lib/geocoder/cache.rb

@@ -15,6 +15,8 @@ module Geocoder
           store[key_for(url)]
         when store.respond_to?(:get)
           store.get key_for(url)
+        when store.respond_to?(:read)
+          store.read key_for(url)
       end
     end
 
@@ -27,6 +29,8 @@ module Geocoder
           store[key_for(url)] = value
         when store.respond_to?(:set)
           store.set key_for(url), value
+        when store.respond_to?(:write)
+          store.write key_for(url), value
       end
     end
 

data/lib/geocoder/calculations.rb

@@ -21,6 +21,11 @@ module Geocoder
     #
     KM_IN_MI = 0.621371192
 
+    ##
+    # Conversion factor: multiply by nautical miles to get miles.
+    #
+    KM_IN_NM = 0.539957
+
     # Not a number constant
     NAN = defined?(::Float::NAN) ? ::Float::NAN : 0 / 0.0
 
@@ -263,13 +268,24 @@ module Geocoder
       km * km_in_mi
     end
 
+    ##
+    # Convert kilometers to nautical miles.
+    #
+    def to_nautical_miles(km)
+      km * km_in_nm
+    end
+
     ##
     # Radius of the Earth in the given units (:mi or :km).
     # Use Geocoder.configure(:units => ...) to configure default units.
     #
     def earth_radius(units = nil)
       units ||= Geocoder.config.units
-      units == :km ? EARTH_RADIUS : to_miles(EARTH_RADIUS)
+      case units
+        when :km; EARTH_RADIUS
+        when :mi; to_miles(EARTH_RADIUS)
+        when :nm; to_nautical_miles(EARTH_RADIUS)
+      end
     end
 
     ##
@@ -279,6 +295,15 @@ module Geocoder
       KM_IN_MI
     end
 
+    ##
+    # Conversion factor: km to nm.
+    #
+    def km_in_nm
+      KM_IN_NM
+    end
+
+
+
     ##
     # Conversion factor: mi to km.
     #
@@ -286,6 +311,13 @@ module Geocoder
       1.0 / KM_IN_MI
     end
 
+    ##
+    # Conversion factor: nm to km.
+    #
+    def nm_in_km
+      1.0 / KM_IN_NM
+    end
+
     ##
     # Takes an object which is a [lat,lon] array, a geocodable string,
     # or an object that implements +to_coordinates+ and returns a

data/lib/geocoder/lookup.rb

@@ -21,6 +21,7 @@ module Geocoder
     #
     def street_services
       [
+        :esri,
         :google,
         :google_premier,
         :yahoo,
@@ -29,6 +30,7 @@ module Geocoder
         :yandex,
         :nominatim,
         :mapquest,
+        :ovi,
         :test
       ]
     end

data/lib/geocoder/lookups/base.rb

@@ -72,6 +72,16 @@ module Geocoder
       def query_url(query)
         fail
       end
+      
+      ##
+      # The working Cache object.
+      #
+      def cache
+        if @cache.nil? and store = configuration.cache
+          @cache = Cache.new(store, configuration.cache_prefix)
+        end
+        @cache
+      end
 
       private # -------------------------------------------------------------
 
@@ -225,16 +235,6 @@ module Geocoder
         end
       end
 
-      ##
-      # The working Cache object.
-      #
-      def cache
-        if @cache.nil? and store = configuration.cache
-          @cache = Cache.new(store, configuration.cache_prefix)
-        end
-        @cache
-      end
-
       ##
       # Simulate ActiveSupport's Object#to_query.
       # Removes any keys with nil value.

data/lib/geocoder/lookups/esri.rb

@@ -0,0 +1,52 @@
+require 'geocoder/lookups/base'
+require "geocoder/results/esri"
+require 'rack/utils'
+
+module Geocoder::Lookup
+  class Esri < Base
+    
+    def name
+      "Esri"
+    end
+
+    def query_url(query)
+      search_keyword = query.reverse_geocode? ? "reverseGeocode" : "find"
+
+      "#{protocol}://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/#{search_keyword}?" +
+        url_query_string(query)
+    end
+
+    private # ---------------------------------------------------------------
+
+    def results(query)
+      return [] unless doc = fetch_data(query)
+
+      if (!query.reverse_geocode?)
+        return [] if doc['locations'].empty?
+      end
+
+      if (doc['error'].nil?)
+        return [ doc ]
+      else
+        return []
+      end
+    end
+
+    def query_url_params(query)
+      if query.reverse_geocode?
+        {
+          :location => query.coordinates.reverse.join(','),
+          :outFields => :*,
+          :p => :pjson
+        }.merge(super)
+      else
+        {
+          :f => :pjson,
+          :outFields => :*,
+          :text => query.sanitized_text
+        }.merge(super)
+      end
+    end  
+
+  end
+end

data/lib/geocoder/lookups/mapquest.rb

@@ -10,7 +10,7 @@ module Geocoder::Lookup
     end
 
     def required_api_key_parts
-      ["key"]
+      []
     end
 
     def query_url(query)