carlosparamio-geoplanet 0.1.0

data/README.rdoc

@@ -0,0 +1,97 @@
+= 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.app_id = [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.app_id = [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)
+
+== 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
+
+== INSTALL:
+
+* gem install carlosparamiogeoplanet --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.

data/geoplanet.gemspec

@@ -0,0 +1,27 @@
+Gem::Specification.new do |s|
+  s.name     = "geoplanet"
+  s.version  = "0.1.0"
+  s.date     = "2009-02-25"
+  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 = true
+  s.rdoc_options = ["--main", "README.rdoc"]
+end

data/lib/geoplanet/base.rb

@@ -0,0 +1,43 @@
+module GeoPlanet
+  class Base
+    class << self
+      def build_url(resource_name, 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 if query_params[:appid].nil? || resource_name == 'places' && filters[:q].nil? # required
+
+        q = ".q('#{filters[:q]}')" if filters[:q]
+        type = ".type('#{filters[:type].is_a?(Array) ? filters[:type].to_a.join(',') : 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_name}#{query_string}"
+      end
+
+      protected
+      def extract_filters(options)
+        filters = %w(q type)
+        Hash[*(options.select{|k,v| filters.include?(k.to_s)}).flatten(1)]
+      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,102 @@
+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
+
+    def initialize(woe_or_attrs)
+      attrs =
+        case woe_or_attrs
+        when Integer
+          url = self.class.build_url("place/#{woe_or_attrs}", :format => "json")
+          puts "Yahoo GeoPlanet: GET #{url}"
+          JSON.parse(RestClient.get(url))['place'] rescue nil
+        when Hash
+          woe_or_attrs
+        else
+          raise ArgumentError
+        end
+
+      @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 = {})
+          url = self.class.build_url("place/\#{self.woeid}/#{association}", options.merge(:format => "json"))
+          puts "Yahoo GeoPlanet: GET \#{url}"
+          results = JSON.parse RestClient.get(url)
+          results['places']['place'].map{|r| Place.new(r)} rescue nil
+        rescue
+          raise GeoPlanet::Error
+        end
+      RUBY
+    end
+    
+    def to_s
+      self.name
+    end
+    
+    def to_i
+      self.woeid.to_i
+    end
+    
+    class << self
+      def search(text, options = {})
+        url = build_url('places', options.merge(:q => text, :format => "json"))
+        puts "Yahoo GeoPlanet: GET #{url}"
+        results = JSON.parse RestClient.get(url)
+        results['places']['place'].map{|r| Place.new(r)} rescue nil
+      rescue
+        raise GeoPlanet::Error
+      end
+    end
+  end
+end

data/lib/geoplanet/version.rb

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

data/lib/geoplanet.rb

@@ -0,0 +1,16 @@
+%w{rubygems rest_client json}.each { |x| require x }
+
+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
+  end
+
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: carlosparamio-geoplanet
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Carlos Paramio
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-25 00:00:00 -08: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/
+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.2.0
+signing_key: 
+specification_version: 2
+summary: A Ruby wrapper for the Yahoo! GeoPlanet API.
+test_files: []
+