geoplanet 0.2.2

data/README.rdoc

@@ -0,0 +1,132 @@
+= geoplanet
+
+A Ruby wrapper for the Yahoo! GeoPlanet APIs. It's inspired on Mattt Thompson's yahoo-geoplanet gem,
+but this version supports better usage of matrix and query parameters, uses JSON for API communication to minimize bandwidth usage, supports both short & long versions of a place, and supports multiple languages.
+
+== Usage
+
+=== Searching for a Location:
+
+  require 'geoplanet'
+  GeoPlanet.appid = [Your App ID Here]
+  
+  # Search for places that matches "Springfield" (the API returns 1 by default)
+  GeoPlanet::Place.search("Springfield")
+  
+  # Search for *all* places that matches "Springfield"
+  GeoPlanet::Place.search("Springfield", :count => 0)
+  
+  # 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 'geoplanet'
+  GeoPlanet.appid = [Your App ID Here]
+  
+  a = GeoPlanet::Place.new(752067) # WoE ID for Algeciras
+  
+  # Everything you get back from the API you have direct access to
+  # through the Place object. For example:
+  
+  a.version          # "long"
+  a.placetype        # "Town"
+  a.placetype_code   # 7
+  a.admin1           # "Andalucia"
+  a.admin1_code      # "ES-AN"
+  a.admin1_placetype # "Autonomous Community"
+  a.admin2           # "Cadiz"
+  a.admin2_code      # ""
+  a.admin2_placetype # "Province"
+  a.latitude         # 36.127602
+                     # Latitude and Longitude are values at Centroid
+  a.bounding_box     # [[36.109779, -5.47725], [36.164268, -5.43527]]
+                     # Bounding box are SW / NE coordinates in array
+  
+  # We unlock the true power of GeoPlanet with association collections
+  # Check out this truly amazing stuff:
+  
+  # A list of other towns in the area
+  a.siblings
+  
+  # A complete hierarchy, from country down to municipality
+  a.ancestors
+
+  # Postal Codes at Algeciras
+  a.children(:select => "long", :type => 11)
+  
+  # You can use multiple types on the same query.
+  # e.g. Country and Province for Algeciras
+  a.belongtos(:type => [12, 9])
+  
+  # You can specify the language you want for the results.
+  a.belongtos(:type => 12, :lang => 'es_ES').first.name  # España
+  
+  a = GeoPlanet::Place.new(752067, :lang => :es)
+  a.country  # España
+  
+  # It is also possible to query for any association directly using a WOE ID, without
+  # create a Place object. Append a '_of' suffix to the association name to build the
+  # method name to execute. The first argument is the WOE ID.
+  
+  GeoPlanet::Place.belongtos_of(752067, :type => [12, 9])
+
+=== Debug Mode
+
+If you want to look at the requests that are being executed against the Yahoo GeoPlanet API, you can enable the debug mode. It uses the standard output.
+
+  GeoPlanet.debug = true
+  GeoPlanet::Place.new(752067, :lang => :es)
+  # outputs:
+  # Yahoo GeoPlanet: GET http://where.yahooapis.com/v1/place/752067?appid=[your_appid]&format=json&lang=es
+
+
+== REQUIREMENTS:
+
+To use this library, you must have a valid Yahoo! App ID. 
+You can get one at http://developer.yahoo.com/wsregapp/
+
+Additionally, geoplanet has the following gem dependencies:
+
+* rest-client >= 0.9
+* json >= 1.1.3
+
+Please note that if you have ActiveSupport::JSON defined (either by
+manually having loaded it or when you use geoplanet within a Rails
+application) the json dependency will be ignored and geoplanet uses
+ActiveSupport::JSON instead.
+
+== INSTALL:
+
+  gem install carlosparamio-geoplanet --source http://gems.github.com
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Carlos Paramio
+
+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.
+
+== CONTRIBUTORS:
+
+Nielsomat <http://github.com/Nielsomat> : Usage of ActiveSupport::JSON when available

data/geoplanet.gemspec

@@ -0,0 +1,25 @@
+Gem::Specification.new do |s|
+  s.name     = "geoplanet"
+  s.version  = "0.2.2"
+  s.date     = "2009-04-01"
+  s.summary  = "A Ruby wrapper for the Yahoo! GeoPlanet API."
+  s.email    = "carlosparamio@gmail.com"
+  s.homepage = "http://github.com/carlosparamio/geoplanet/"
+  s.description = "A Ruby wrapper for the Yahoo! GeoPlanet API. It uses JSON format by default to minimize bandwidth usage. See http://developer.yahoo.com/geo/ for more information about the API."
+  s.authors  = ["Carlos Paramio"]
+  
+  s.files    = [
+		"README.rdoc",
+		"geoplanet.gemspec", 
+		"lib/geoplanet.rb",
+		"lib/geoplanet/base.rb",
+		"lib/geoplanet/place.rb",
+		"lib/geoplanet/version.rb"
+	]
+  
+  s.add_dependency("rest-client",   [">= 0.9"])
+  s.add_dependency("json", [">= 1.1.3"])
+  
+  s.has_rdoc = false
+  s.rdoc_options = ["--main", "README.rdoc"]
+end

data/lib/geoplanet.rb

@@ -0,0 +1,29 @@
+%w{rubygems rest_client}.each { |x| require x }
+
+if defined?(ActiveSupport::JSON)
+  JSON = ActiveSupport::JSON
+  module JSON
+    def self.parse(json)
+      decode(json)
+    end
+  end
+else
+  require 'json'
+end
+
+require 'geoplanet/version'
+require 'geoplanet/base'
+require 'geoplanet/place'
+
+module GeoPlanet
+  API_VERSION = "v1"
+  API_URL     = "http://where.yahooapis.com/#{API_VERSION}/"
+    
+  class << self
+    attr_accessor :appid, :debug
+  end
+
+  class BadRequest           < StandardError; end
+  class NotFound             < StandardError; end
+  class NotAcceptable        < StandardError; end
+end

data/lib/geoplanet/base.rb

@@ -0,0 +1,76 @@
+module GeoPlanet
+  class Base
+    class << self
+      def build_url(resource_path, options = {})
+        check_options_for(resource_path, options)
+        
+        filters       = extract_filters(options)
+        matrix_params = extract_matrix_params(options)
+        query_params  = extract_query_params(options)
+
+        query_params[:appid] ||= GeoPlanet.appid # use default appid if not provided
+
+        raise ArgumentError, "appid or q filter missing" if query_params[:appid].nil? || resource_path == 'places' && filters[:q].nil? # required
+
+        q = ".q('#{filters[:q]}')" if filters[:q]
+        type = ".type('#{filters[:type]}')" if filters[:type]
+        
+        query_string = q && type ? "$and(#{q},#{type})" : "#{q}#{type}"
+        
+        matrix_params = ";#{matrix_params.map{|k,v| "#{k}=#{v}"}.join(';')}" if matrix_params.any?
+        query_params  = "?#{query_params.map{|k,v| "#{k}=#{v}"}.join('&')}"  if query_params.any?
+        
+        query_string += "#{matrix_params}#{query_params}"
+        
+        "#{GeoPlanet::API_URL}#{resource_path}#{query_string}"
+      end
+      
+      def get(url)
+        RestClient.get(url)
+      rescue RestClient::RequestFailed
+        raise BadRequest, "appid, q filter or format invalid"
+      rescue RestClient::ResourceNotFound
+        raise NotFound, "woeid or URI invalid"
+      end
+
+      protected
+      def supported_options_for(resource_path)
+        case resource_path
+        when 'places'
+          %w(q type start count lang format callback select appid)
+        when /^place\/\d+\/parent$/, /^place\/\d+\/ancestors$/, /^place\/\d+$/, 'placetype'
+          %w(lang format callback select appid)
+        when /^place\/\d+\/belongtos$/, /^place\/\d+\/children$/, 'placetypes'
+          %w(type start count lang format callback select appid)
+        when /^place\/\d+\/neighbors$/, /^place\/\d+\/siblings$/
+          %w(start count lang format callback select appid)
+        else
+          raise NotFound, "URI invalid"
+        end
+      end
+      
+      def check_options_for(resource_path, options)
+        supported = supported_options_for(resource_path)
+        unless options.keys.all?{|o| supported.include?(o.to_s)}
+          raise ArgumentError, "invalid option(s) for #{resource_path}. Supported are: #{supported.join(', ')}. You used: #{options.keys.join(', ')}"
+        end
+      end
+      
+      def extract_filters(options)
+        filters = %w(q type)
+        options[:type] = options[:type].join(",") if options[:type].is_a?(Array)
+        Hash[*(options.select{|k,v| filters.include?(k.to_s)}).flatten]
+      end
+      
+      def extract_matrix_params(options)
+        matrix_params = %w(start count)
+        Hash[*(options.select{|k,v| matrix_params.include?(k.to_s)}).flatten]
+      end
+      
+      def extract_query_params(options)
+        query_params = %w(lang format callback select appid)
+        Hash[*(options.select{|k,v| query_params.include?(k.to_s)}).flatten]
+      end
+    end
+  end
+end

data/lib/geoplanet/place.rb

@@ -0,0 +1,119 @@
+module GeoPlanet
+  class Place < Base
+    attr_reader  :version # short or long
+    # short
+    attr_reader  :woeid, :placetype, :placetype_code, :name, :uri, :lang
+    # long
+    attr_reader  :country, :country_code, :postal
+    attr_reader  :latitude, :longitude, :bounding_box
+    attr_reader  :admin1, :admin1_code, :admin1_placetype
+    attr_reader  :admin2, :admin2_code, :admin2_placetype
+    attr_reader  :admin3, :admin3_code, :admin3_placetype
+    attr_reader  :locality1, :locality1_placetype
+    attr_reader  :locality2, :locality2_placetype
+    alias_method :lat, :latitude 
+    alias_method :lon, :longitude
+
+    # Class methods
+    def self.search(text, options = {})
+      text = URI.encode(text)
+      url = build_url('places', options.merge(:q => text, :format => 'json'))
+      puts "Yahoo GeoPlanet: GET #{url}" if GeoPlanet.debug
+      get_then_parse(url)
+    end
+    
+    def self.get_then_parse(url)
+      results = JSON.parse get(url)
+      return results['places']['place'].map{|attrs| Place.new attrs} if results['places']
+      return Place.new(results['place']) if results['place']
+      nil
+    rescue
+      nil
+    end
+
+    %w(parent ancestors belongtos neighbors siblings children).each do |association|
+      self.instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{association}_of(woeid, options = {})
+          url = build_url("place/\#{woeid}/#{association}", options.merge(:format => "json"))
+          puts "Yahoo GeoPlanet: GET \#{url}" if GeoPlanet.debug
+          get_then_parse(url)
+        end
+      RUBY
+    end
+    
+    # Instance methods
+    def initialize(woe_or_attrs, options = {})
+      case woe_or_attrs
+      when Integer then initialize_with_woe(woe_or_attrs, options)
+      when Hash    then initialize_with_attrs(woe_or_attrs)
+      else
+        raise ArgumentError
+      end
+    end
+    
+    def initialize_with_woe(woe, options = {})
+      url = self.class.build_url("place/#{woe}", options.merge(:format => "json"))
+      puts "Yahoo GeoPlanet: GET #{url}" if GeoPlanet.debug
+      initialize_with_attrs JSON.parse(Place.get(url))['place']
+    end
+    
+    
+    def initialize_with_attrs(attrs)
+      @version = attrs['centroid'] ? 'long' : 'short'
+
+      # short
+      @woeid          = attrs['woeid']
+      @placetype      = attrs['placeTypeName']
+      @placetype_code = attrs['placeTypeName attrs']['code']
+      @name           = attrs['name']
+      @uri            = attrs['uri']
+      @lang           = attrs['lang']
+
+      if version == 'long'
+        # long
+        @latitude            = attrs['centroid']['latitude']
+        @longitude           = attrs['centroid']['longitude']
+        @bounding_box        = [ [ attrs['boundingBox']['southWest']['latitude'],
+                                   attrs['boundingBox']['southWest']['longitude'] ],
+                                 [ attrs['boundingBox']['northEast']['latitude'],
+                                   attrs['boundingBox']['northEast']['longitude'] ],
+                               ]
+        @country             = attrs['country']
+        @country_code        = attrs['country attrs']['code']   rescue nil
+        @postal              = attrs['postal']
+        @admin1              = attrs['admin1']
+        @admin1_code         = attrs['admin1 attrs']['code']    rescue nil
+        @admin1_placetype    = attrs['admin1 attrs']['type']    rescue nil
+        @admin2              = attrs['admin2']
+        @admin2_code         = attrs['admin2 attrs']['code']    rescue nil
+        @admin2_placetype    = attrs['admin2 attrs']['type']    rescue nil
+        @admin3              = attrs['admin3']
+        @admin3_code         = attrs['admin3 attrs']['code']    rescue nil
+        @admin3_placetype    = attrs['admin3 attrs']['type']    rescue nil
+        @locality1           = attrs['locality1']
+        @locality1_placetype = attrs['locality1 attrs']['type'] rescue nil
+        @locality2           = attrs['locality2']
+        @locality2_placetype = attrs['locality2 attrs']['type'] rescue nil
+      end
+      self
+    end
+
+    # Association Collections
+    %w(parent ancestors belongtos neighbors siblings children).each do |association|
+      self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{association}(options = {})
+          Place.send("#{association}_of", self.woeid, options)
+        end
+      RUBY
+    end
+    
+    def to_s
+      self.name
+    end
+    
+    def to_i
+      self.woeid.to_i
+    end
+    
+  end
+end

data/lib/geoplanet/version.rb

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

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: geoplanet
+version: !ruby/object:Gem::Version 
+  version: 0.2.2
+platform: ruby
+authors: 
+- Carlos Paramio
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-01 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.9"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.3
+    version: 
+description: A Ruby wrapper for the Yahoo! GeoPlanet API. It uses JSON format by default to minimize bandwidth usage. See http://developer.yahoo.com/geo/ for more information about the API.
+email: carlosparamio@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- geoplanet.gemspec
+- lib/geoplanet.rb
+- lib/geoplanet/base.rb
+- lib/geoplanet/place.rb
+- lib/geoplanet/version.rb
+has_rdoc: true
+homepage: http://github.com/carlosparamio/geoplanet/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+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.3.5
+signing_key: 
+specification_version: 3
+summary: A Ruby wrapper for the Yahoo! GeoPlanet API.
+test_files: []
+