rails-geocoder 0.9.7 → 0.9.8

data/CHANGELOG.rdoc

@@ -2,10 +2,19 @@
 
 Per-release changes to Geocoder.
 
+== 0.9.8 (TBA)
+
+* Include geocode:all Rake task in gem (was missing!).
+* Add Geocoder.search for access to Google's full response.
+* Add ability to configure Google connection timeout.
+* Emit warnings on Google connection problems and errors.
+* Refactor: insert Geocoder into ActiveRecord via Railtie.
+
 == 0.9.7 (2011 Feb 1)
 
 * Add reverse geocoding (+reverse_geocoded_by+).
 * Prevent exception (uninitialized constant Geocoder::Net) when net/http not already required (sleepycat).
+* Refactor: split monolithic Geocoder module into several smaller ones.
 
 == 0.9.6 (2011 Jan 19)
 

data/README.rdoc

@@ -97,8 +97,11 @@ If your model has +address+, +city+, +state+, and +country+ attributes you might
     [address, city, state, country].compact.join(', ')
   end
 
+Please see the code (<tt>lib/geocoder/active_record.rb</tt>) for more methods and detailed information about arguments (eg, working with kilometers).
 
-Please see the code for more methods and detailed information about arguments (eg, working with kilometers).
+You can also set the timeout used for connections to Google's geocoding service. The default is 3 seconds, but if you want to set it to 5 you could put the following in an initializer:
+
+  Geocoder::Configuration.timeout = 5
 
 
 == Reverse Geocoding
@@ -172,15 +175,12 @@ If anyone has a more elegant solution to this problem I am very interested in se
 
 == To-do List
 
+* support different ORMs (DataMapper, Mongoid, etc)
 * use completely separate "drivers" for different AR adapters?
   * seems reasonable since we're using very DB-specific features
   * also need to make sure 'mysql2' is supported
 * make 'near' scope work with AR associations
   * http://stackoverflow.com/questions/3266358/geocoder-rails-plugin-near-search-problem-with-activerecord
-* prepend table names to column names in SQL distance expression (required
-  to do joins on another geocoded model)
-* unobtrusively add ability to get a result with more data (Geocoder object?)
-  * the default usage should remain dead simple
 
 
-Copyright (c) 2009-10 Alex Reisner, released under the MIT license
+Copyright (c) 2009-11 Alex Reisner, released under the MIT license

data/lib/geocoder.rb

@@ -1,53 +1,23 @@
+require "geocoder/configuration"
 require "geocoder/calculations"
 require "geocoder/lookup"
+require "geocoder/result"
 require "geocoder/active_record"
+require "geocoder/railtie"
 
-##
-# Add geocoded_by method to ActiveRecord::Base so Geocoder is accessible.
-#
-ActiveRecord::Base.class_eval do
+module Geocoder
+  extend self
 
   ##
-  # Set attribute names and include the Geocoder module.
+  # Alias for Geocoder::Lookup.search.
   #
-  def self.geocoded_by(address_attr, options = {})
-    _geocoder_init(
-      :user_address => address_attr,
-      :latitude  => options[:latitude]  || :latitude,
-      :longitude => options[:longitude] || :longitude
-    )
+  def search(*args)
+    Lookup.search(*args)
   end
 
-  ##
-  # Set attribute names and include the Geocoder module.
-  #
-  def self.reverse_geocoded_by(latitude_attr, longitude_attr, options = {})
-    _geocoder_init(
-      :fetched_address => options[:address] || :address,
-      :latitude  => latitude_attr,
-      :longitude => longitude_attr
-    )
-  end
-
-  def self._geocoder_init(options)
-    unless _geocoder_initialized?
-      class_inheritable_reader :geocoder_options
-      class_inheritable_hash_writer :geocoder_options
-    end
-    self.geocoder_options = options
-    unless _geocoder_initialized?
-      include Geocoder::ActiveRecord
-    end
-  end
-
-  def self._geocoder_initialized?
-    included_modules.include? Geocoder::ActiveRecord
-  end
+  # exception classes
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
 end
 
-
-class GeocoderError < StandardError
-end
-
-class GeocoderConfigurationError < GeocoderError
-end
+Geocoder::Railtie.insert

data/lib/geocoder/active_record.rb

@@ -185,7 +185,7 @@ module Geocoder
     def fetch_coordinates(save = false)
       address_method = self.class.geocoder_options[:user_address]
       unless address_method.is_a? Symbol
-        raise GeocoderConfigurationError,
+        raise Geocoder::ConfigurationError,
           "You are attempting to fetch coordinates but have not specified " +
           "a method which provides an address for the object."
       end
@@ -213,7 +213,7 @@ module Geocoder
       lat_attr = self.class.geocoder_options[:latitude]
       lon_attr = self.class.geocoder_options[:longitude]
       unless lat_attr.is_a?(Symbol) and lon_attr.is_a?(Symbol)
-        raise GeocoderConfigurationError,
+        raise Geocoder::ConfigurationError,
           "You are attempting to fetch an address but have not specified " +
           "attributes which provide coordinates for the object."
       end

data/lib/geocoder/configuration.rb

@@ -0,0 +1,8 @@
+module Geocoder
+  class Configuration
+    cattr_accessor :timeout
+  end
+end
+
+Geocoder::Configuration.timeout = 3
+

data/lib/geocoder/lookup.rb

@@ -6,73 +6,85 @@ module Geocoder
 
     ##
     # Query Google for the coordinates of the given address.
-    # Returns array [lat,lon] if found, nil if not found or if network error.
     #
     def coordinates(address)
-      return nil if address.blank?
-      return nil unless doc = search(address, false)
-      # blindly use first result (assume it is most accurate)
-      place = doc['results'].first['geometry']['location']
-      ['lat', 'lng'].map{ |i| place[i] }
+      if (results = search(address)).size > 0
+        place = results.first.geometry['location']
+        ['lat', 'lng'].map{ |i| place[i] }
+      end
     end
 
     ##
     # Query Google for the address of the given coordinates.
-    # Returns string if found, nil if not found or if network error.
     #
     def address(latitude, longitude)
-      return nil if latitude.blank? || longitude.blank?
-      return nil unless doc = search("#{latitude},#{longitude}", true)
-      # blindly use first result (assume it is most accurate)
-      doc['results'].first['formatted_address']
+      if (results = search(latitude, longitude)).size > 0
+        results.first.formatted_address
+      end
     end
 
-
-    private # ---------------------------------------------------------------
-
     ##
-    # Query Google for geographic information about the given phrase.
-    # Returns a hash representing a valid geocoder response.
-    # Returns nil if non-200 HTTP response, timeout, or other error.
+    # Takes a search string (eg: "Mississippi Coast Coliseumf, Biloxi, MS") for
+    # geocoding, or coordinates (latitude, longitude) for reverse geocoding.
+    # Returns an array of Geocoder::Result objects,
+    # or nil if not found or if network error.
     #
-    def search(query, reverse = false)
-      doc = fetch_parsed_response(query, reverse)
-      doc && doc['status'] == "OK" ? doc : nil
+    def search(*args)
+      return nil if args[0].blank?
+      doc = parsed_response(args.join(","), args.size == 2)
+      [].tap do |results|
+        if doc
+          doc['results'].each{ |r| results << Result.new(r) }
+        end
+      end
     end
 
+
+    private # ---------------------------------------------------------------
+
     ##
     # Returns a parsed Google geocoder search result (hash).
-    # This method is not intended for general use (prefer Geocoder.search).
+    # Returns nil if non-200 HTTP response, timeout, or other error.
     #
-    def fetch_parsed_response(query, reverse = false)
-      if doc = fetch_raw_response(query, reverse)
-        ActiveSupport::JSON.decode(doc)
+    def parsed_response(query, reverse = false)
+      begin
+        doc = ActiveSupport::JSON.decode(fetch_data(query, reverse))
+      rescue SocketError
+        warn "Google Geocoding API connection cannot be established."
+      rescue TimeoutError
+        warn "Google Geocoding API not responding fast enough " +
+          "(see Geocoder::Configuration.timeout to set limit)."
+      end
+
+      case doc['status']; when "OK"
+        doc
+      when "OVER_QUERY_LIMIT"
+        warn "Google Geocoding API error: over query limit."
+      when "REQUEST_DENIED"
+        warn "Google Geocoding API error: request denied."
+      when "INVALID_REQUEST"
+        warn "Google Geocoding API error: invalid request."
       end
     end
 
     ##
-    # Returns a raw Google geocoder search result (JSON).
-    # This method is not intended for general use (prefer Geocoder.search).
+    # Fetches a raw Google geocoder search result (JSON string).
     #
-    def fetch_raw_response(query, reverse = false)
+    def fetch_data(query, reverse = false)
       return nil if query.blank?
-
-      # name parameter based on forward/reverse geocoding
-      param = reverse ? :latlng : :address
-
-      # build URL
-      params = { param => query, :sensor  => "false" }
-      url = "http://maps.google.com/maps/api/geocode/json?" + params.to_query
-
-      # query geocoder and make sure it responds quickly
-      begin
-        resp = nil
-        timeout(3) do
-          Net::HTTP.get_response(URI.parse(url)).body
-        end
-      rescue SocketError, TimeoutError
-        return nil
+      url = query_url(query, reverse)
+      timeout(Geocoder::Configuration.timeout) do
+        Net::HTTP.get_response(URI.parse(url)).body
       end
     end
+
+    def query_url(query, reverse = false)
+      params = {
+        (reverse ? :latlng : :address) => query,
+        :sensor => "false"
+      }
+      "http://maps.google.com/maps/api/geocode/json?" + params.to_query
+    end
   end
 end
+

data/lib/geocoder/railtie.rb

@@ -0,0 +1,68 @@
+require 'geocoder'
+
+module Geocoder
+  if defined? Rails::Railtie
+    require 'rails'
+    class Railtie < Rails::Railtie
+      initializer 'geocoder.insert_into_active_record' do
+        ActiveSupport.on_load :active_record do
+          Geocoder::Railtie.insert
+        end
+      end
+      rake_tasks do
+        load "tasks/geocoder.rake"
+      end
+    end
+  end
+
+  class Railtie
+    def self.insert
+
+      return unless defined?(::ActiveRecord)
+
+      ##
+      # Add methods to ActiveRecord::Base so Geocoder is accessible by models.
+      #
+      ::ActiveRecord::Base.class_eval do
+
+        ##
+        # Set attribute names and include the Geocoder module.
+        #
+        def self.geocoded_by(address_attr, options = {})
+          _geocoder_init(
+            :user_address => address_attr,
+            :latitude  => options[:latitude]  || :latitude,
+            :longitude => options[:longitude] || :longitude
+          )
+        end
+
+        ##
+        # Set attribute names and include the Geocoder module.
+        #
+        def self.reverse_geocoded_by(latitude_attr, longitude_attr, options = {})
+          _geocoder_init(
+            :fetched_address => options[:address] || :address,
+            :latitude  => latitude_attr,
+            :longitude => longitude_attr
+          )
+        end
+
+        def self._geocoder_init(options)
+          unless _geocoder_initialized?
+            class_inheritable_reader :geocoder_options
+            class_inheritable_hash_writer :geocoder_options
+          end
+          self.geocoder_options = options
+          unless _geocoder_initialized?
+            include Geocoder::ActiveRecord
+          end
+        end
+
+        def self._geocoder_initialized?
+          included_modules.include? Geocoder::ActiveRecord
+        end
+      end
+
+    end
+  end
+end

data/lib/geocoder/result.rb

@@ -0,0 +1,42 @@
+module Geocoder
+  class Result
+    attr_accessor :data
+
+    ##
+    # Takes a hash of result data from a parsed Google result document.
+    #
+    def initialize(data)
+      @data = data
+    end
+
+    def types
+      @data['types']
+    end
+
+    def formatted_address
+      @data['formatted_address']
+    end
+
+    def address_components
+      @data['address_components']
+    end
+
+    ##
+    # Get address components of a given type. Valid types are defined in
+    # Google's Geocoding API documentation and include (among others):
+    #
+    #   :street_number
+    #   :locality
+    #   :neighborhood
+    #   :route
+    #   :postal_code
+    #
+    def address_components_of_type(type)
+      address_components.select{ |c| c['types'].include?(type.to_s) }
+    end
+
+    def geometry
+      @data['geometry']
+    end
+  end
+end

data/lib/tasks/geocoder.rake

@@ -0,0 +1,15 @@
+def klass
+  class_name = ENV['CLASS'] || ENV['class']
+  raise "Please specify a CLASS (model)" unless class_name
+  Object.const_get(class_name)
+end
+
+namespace :geocode do
+
+  desc "Geocode all objects without coordinates."
+  task :all => :environment do
+    klass.not_geocoded.each do |obj|
+      obj.fetch_coordinates!
+    end
+  end
+end

data/test/geocoder_test.rb

@@ -23,8 +23,14 @@ class GeocoderTest < Test::Unit::TestCase
 
   def test_exception_raised_for_unconfigured_geocoding
     l = Landmark.new("Mount Rushmore", 43.88, -103.46)
-    assert_raises GeocoderConfigurationError do
+    assert_raises Geocoder::ConfigurationError do
       l.fetch_coordinates
     end
   end
+
+  def test_result_address_components_of_type
+    results = Geocoder::Lookup.search("Madison Square Garden, New York, NY")
+    assert_equal "Manhattan",
+      results.first.address_components_of_type(:sublocality).first['long_name']
+  end
 end

data/test/test_helper.rb

@@ -39,7 +39,9 @@ require 'geocoder'
 #
 module Geocoder
   module Lookup
-    def self.fetch_raw_response(query, reverse = false)
+    extend self
+    private #-----------------------------------------------------------------
+    def fetch_data(query, reverse = false)
       File.read(File.join("test", "fixtures", "madison_square_garden.json"))
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rails-geocoder
 version: !ruby/object:Gem::Version 
-  hash: 53
+  hash: 43
   prerelease: false
   segments: 
   - 0
   - 9
-  - 7
-  version: 0.9.7
+  - 8
+  version: 0.9.8
 platform: ruby
 authors: 
 - Alex Reisner
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-01 00:00:00 -05:00
+date: 2011-02-08 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -32,7 +32,11 @@ files:
 - lib/geocoder.rb
 - lib/geocoder/lookup.rb
 - lib/geocoder/calculations.rb
+- lib/geocoder/railtie.rb
+- lib/geocoder/result.rb
+- lib/geocoder/configuration.rb
 - lib/geocoder/active_record.rb
+- lib/tasks/geocoder.rake
 - test/test_helper.rb
 - test/geocoder_test.rb
 - CHANGELOG.rdoc