placemaker 0.0.2

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+
+gem 'curb'
+gem 'nokogiri'
+
+group :test do
+  gem 'rspec', '1.3.0'
+end

data/Gemfile.lock

@@ -0,0 +1,14 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    curb (0.7.9)
+    nokogiri (1.4.4)
+    rspec (1.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  curb
+  nokogiri
+  rspec (= 1.3.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Justin S. Leitgeb
+
+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/README.rdoc

@@ -0,0 +1,76 @@
+= Description
+
+Yahoo! Placemaker is a freely available geoparsing Web service. It helps developers make their applications location-aware by 
+identifying places in unstructured and atomic content - feeds, web pages, news, status updates - and returning geographic metadata 
+for geographic indexing and markup.
+
+This library is a Ruby interface for accessing the {Yahoo PlaceMaker API}[http://developer.yahoo.com/geo/placemaker/].
+
+= Installation
+
+Assuming that you've set up your ruby environment to pull gems from GitHub 
+(see {the GitHub instructions if you haven't yet done this}[http://gems.github.com]), 
+install placemaker with the following command:
+
+  sudo gem install jsl-placemaker
+
+= Usage
+
+The following is an example of using the Placemaker gem to read places in a standard feed.  You'll have to get a Yahoo App ID first if you haven't 
+already done so.
+
+  require 'placemaker'
+  p = Placemaker::Client.new(:appid => YOUR_APP_ID, :document_url => 'http://feeds.feedburner.com/wooster', :document_type => 'text/xml')
+  p.fetch!
+
+This will make a call to the Placemaker service and populate the Placemaker::Client object with data about the places in the content that you
+sent to Yahoo.  The information that you'll be interested in may be divided into "documents" and "meta-data."
+
+You can also use placemaker with a document that you upload.  Use +document_content+ in the configuration options instead of +document_url+, and 
+make sure to set the appropriate value for +document_type+.  Acceptable mime types are text/plain, text/html, text/xml, text/rss, application/xml, 
+and application/rss+xml.  The following is an example of using jsl-placemaker to encode content that you upload:
+
+  p = Placemaker::Client.new(:appid => YOUR_APP_ID, :document_content => 'railsconf was in las vegas this year', :document_type => 'text/plain')
+  p.fetch!
+
+Afterwards, you have access to the same Placemaker::Client methods as if you had pointed placemaker to a +document_url+.
+
+== Documents
+
+Once you've run the +fetch!+ method on the Placemaker::Client, you may invoke the method +documents+ which will return a set of Placemaker::Document
+objects corresponding to each of the entries in the feed given to the placemaker service.  For example, if you gave a +document_url+ pointing
+to a feed containing 15 entries, there will be 15 documents in the resulting client object.
+
+The following are methods that you may invoke on each of the Placemaker::Document objects to find out more about the place information that
+Yahoo was able to glean from the input document:
+
+* place_details - Returns a Placemaker::Location object that is a container for one named place mentioned in the document
+* administrative_scope - Returns a Placemaker::Location object that is a container for the smallest administrative place that best describes the document 
+* geographic_scope - Returns a Placemaker::Location object that is a container for the smallest place that best describes the document 
+* extents - Returns a Placemaker::Extents object that is a container for the the map extents covering the places mentioned in the document
+
+Below is a summary of the methods that these objects respond to.  You may wish to browse the Placemaker rdoc files for these classes to see 
+for more details.
+  
+=== Placemaker::Location
+
+Placemaker::Location objects contain a woe_id, name, location_type and centroid.
+
+* woe_id - permanent identifier for the place
+* name - fully qualified name for the place
+* location_type - type name for the place
+* centroid - centroid for the place, responds to +lat+ and +lng+
+
+=== Placemaker::Extents
+
+Placemaker::Extents are bounding boxes for an area of interest.  They respond to methods for +center+, +south_west+ and +north_east+.  In
+all of these cases, they return a Placemaker::Coordinates object responding to +lat+ and +lng+.
+
+== Meta-data
+
+The request to the Yahoo place coding service returns information about the request.  You may invoke the methods +processing_time+, 
++version+, and +document_length+ to find out more about the request.
+
+= Author
+
+Justin S. Leitgeb, justin@phq.org

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'spec'
+
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+
+require 'lib/placemaker'
+
+desc 'Test the plugin.'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts  = ["--format", "progress", "--colour"]
+  t.libs << 'lib'
+  t.verbose = true
+end
+
+desc "Run all the tests"
+task :default => :spec
+
+desc 'Generate documentation'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Placemaker'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/placemaker/**/*.rb')
+end
+

data/lib/placemaker/client.rb

@@ -0,0 +1,75 @@
+require 'placemaker/xml_parser'
+
+module Placemaker
+  
+  # Main interface to the Placemaker API.
+  class Client
+    POST_FIELDS =  %w[ appid document_content document_url document_type document_title 
+      auto_disambiguate focus_woe_id input_language output_type ].map{|f| f.to_sym}
+
+    def initialize(options = {})
+      @options = options
+      @options[:appid] ||= ENV['PLACEMAKER_APPID']
+      
+      @xml_parser = Placemaker::XmlParser.new('NODOC')
+      
+      verify_content_set
+      verify_document_type_set
+    end
+
+    # Fetches the place information for input parameters from the Yahoo Placemaker service
+    def fetch!
+      fields = POST_FIELDS.reject{|f| @options[f].nil? }.map do |f|
+        # Change ruby-form fields to url type, e.g., document_content => documentContent
+        cgi_param = f.to_s.gsub(/\_(.)/) {|s| s.upcase}.gsub('_', '').sub(/url/i, 'URL')
+        Curl::PostField.content(cgi_param, @options[f])
+      end
+
+      res         = Curl::Easy.http_post('http://wherein.yahooapis.com/v1/document', *fields)
+      @xml_parser = Placemaker::XmlParser.new(res.body_str)
+    end
+
+    # Returns a collection of Placemaker::Document items as containers for content location information
+    def documents
+      @xml_parser.documents
+    end
+    
+    # time in seconds to process the document
+    def processing_time
+      @xml_parser.processing_time
+    end
+    
+    # version of the software used to process the document 
+    def version
+      @xml_parser.version
+    end
+
+    # length in bytes of the document
+    def document_length
+      @xml_parser.document_length
+    end
+    
+    # Create convenience methods to access post fields from the @options hash, mostly for testing.
+    POST_FIELDS.each do |f|
+      define_method(f) do  # def appid
+        @options[f]        #   @options[:appid]
+      end                  # end
+    end
+
+    private
+
+    def verify_document_type_set
+      valid_types = %w[
+        text/plain
+        text/html text/xml text/rss 
+        application/xml application/rss+xml
+      ]
+
+      raise ArgumentError, "Document type must be in #{valid_types.join(', ')}" unless valid_types.include?(@options[:document_type]) 
+    end
+
+    def verify_content_set 
+      raise ArgumentError, "Either document_url or document_content must be set" if (@options[:document_content].nil? && @options[:document_url].nil?)
+    end
+  end
+end

data/lib/placemaker/coordinates.rb

@@ -0,0 +1,13 @@
+module Placemaker
+  class Coordinates
+    include Placemaker::XmlHelper
+    
+    def lat
+      @nodeset.search('.//xmlns:latitude', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text.to_f
+    end
+    
+    def lng
+      @nodeset.search('.//xmlns:longitude', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text.to_f
+    end
+  end
+end

data/lib/placemaker/document.rb

@@ -0,0 +1,44 @@
+require 'placemaker/xml_helper'
+require 'placemaker/place_details'
+require 'placemaker/location'
+require 'placemaker/extents'
+require 'placemaker/reference'
+
+module Placemaker
+  
+  class Document
+    include Placemaker::XmlHelper
+    
+    # Returns a Placemaker::Location object that is a container for one named place mentioned in the document 
+    def place_details
+      @nodeset.search('.//xmlns:placeDetails', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').map do |p|
+        Placemaker::PlaceDetails.new(p)
+      end
+    end
+    
+    # Returns a Placemaker::Location object that is a container for the smallest administrative place that best describes the document 
+    def administrative_scope
+      as = @nodeset.search('.//xmlns:administrativeScope', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').first
+      Placemaker::Location.new(as) unless as.nil?
+    end
+    
+    # Returns a Placemaker::Location object that is a container for the smallest place that best describes the document 
+    def geographic_scope
+      gs = @nodeset.search('.//xmlns:geographicScope', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').first
+      Placemaker::Location.new(gs) unless gs.nil?
+    end
+    
+    # Returns a Placemaker::Extents object that is a container for the the map extents covering the places mentioned in the document 
+    def extents
+      extents = @nodeset.search('.//xmlns:extents', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').first
+      Placemaker::Extents.new(extents) unless extents.nil?
+    end
+
+    def reference_list
+      @nodeset.search('.//xmlns:referenceList[1]/xmlns:reference', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').map do |reference|
+        Placemaker::Reference.new(reference)
+      end
+    end
+  end
+  
+end

data/lib/placemaker/extents.rb

@@ -0,0 +1,25 @@
+require 'placemaker/coordinates'
+
+module Placemaker
+  
+  # container for the the map extents covering the places mentioned in the document 
+  class Extents
+    include Placemaker::XmlHelper
+            
+    # coordinates of center (WGS84)
+    def center
+      Placemaker::Coordinates.new(@nodeset.search('.//xmlns:center', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema'))
+    end
+    
+    # coordinates of southwest corner of bounding box (WGS84)
+    def south_west
+      Placemaker::Coordinates.new(@nodeset.search('.//xmlns:southWest', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema'))
+    end
+    
+    # coordinates of northeast corner of bounding box (WGS84)
+    def north_east
+      Placemaker::Coordinates.new(@nodeset.search('.//xmlns:northEast', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema'))
+    end
+  end
+
+end

data/lib/placemaker/location.rb

@@ -0,0 +1,35 @@
+require 'placemaker/coordinates'
+
+module Placemaker
+
+  # Parses and contains data for +place+, +administrative scope+ and +geographic scope+ elements.
+  class Location
+    include Placemaker::XmlHelper
+    
+    # permanent identifier for the place
+    def woe_id
+      nested_node('woeId').to_i
+    end
+
+    # fully qualified name for the place
+    def name
+      nested_node('name')
+    end
+    
+    # place type name for the place
+    def location_type
+      nested_node('type')
+    end
+    
+    # centroid for the place
+    def centroid
+      Placemaker::Coordinates.new(@nodeset.search('.//xmlns:centroid', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema'))
+    end
+
+    private    
+    
+    def nested_node(name)
+      @nodeset.search(".//xmlns:#{name}", 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text
+    end    
+  end
+end

data/lib/placemaker/place_details.rb

@@ -0,0 +1,28 @@
+module Placemaker
+
+  # container for one named place mentioned in the document
+  class PlaceDetails
+    include Placemaker::XmlHelper
+    
+    # Returns a Placemaker::Location object as a container for place information.
+    def place
+      Placemaker::Location.new(@nodeset.search('.//xmlns:place', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema'))
+    end
+    
+    # type of match (0=text or text and coordinates, 1=coordinates only) 
+    def match_type
+      nested_node('matchType').to_i
+    end
+
+    # relative weight of the place within the document (range 1-100) 
+    def weight
+      nested_node('weight').to_i
+    end
+
+    # confidence that the document mentions the place (range 1-10) 
+    def confidence
+      nested_node('confidence').to_i
+    end    
+
+  end
+end

data/lib/placemaker/reference.rb

@@ -0,0 +1,34 @@
+module Placemaker
+
+  class Reference
+    include Placemaker::XmlHelper
+
+    def woe_ids
+      nested_node('woeIds')
+    end
+
+    def start
+      nested_node('start')
+    end
+
+    def end
+      nested_node('end')
+    end
+
+    def is_plain_text_marker
+      nested_node('isPlainTextMarker')
+    end
+
+    def text
+      nested_node('text')
+    end
+
+    def type
+      nested_node('type')
+    end
+
+    def xpath
+      nested_node('xpath')
+    end
+  end
+end

data/lib/placemaker/xml_helper.rb

@@ -0,0 +1,14 @@
+module Placemaker
+  module XmlHelper
+    def initialize(nodeset)
+      @nodeset = nodeset
+    end
+    
+    # Returns the inner text of a node with the given name under the current @nodeset 
+    def nested_node(name)
+      @nodeset.search(".//xmlns:#{name}", 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text
+    end
+    
+    private :nested_node
+  end
+end

data/lib/placemaker/xml_parser.rb

@@ -0,0 +1,33 @@
+require 'placemaker/document'
+
+module Placemaker
+  class XmlParser
+    def initialize(xml_body)
+      @body = xml_body
+      @xml = Nokogiri::XML(xml_body)
+    end    
+    
+    # time in seconds to process the document
+    def processing_time
+      @xml.xpath('.//xmlns:processingTime', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text.to_f
+    end
+    
+    # version of the software used to process the document 
+    def version
+      @xml.xpath('.//xmlns:version', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text.strip
+    end
+    
+    # length in bytes of the document
+    def document_length
+      @xml.xpath('.//xmlns:documentLength', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').inner_text.to_i  
+    end
+    
+    #  Returns a set of Placemaker::Document objects as containers for content location information
+    def documents
+      @xml.xpath('//xmlns:document', 'xmlns' => 'http://wherein.yahooapis.com/v1/schema').map do |d|
+        Placemaker::Document.new(d)
+      end
+    end
+    
+  end
+end

data/lib/placemaker.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'curb'
+require 'nokogiri'
+require 'cgi'
+
+dir = File.dirname(__FILE__)
+$LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
+
+require 'placemaker/client'