mattt-yahoo-geoplanet 0.1.0

data/README

@@ -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/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

data/yahoo-geoplanet.gemspec

@@ -0,0 +1,27 @@
+Gem::Specification.new do |s|
+  s.name     = "yahoo-geoplanet"
+  s.version  = "0.1.0"
+  s.date     = "2008-11-13"
+  s.summary  = "A Ruby wrapper for the Yahoo! GeoPlanet API."
+  s.email    = "mail@matttthompson.com"
+  s.homepage = "http://github.com/mattt/yahoo-geoplanet/"
+  s.description = "A Ruby wrapper for the Yahoo! GeoPlanet API.
+                   See http://developer.yahoo.com/geo/ for more information about the API."
+  s.authors  = ["Mattt Thompson"]
+  
+  s.files    = [
+		"README", 
+		"yahoo-geoplanet.gemspec", 
+		"lib/yahoo-geoplanet.rb",
+		"lib/rest.rb",
+		"lib/yahoo-geoplanet/base.rb",
+		"lib/yahoo-geoplanet/place.rb",
+		"lib/yahoo-geoplanet/version.rb"
+	]
+  
+  s.add_dependency("hpricot",       ["> 0.6"])
+  s.add_dependency("activesupport", ["> 2.1.0"])
+  
+  s.has_rdoc = false
+  s.rdoc_options = ["--main", "README"]
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: mattt-yahoo-geoplanet
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mattt Thompson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-13 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: "0.6"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 2.1.0
+    version: 
+description: A Ruby wrapper for the Yahoo! GeoPlanet API. See http://developer.yahoo.com/geo/ for more information about the API.
+email: mail@matttthompson.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- yahoo-geoplanet.gemspec
+- lib/yahoo-geoplanet.rb
+- lib/rest.rb
+- lib/yahoo-geoplanet/base.rb
+- lib/yahoo-geoplanet/place.rb
+- lib/yahoo-geoplanet/version.rb
+has_rdoc: false
+homepage: http://github.com/mattt/yahoo-geoplanet/
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+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: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A Ruby wrapper for the Yahoo! GeoPlanet API.
+test_files: []
+