geocoder 1.1.4 → 1.1.5

data/CHANGELOG.rdoc

@@ -2,6 +2,15 @@
 
 Per-release changes to Geocoder.
 
+== 1.1.5 (2012 Nov 9)
+
+* Replace support for old Yahoo Placefinder with Yahoo BOSS (thanks github.com/pwoltman).
+* Add support for actual Mapquest API (was previously just a proxy for Nominatim), including the paid service (thanks github.com/jedschneider).
+* Add support for :select => :id_only option to near scope.
+* Treat a given query as blank (don't do a lookup) if coordinates are given but latitude or longitude is nil.
+* Speed up 'near' queries by adding bounding box condition (thanks github.com/mlandauer).
+* Fix: don't redefine Object#hash in Yahoo result object (thanks github.com/m0thman).
+
 == 1.1.4 (2012 Oct 2)
 
 * Deprecate Geocoder::Result::Nominatim#class and #type methods. Use #place_class and #place_type instead.

data/README.md

@@ -263,7 +263,7 @@ By default Geocoder uses Google's geocoding API to fetch coordinates and street
     Geocoder.configure do |config|
 
       # geocoding service (see below for supported options):
-      config.lookup = :yahoo
+      config.lookup = :yandex
 
       # to use an API key:
       config.api_key = "..."
@@ -304,17 +304,19 @@ The following is a comparison of the supported geocoding APIs. The "Limitations"
 * **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`)
+#### Yahoo BOSS (`:yahoo`)
 
-* **API key**: optional in development (required for production apps)
-* **Key signup**: https://developer.apps.yahoo.com/wsregapp
-* **Quota**: 50,000 requests/day, more available by special arrangement
+Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer offers a free geocoding API.
+
+* **API key**: requires OAuth consumer key and secret (set `Geocoder::Configuration.api_key = [key, secret]`)
+* **Key signup**: http://developer.yahoo.com/boss/geo/
+* **Quota**: unlimited, but subject to usage fees
 * **Region**: world
 * **SSL support**: no
-* **Languages**: ?
-* **Documentation**: http://developer.yahoo.com/geo/placefinder/guide/responses.html
-* **Terms of Service**: http://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;"
+* **Languages**: en, fr, de, it, es, pt, nl, zh, ja, ko
+* **Documentation**: http://developer.yahoo.com/boss/geo/docs/index.html
+* **Terms of Service**: http://info.yahoo.com/legal/us/yahoo/boss/tou/?pir=ucJPcJ1ibUn.h.d.lVmlcbcEkoHjwJ_PvxG9SLK9VIbIQAw1XFrnDqY-
+* **Limitations**: No mass downloads, no commercial map production based on the data, no storage of data except for caching.
 
 #### Bing (`:bing`)
 
@@ -363,8 +365,11 @@ The following is a comparison of the supported geocoding APIs. The "Limitations"
 
 #### Mapquest (`:mapquest`)
 
-* **API key**: none
+* **API key**: required for the licensed API, do not use for open tier
 * **Quota**: ?
+* **HTTP Headers**: in order to use the licensed API you can configure the http_headers to include a referer as so:
+    `Geocoder::Configuration.http_headers = { "Referer" => "http://foo.com" }`
+  You can also allow a blank referer from the API management console via mapquest but it is potentially a security risk that someone else could use your API key from another domain.
 * **Region**: world
 * **SSL support**: no
 * **Languages**: English
@@ -524,6 +529,15 @@ Calling `obj.coordinates` directly returns the internal representation of the co
 
 For consistency with the rest of Geocoder, always use the `to_coordinates` method instead.
 
+Optimisation of Distance Queries
+--------------------------------
+
+In MySQL and Postgres the finding of objects near a given point is speeded up by using a bounding box to limit the number of points over which a full distance calculation needs to be done.
+
+To take advantage of this optimisation you need to add a composite index on latitude and longitude. In your Rails migration:
+
+    add_index :table, [:latitude, :longitude]
+
 
 Distance Queries in SQLite
 --------------------------

data/lib/geocoder/configuration.rb

@@ -23,7 +23,7 @@ module Geocoder
   #
   #   Geocoder.configure do |config|
   #     config.timeout      = 5
-  #     config.lookup       = :yahoo
+  #     config.lookup       = :yandex
   #     config.api_key      = "2a9fsa983jaslfj982fjasd"
   #     config.units        = :km
   #   end

data/lib/geocoder/lookups/base.rb

@@ -90,6 +90,16 @@ module Geocoder
         fail
       end
 
+      ##
+      # Key to use for caching a geocoding result. Usually this will be the
+      # request URL, but in cases where OAuth is used and the nonce,
+      # timestamp, etc varies from one request to another, we need to use
+      # something else (like the URL before OAuth encoding).
+      #
+      def cache_key(query)
+        query_url(query)
+      end
+
       ##
       # Class of the result objects
       #
@@ -144,25 +154,34 @@ module Geocoder
       end
 
       ##
-      # Fetches a raw search result (JSON string).
+      # Fetch a raw geocoding result (JSON string).
+      # The result might or might not be cached.
       #
       def fetch_raw_data(query)
-        timeout(Geocoder::Configuration.timeout) do
-          url = query_url(query)
-          uri = URI.parse(url)
-          if cache and body = cache[url]
-            @cache_hit = true
-          else
-            client = http_client.new(uri.host, uri.port)
-            client.use_ssl = true if Geocoder::Configuration.use_https
-            response = client.get(uri.request_uri, Geocoder::Configuration.http_headers)
-            body = response.body
-            if cache and (200..399).include?(response.code.to_i)
-              cache[url] = body
-            end
-            @cache_hit = false
+        key = cache_key(query)
+        if cache and body = cache[key]
+          @cache_hit = true
+        else
+          response = make_api_request(query)
+          body = response.body
+          if cache and (200..399).include?(response.code.to_i)
+            cache[key] = body
           end
-          body
+          @cache_hit = false
+        end
+        body
+      end
+
+      ##
+      # Make an HTTP(S) request to a geocoding API and
+      # return the response object.
+      #
+      def make_api_request(query)
+        timeout(Geocoder::Configuration.timeout) do
+          uri = URI.parse(query_url(query))
+          client = http_client.new(uri.host, uri.port)
+          client.use_ssl = true if Geocoder::Configuration.use_https
+          client.get(uri.request_uri, Geocoder::Configuration.http_headers)
         end
       end
 

data/lib/geocoder/lookups/bing.rb

@@ -29,7 +29,7 @@ module Geocoder::Lookup
     end
 
     def query_url(query)
-      "http://dev.virtualearth.net/REST/v1/Locations" +
+      "#{protocol}://dev.virtualearth.net/REST/v1/Locations" +
         (query.reverse_geocode? ? "/#{query.sanitized_text}?" : "?") +
         url_query_string(query)
     end

data/lib/geocoder/lookups/freegeoip.rb

@@ -37,7 +37,7 @@ module Geocoder::Lookup
     end
 
     def query_url(query)
-      "http://freegeoip.net/json/#{query.sanitized_text}"
+      "#{protocol}://freegeoip.net/json/#{query.sanitized_text}"
     end
   end
 end

data/lib/geocoder/lookups/geocoder_ca.rb

@@ -39,7 +39,7 @@ module Geocoder::Lookup
     end
 
     def query_url(query)
-      "http://geocoder.ca/?" + url_query_string(query)
+      "#{protocol}://geocoder.ca/?" + url_query_string(query)
     end
 
     def parse_raw_data(raw_data)

data/lib/geocoder/lookups/mapquest.rb

@@ -1,15 +1,36 @@
+require 'cgi'
 require 'geocoder/lookups/base'
-require "geocoder/lookups/nominatim"
 require "geocoder/results/mapquest"
 
 module Geocoder::Lookup
-  class Mapquest < Nominatim
+  class Mapquest < Base
 
     private # ---------------------------------------------------------------
 
     def query_url(query)
-      method = query.reverse_geocode? ? "reverse" : "search"
-      "http://open.mapquestapi.com/#{method}?" + url_query_string(query)
+      key = Geocoder::Configuration.api_key
+      domain = key ? "www" : "open"
+      url = "#{protocol}://#{domain}.mapquestapi.com/geocoding/v1/#{search_type(query)}?"
+      url + url_query_string(query)
     end
+
+    def search_type(query)
+      query.reverse_geocode? ? "reverse" : "address"
+    end
+
+    def query_url_params(query)
+      key = Geocoder::Configuration.api_key
+      params = { :location => query.sanitized_text }
+      if key
+        params[:key] = CGI.unescape(key)
+      end
+      super.merge(params)
+    end
+
+    def results(query)
+      return [] unless doc = fetch_data(query)
+      doc["results"][0]['locations']
+    end
+
   end
 end

data/lib/geocoder/lookups/nominatim.rb

@@ -34,7 +34,7 @@ module Geocoder::Lookup
 
     def query_url(query)
       method = query.reverse_geocode? ? "reverse" : "search"
-      "http://nominatim.openstreetmap.org/#{method}?" + url_query_string(query)
+      "#{protocol}://nominatim.openstreetmap.org/#{method}?" + url_query_string(query)
     end
   end
 end

data/lib/geocoder/lookups/yahoo.rb

@@ -1,5 +1,6 @@
 require 'geocoder/lookups/base'
 require "geocoder/results/yahoo"
+require 'oauth_util'
 
 module Geocoder::Lookup
   class Yahoo < Base
@@ -12,47 +13,16 @@ module Geocoder::Lookup
 
     def results(query)
       return [] unless doc = fetch_data(query)
-      doc = doc['ResultSet']
-      if api_version(doc).to_i == 1
-        return version_1_results(doc)
-      elsif api_version(doc).to_i == 2
-        return version_2_results(doc)
-      else
-        warn "Yahoo Geocoding API error: #{doc['Error']} (#{doc['ErrorMessage']})."
-        return []
-      end
-    end
-
-    def api_version(doc)
-      if doc.include?('version')
-        return doc['version'].to_f
-      elsif doc.include?('@version')
-        return doc['@version'].to_f
-      end
-    end
-
-    def version_1_results(doc)
-      if doc['Error'] == 0
-        if doc['Found'] > 0
-          return doc['Results']
-        else
-          return []
-        end
-      end
-    end
-
-    ##
-    # Return array of results, or nil if an error.
-    #
-    def version_2_results(doc)
-      # seems to have Error == 7 when no results, though this is not documented
-      if [0, 7].include?(doc['Error'].to_i)
-        if doc['Found'].to_i > 0
-          r = doc['Result']
-          return r.is_a?(Array) ? r : [r]
+      doc = doc['bossresponse']
+      if doc['responsecode'].to_i == 200
+        if doc['placefinder']['count'].to_i > 0
+          return doc['placefinder']['results']
         else
           return []
         end
+      else
+        warn "Yahoo Geocoding API error: #{doc['responsecode']} (#{doc['reason']})."
+        return []
       end
     end
 
@@ -60,14 +30,28 @@ module Geocoder::Lookup
       super.merge(
         :location => query.sanitized_text,
         :flags => "JXTSR",
-        :gflags => "AC#{'R' if query.reverse_geocode?}",
-        :locale => "#{Geocoder::Configuration.language}_US",
-        :appid => Geocoder::Configuration.api_key
+        :gflags => "AC#{'R' if query.reverse_geocode?}"
       )
     end
 
+    def cache_key(query)
+      raw_url(query)
+    end
+
+    def base_url
+      "#{protocol}://yboss.yahooapis.com/geo/placefinder?"
+    end
+
+    def raw_url(query)
+      base_url + url_query_string(query)
+    end
+
     def query_url(query)
-      "http://where.yahooapis.com/geocode?" + url_query_string(query)
+      parsed_url = URI.parse(raw_url(query))
+      o = OauthUtil.new
+      o.consumer_key = Geocoder::Configuration.api_key[0]
+      o.consumer_secret = Geocoder::Configuration.api_key[1]
+      base_url + o.sign(parsed_url).query_string
     end
   end
 end

data/lib/geocoder/lookups/yandex.rb

@@ -40,7 +40,7 @@ module Geocoder::Lookup
     end
 
     def query_url(query)
-      "http://geocode-maps.yandex.ru/1.x/?" + url_query_string(query)
+      "#{protocol}://geocode-maps.yandex.ru/1.x/?" + url_query_string(query)
     end
   end
 end

data/lib/geocoder/models/mongoid.rb

@@ -18,7 +18,7 @@ module Geocoder
         super(options)
         if options[:skip_index] == false
           # create 2d index
-          if (::Mongoid::VERSION >= "3")
+          if defined?(::Mongoid::VERSION) && ::Mongoid::VERSION >= "3"
             index({ geocoder_options[:coordinates].to_sym => '2d' }, 
                   {:min => -180, :max => 180})
           else

data/lib/geocoder/query.rb

@@ -40,7 +40,13 @@ module Geocoder
     # Is the Query text blank? (ie, should we not bother searching?)
     #
     def blank?
-      !!text.to_s.match(/^\s*$/)
+      # check whether both coordinates given
+      if text.is_a?(Array)
+        text.compact.size < 2
+      # else assume a string
+      else
+        !!text.to_s.match(/^\s*$/)
+      end
     end
 
     ##

data/lib/geocoder/results/base.rb

@@ -1,10 +1,16 @@
 module Geocoder
   module Result
     class Base
-      attr_accessor :data, :cache_hit
+
+      # data (hash) fetched from geocoding service
+      attr_accessor :data
+
+      # true if result came from cache, false if from request to geocoding
+      # service; nil if cache is not configured
+      attr_accessor :cache_hit
 
       ##
-      # Takes a hash of result data from a parsed Google result document.
+      # Takes a hash of data from a parsed geocoding service response.
       #
       def initialize(data)
         @data = data

data/lib/geocoder/results/mapquest.rb

@@ -1,7 +1,51 @@
 require 'geocoder/results/base'
-require 'geocoder/results/nominatim'
 
 module Geocoder::Result
-  class Mapquest < Nominatim
+  class Mapquest < Base
+    def latitude
+      @data["latLng"]["lat"]
+    end
+
+    def longitude
+      @data["latLng"]["lng"]
+    end
+
+    def coordinates
+      [latitude, longitude]
+    end
+
+    def city
+      @data['adminArea5']
+    end
+
+    def street
+      @data['street']
+    end
+
+    def state
+      @data['adminArea3']
+    end
+
+    alias_method :state_code, :state
+
+    #FIXME: these might not be right, unclear with MQ documentation
+    alias_method :provinice, :state
+    alias_method :province_code, :state
+
+    def postal_code
+      @data['postalCode'].to_s
+    end
+
+    def country
+      @data['adminArea1']
+    end
+
+    def country_code
+      country
+    end
+
+    def address
+      [street, city, state, postal_code, country].reject{|s| s.length == 0 }.join(", ")
+    end
   end
 end