first commit

README

@@ -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)
+  Place.search("Springfield")
+
+  # Search for *all* places that matches "Springfield"
+  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'
+  include GeoPlanet
+  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:
+
+  cmu.version          # "long"
+  cmu.placetype        # "Point of Interest"
+  cmu.placetype_code   # 20
+  cmu.admin1           # "Pennsylvania"
+	cmu.admin1_code      # "US-PA"
+	cmu.admin1_placetype # "State"
+  cmu.latitude         # 40.444
+                       # Latitude and Longitude are values at Centroid
+  cmu.bounding_box     # [[40.44445, -79.943314], [40.44355, -79.944511]]
+                       # Bounding box are NW / SE coordinates in array
+  cmu.admin2           # "Allegheny"
+	cmu.admin2_placetype # "County"
+
+  # We unlock the true power of GeoPlanet with association collections
+  # Check out this truly amazing stuff:
+
+  # The containing GeoPlanet entity for CMU
+  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, 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.

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",
+		"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"]
+end

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

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

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

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