yahoo-geoplanet 0.1.0

data/History.txt

@@ -0,0 +1,3 @@
+== 0.1.0 2008-10-08
+
+* Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Mattt Thompson
+
+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.

data/Manifest.txt

@@ -0,0 +1,21 @@
+History.txt
+License.txt
+Manifest.txt
+PostInstall.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/rest.rb
+lib/yahoo-geoplanet.rb
+lib/yahoo-geoplanet/base.rb
+lib/yahoo-geoplanet/place.rb
+lib/yahoo-geoplanet/version.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake

data/README.txt

@@ -0,0 +1,91 @@
+= yahoo-geoplanet
+
+A Ruby wrapper for the Yahoo! GeoPlanet APIs.
+
+== Example Usage
+
+=== Searching for a Location:
+
+  require 'yahoo-geoplanet'
+  include Yahoo::GeoPlanet
+  Yahoo::GeoPlanet.app_id = [Your App ID Here]
+  
+  # Returns first 20 results by default
+  Place.search("Springfield")
+  
+  # ...but let's say you want _all_ of them
+  Place.search("Springfield", :count => 0) # Returns all 110
+  
+  # You can pass in any Matrix or Query parameters this way too
+  # For more details see the following URLs:
+  # http://developer.yahoo.com/geo/guide/resources_and_collections.html#matrix_parameters
+  # http://developer.yahoo.com/geo/guide/resources_and_collections.html#query_parameters
+  
+=== Initializing by Where On Earth ID && Associations
+  
+  require 'yahoo-geoplanet'
+  include Yahoo::GeoPlanet
+  Yahoo::GeoPlanet.app_id = [Your App ID Here]
+  
+  cmu = Place.new(23511275) # WoE ID for Carnegie Mellon University
+  
+  # Everything you get back from the API you have direct access to
+  # through the Place object. For example:
+  
+  puts cmu.type           # "Point of Interest"
+  puts cmu.county         # "Allegheny"
+  puts cmu.latitude       # 40.444
+                          # Latitude and Longitude are values at Centroid
+  puts cmu.bounding_box   # [[40.44445, -79.943314], [40.44355, -79.944511]]
+                          # Bounding box are NW / SE coordinates in array
+  
+  # We unlock the true power of GeoPlanet with association collections
+  # Check out this truly amazing stuff:
+  
+  # The containing GeoPlanet entity for CMU
+  puts cmu.parent # "Squirrel Hill North"
+  
+  # A list of other points of interest in the area
+  cmu.siblings.each{|s| puts s} 
+  
+  # A complete hierarchy, from country down to suburb
+  cmu.ancestors.each{|s| puts s} 
+
+== REQUIREMENTS:
+
+To use this library, you must have a valid Yahoo! App ID. 
+You can get one at http://developer.yahoo.com/wsregapp/
+
+Additionally, yahoo-geoplanet has the following gem dependencies:
+
+* Hpricot >= 0.6
+* ActiveSupport >= 2.1.0
+
+== INSTALL:
+
+* sudo gem install yahoo-geoplanet
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Mattt Thompson
+
+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.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,75 @@
+require 'yahoo-geoplanet/version'
+
+AUTHOR = "Mattt Thompson"
+EMAIL = "mail@matttthompson.com"
+DESCRIPTION = "yahoo-geoplanet is a wrapper to the Y! GeoPlanet REST APIs"
+GEM_NAME = 'yahoo-geoplanet' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'yahoo-geoplanet' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+ ['hpricot',        '>= 0.6'],
+ ['activesupport',  '>= 2.1.0'],
+ ['flexmock',       '>= 0.8.2']
+] # An array of rubygem dependencies [name, version]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "mattt"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = Yahoo::GeoPlanet::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'yahoo-geoplanet documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = EXTRA_DEPENDENCIES
+
+    #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+$hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/rest.rb

@@ -0,0 +1,49 @@
+# Ported from John Nunemaker's Scrobbler Gem (http://scrobbler.rubyforge.org/)
+
+require 'net/https'
+
+module REST
+	class Connection
+		def initialize(base_url, args = {})
+			@base_url = base_url
+			@username = args['username']
+			@password = args['password']
+			@app_id   = args['app_id']
+		end
+
+		def get(resource, args = nil)
+			request(resource, "get", args)
+		end
+
+		def post(resource, args = nil)
+			request(resource, "post", args)
+		end
+
+		def request(resource, method = "get", args = {})
+			url = URI.join(@base_url, resource)
+
+			if args = args.update('appid' => @app_id)
+				# TODO: What about keys without value?
+				url.query = args.map { |k,v| "%s=%s" % [URI.encode(k.to_s), URI.encode(v.to_s)] }.join("&")
+			end
+						
+			case method
+			when "get"
+				req = Net::HTTP::Get.new(url.request_uri)
+			when "post"
+				req = Net::HTTP::Post.new(url.request_uri)
+			end
+
+			if @username and @password
+				req.basic_auth(@username, @password)
+			end
+
+			http = Net::HTTP.new(url.host, url.port)
+			http.use_ssl = (url.port == 443)
+
+			res = http.start() { |conn| conn.request(req) }
+			puts url
+			res.body
+		end
+	end
+end

data/lib/yahoo-geoplanet.rb

@@ -0,0 +1,24 @@
+%w{rubygems cgi hpricot activesupport}.each { |x| require x }
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rest'
+require 'yahoo-geoplanet/base'
+require 'yahoo-geoplanet/version'
+
+require 'yahoo-geoplanet/place'
+
+module Yahoo
+  module GeoPlanet
+    LOCALE      = "us"
+    API_VERSION = "v1"
+    API_URL     = "http://where.yahooapis.com/v1/"
+    
+    class << self
+      def app_id=(_id)
+        Yahoo::GeoPlanet::Base::connection = REST::Connection.new(API_URL, 'app_id' => _id)
+      end
+    end
+  end
+end

data/lib/yahoo-geoplanet/base.rb

@@ -0,0 +1,48 @@
+module Yahoo
+  module GeoPlanet
+    class Base
+      class << self
+        cattr_accessor  :connection
+        
+        def name_with_demodulization
+          self.name_without_demodulization.demodulize        
+        end
+        
+        alias_method_chain :name, :demodulization
+
+        def fetch_and_parse(resource, options = {})      
+          raise YahooWebServiceError, "No App ID specified" if connection.nil?    
+          return Hpricot::XML(connection.get(resource, options))
+        end
+        
+        def api_path(resource, id, collection, *args)
+          parameters = [resource, id, collection, *args].compact
+          return parameters.collect!{|param| CGI::escape(param.to_s).downcase}.join('/')
+        end
+      end
+            
+      def initialize(xml)
+        raise ArgumentError unless xml.kind_of?(Hpricot)
+      end
+      
+      def initialize_with_polymorphism(arg)
+        case arg
+        when Integer
+          initialize_without_polymorphism(query_by_id(arg))
+        when Hpricot
+          initialize_without_polymorphism(arg)
+        end
+      end
+     
+      alias_method_chain :initialize, :polymorphism
+      
+    protected
+      def query_by_id(id)
+        xml = self.class.fetch_and_parse(self.class.api_path(self.class.name, id, nil))
+        return xml.at(self.class.name.downcase)
+      end
+    end
+  
+    class YahooWebServiceError < StandardError; end
+  end
+end

data/lib/yahoo-geoplanet/place.rb

@@ -0,0 +1,73 @@
+module Yahoo
+  module GeoPlanet
+    class Place < Base
+      attr_reader  :woe_id, :type, :name
+      attr_reader  :latitude, :longitude, :bounding_box
+      alias_method :lat, :latitude 
+      alias_method :lon, :longitude
+            
+      def initialize_without_polymorphism(xml)
+        super
+        
+        @woe_id = xml.at("woeid").inner_text
+        @type   = xml.at("placeTypeName").inner_text
+        @name   = xml.at("name").inner_text
+        
+        ["admin1", "admin2", "admin3", "locality1", "locality2", "postal"].each do |optional|
+          begin
+            element = xml.at(optional)          
+            type  = element.attributes["type"].downcase.gsub(/\s+/, '_')
+            value = element.inner_text
+          
+            self.class.class_eval %(attr_accessor :#{type})
+            self.instance_variable_set("@#{type}", value)
+          rescue
+            next
+          end
+        end
+        
+        element = xml.at("centroid")
+        @latitude  = element.at("latitude").inner_text.to_f
+        @longitude = element.at("longitude").inner_text.to_f
+      
+        element = xml.at("boundingBox")
+        @bounding_box = ["northEast","southWest"].collect do |corner|
+          corner = element.at(corner)
+          [corner.at("latitude"), corner.at("longitude")].collect{|e| e.inner_text.to_f}
+        end
+      end
+      
+      # Association Collections
+      ["parent", "ancestors", "belongtos", "neighbors", "siblings", "children"].each do |association|
+        define_method(association.to_sym) do
+          xml = self.class.fetch_and_parse(self.class.api_path(self.class.name, @woe_id, association), :select => :long)
+          value = xml.search(self.class.name.downcase).collect{|elem| self.class.new(elem)}
+          return association.singularize == association ? value.first : value
+        end
+      end
+      
+      def to_s
+        self.name
+      end
+      
+      def to_i
+        self.woe_id.to_i
+      end
+      
+      class << self
+        def search(query, options = {'count' => '20'})
+          query = URI.encode(query.gsub(/\s+/, '+'))
+          if options[:type]
+            type = options.delete(:type).gsub(/\s+/, '+')
+            term = "$and(.q('#{query}'),.type('#{type}'));"
+          else
+            term = ".q('#{query}');"
+          end
+          term << options.collect{|k,v| "%s=%s" % [URI.encode(k.to_s), URI.encode(v.to_s)]}.join(";")
+          xml = fetch_and_parse('places' + term)
+          return xml.search(self.name.downcase).collect{|elem| self.new(elem)}
+        end
+      end
+    end
+  end
+end

data/lib/yahoo-geoplanet/version.rb

@@ -0,0 +1,11 @@
+module Yahoo
+  module GeoPlanet
+    module VERSION #:nodoc:
+      MAJOR = 0
+      MINOR = 1
+      TINY  = 0
+
+      STRING = [MAJOR, MINOR, TINY].join('.')
+    end
+  end
+end