geosack 1.0

data/README

@@ -0,0 +1,44 @@
+== Geosack On Rails
+
+This plugin enables you to utilize geosack.com unique geocode caching service. Geosack provides a persistent api that caches google-map/geocode lookups - enabling you to re-request the same information any number of times you like without exceeding your quota's or rate-limits from google.
+
+To install the plugin, extract the files from the archive to a directory named "geosack" in your vendors/plugin directory.  
+
+Using the plugin is straightforward:
+
+To use the geocoding service you will need a google API key, obtained from here:
+
+http://code.google.com/apis/maps/signup.html
+
+Once you have this key, you can create your Geosack object:
+
+  geosack = Geosack::Base.new(:api_key => YOUR_API_KEY)
+
+Then you are free to start making geocode requests.
+
+  result, location = geosack.geo(:q => 'San Jose')
+  
+The placename to be looked is specified by the :q parameter. The only other parameter is :output which is the response format - KML/XML/JSON. The default response format is XML.
+
+You don't need to worry about the 2 second delay that google requires - geosack takes care of that for you.
+  
+The result object is a reflection of the response returned by google to your request. Anything other than a 200 (G_GEO_SUCCESS) is a failure.
+
+You will also need to check for 610 (G_GEO_TOO_MANY_QUERIES) responses which indicate you have reached your limit for the 24 period. Note that this limit only applies to new requests sent to google - if you send a request that has already been cached by geosack, the response will come from geosack, not from google, and your daily limit will be unaffected.
+  
+Heres an example to get your started:
+
+  geosack = Geosack::Base.new(:key => API_KEY)
+  result, resp = geosack.geo(:q => lookup)
+  if result == Geosack::StatusCodes::G_GEO_SUCCESS
+    doc = REXML::Document.new(resp)
+    doc.root.each_element('//Response') do |response|
+      response.each_element('//Placemark') do |place|
+        longitude,latitude = place.elements['//coordinates'].text.split(',')
+      end
+    end
+  else
+    # failed
+  end
+
+Have fun, and feel free to contact us at mailto:info@packetnode.com with any questions or suggestions.

data/lib/geosack.rb

@@ -0,0 +1,126 @@
+# Copyright (c) 2008 Philip Mcmahon
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Geosack #:nodoc:
+  
+  class GeosackError < StandardError; end #:nodoc
+  
+  # Base class
+  class Base
+    
+    # Defines the required parameter(s)
+    REQUIRED_OPTIONS = {:base => [:key],
+                        :geo  => [:q]}
+                        
+    GEOSACK_URL = 'http://www.geosack.com/maps/geo'
+    STATUS_RESPONSE = '//kml/Response/Status/code'
+          
+    attr_accessor :key
+    
+    # Initializes the Geosack::Base class
+    # 
+    #  geosack = Geosack::Base.new(:api_key => 'MY_API_KEY')
+    #
+    # === Required options
+    #   :api_key        - Your Google geocoding/maps API key
+    def initialize(options = {})
+      check_options(:base, options)
+      @key = CGI.escape(options[:key])
+    end
+    
+    # Geocodes an address from Geosack
+    #
+    #  > geosack = Geosack::Base.new(:api_key => 'MY_API_KEY')
+    #  > result, location = geosack.geo('San Jose')
+    # 
+    #  > result
+    #  200
+    #  > location
+    #   ... <kml xmlns='http://earth.google.com/kml/2.0'><Response><name>San Jose</name> ...
+    #
+    # === Required options
+    #   :q - The query you wish to submit to Geosack, e.g. 'San Jose'
+    #
+    # === Optional options
+    #   :output    - The output format you are expecting - see Module Outputs
+    def geo(options = {})
+      
+      # Check options
+      check_options(:geo, options)
+      q = CGI.escape(options[:q])
+      output = options[:output] ? CGI.escape(options[:output]) : Outputs::XML
+
+      # first we'll open the url
+      resp = open("#{GEOSACK_URL}?q=#{q}&output=#{output}&key=#{@key}").read
+
+      # then we'll check for the status
+      begin
+        doc = REXML::Document.new(resp)
+        result = doc.elements[STATUS_RESPONSE].text.to_i
+      rescue Exception # bad - too generic
+        if output == Outputs::JSON
+          # :{"code":200,"request":"geocode"}
+          result = resp.scan(/\d+/)[0].to_i
+          puts result
+        else
+          result = StatusCodes::G_GEO_SERVER_ERROR
+        end
+      end
+        
+      [result, resp]
+    end
+    
+    private
+    
+    # Checks options
+    def check_options(method_name, options = {})
+      required_options = REQUIRED_OPTIONS[method_name]
+      missing = []
+      required_options.each{|option| missing << option if options[option].nil?}
+      
+      unless missing.empty?
+        raise GeosackError.new("Missing #{missing.collect{|m| ":#{m}"}.join(', ')}")
+      end
+    end
+    
+  end # Base
+  
+  # Allowed response formats
+  module Outputs
+    XML   = "xml"
+    JSON  = "json"
+    KML   = "kml"
+  end
+  
+  # http://code.google.com/apis/maps/documentation/reference.html#GGeoStatusCode
+  module StatusCodes
+    G_GEO_SUCCESS = 200
+    G_GEO_BAD_REQUEST = 400
+    G_GEO_SERVER_ERROR = 500	 
+    G_GEO_MISSING_QUERY = 601	
+    G_GEO_MISSING_ADDRESS = 601 
+    G_GEO_UNKNOWN_ADDRESS = 602 
+    G_GEO_UNAVAILABLE_ADDRESS = 603 
+    G_GEO_UNKNOWN_DIRECTIONS = 604 
+    G_GEO_BAD_KEY = 610 
+    G_GEO_TOO_MANY_QUERIES = 620 
+  end
+  
+end

data/test/geosack_test.rb

@@ -0,0 +1,44 @@
+require 'test/unit'
+require 'geosack'
+require 'cgi'
+require 'open-uri'
+require 'rexml/document'
+
+class GeosackTest < Test::Unit::TestCase
+  
+  # sample google key
+  API_KEY = "ABQIAAAAEMOKUmwrte1WeNNUKp0ckxTlf0blA_rqbbsuTeo2-FuKFlnNphQEGVnMEOB5H-hLCg_bC_vszRN8Yw"
+  INVALID_KEY = "Invalid Key"
+
+  def test_valid_lookup
+    # sample google key 
+    latitude, longitude = 0.0, 0.0
+    lookup = "San Jose"
+    geosack = Geosack::Base.new(:key => API_KEY)
+    result, resp = geosack.geo(:q => lookup)
+    assert_equal(Geosack::StatusCodes::G_GEO_SUCCESS, result)
+    doc = REXML::Document.new(resp)
+    doc.root.each_element('//Response') do |response|
+      response.each_element('//Placemark') do |place|
+        longitude,latitude = place.elements['//coordinates'].text.split(',')
+      end
+    end
+    assert_equal(37.316466, latitude.to_f)
+    assert_equal(-121.873881, longitude.to_f)
+  end
+  
+  def test_invalid_lookup
+    lookup = "invalid lookup"
+    geosack = Geosack::Base.new(:key => API_KEY)
+    result, resp = geosack.geo(:q => lookup)
+    assert_equal(Geosack::StatusCodes::G_GEO_UNKNOWN_ADDRESS, result)
+  end
+  
+  def test_invalid_key
+    geosack = Geosack::Base.new(:key => INVALID_KEY)
+    lookup = "San Jose"
+    result, resp = geosack.geo(:q => lookup)
+    assert_equal(Geosack::StatusCodes::G_GEO_BAD_KEY, result)
+  end
+  
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification 
+name: geosack
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Philip Mcmahon
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-02-17 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: info@packetnode.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/geosack.rb
+- README
+has_rdoc: true
+homepage: http://geosack.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: geosack_plugin
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: This ruby on rails plugin enables you to utilize the geosack.com unique geocode caching service, which provides a persistent api that caches your google-map/geocode lookups.
+test_files: 
+- test/geosack_test.rb