metacarta-geoparser 1.0.0

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2006 Eric Hodel, The Robot Co-op.  All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the names of the authors nor the names of their contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Manifest.txt

@@ -0,0 +1,6 @@
+LICENSE
+Manifest.txt
+README
+Rakefile
+lib/metacarta_geoparser.rb
+test/test_metacarta_geoparser.rb

data/README

@@ -0,0 +1,41 @@
+= metacarta-geoparser
+
+Rubyforge Project:
+
+http://rubyforge.org/projects/rctools
+
+Documentation:
+
+http://dev.robotcoop.com/Libraries/metacarta-geoparser
+
+== About
+
+metacarta-geoparser implements MetaCarta's GeoParser API:
+
+http://labs.metacarta.com/GeoParser/documentation.html
+
+== Installing metacarta-geoparser
+
+Just install the gem:
+
+  $ sudo gem install metacarta-geoparser
+
+== Using metacarta-geoparser
+
+You can use either +locate+ or +locations+ to locate places:
+
++locate+ returns just one location, but includes a confidence estimate:
+
+  gp = MetaCartaGeoParser.new
+  location = gp.locate 'baghdad'
+  p location.coordinates
+  p location.confidence
+
++locations+ returns a list of locations and a viewbox surrounding all of them.
+
+  gp = MetaCartaGeoParser.new
+  locations, viewbox = gp.locations 'seattle'
+  p locations.length
+  p location.first.coordinates
+  p viewbox
+

data/Rakefile

@@ -0,0 +1,69 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+$VERBOSE = nil
+
+spec = Gem::Specification.new do |s|
+  s.name = 'metacarta-geoparser'
+  s.version = '1.0.0'
+  s.summary = 'MetaCarta GeoParser API Library'
+  s.description = 'Map addresses to latitude and longitude with MetaCarta\'s
+GeoParser API.'
+  s.author = 'Eric Hodel'
+  s.email = 'eric@robotcoop.com'
+
+  s.has_rdoc = true
+  s.files = File.read('Manifest.txt').split($/)
+  s.require_path = 'lib'
+  
+  s.add_dependency 'rc-rest', '>= 1.0.0'
+end
+
+desc 'Run tests'
+task :default => [ :test ]
+
+Rake::TestTask.new('test') do |t|
+  t.libs << '../rc-rest/lib'
+  t.pattern = 'test/test_*.rb'
+  t.verbose = true
+end
+
+desc 'Update Manifest.txt'
+task :update_manifest do
+  sh "find . -type f | sed -e 's%./%%' | egrep -v 'svn|swp|~' | egrep -v '^(doc|pkg)/' | sort > Manifest.txt"
+end
+
+desc 'Generate RDoc'
+Rake::RDocTask.new :rdoc do |rd|
+  rd.rdoc_dir = 'doc'
+  rd.rdoc_files.add 'lib', 'README', 'LICENSE'
+  rd.main = 'README'
+  rd.options << '-d' if `which dot` =~ /\/dot/
+  rd.options << '-t MetaCarta GeoParser'
+end
+
+desc 'Generate RDoc for dev.robotcoop.com'
+Rake::RDocTask.new :dev_rdoc do |rd|
+  rd.rdoc_dir = '../../../www/trunk/dev/html/Libraries/google-geocode'
+  rd.rdoc_files.add 'lib', 'README', 'LICENSE'
+  rd.main = 'README'
+  rd.options << '-d' if `which dot` =~ /\/dot/
+  rd.options << '-t MetaCarta GeoParser'
+end
+
+desc 'Build Gem'
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = true
+end
+
+desc 'Clean up'
+task :clean => [ :clobber_rdoc, :clobber_package ]
+
+desc 'Clean up'
+task :clobber => [ :clean ]
+
+# vim: syntax=Ruby
+

data/lib/metacarta_geoparser.rb

@@ -0,0 +1,119 @@
+require 'rc_rest'
+
+##
+# Library for looking up coordinates with MetaCarta's GeoParser API.
+#
+# http://labs.metacarta.com/GeoParser/documentation.html
+
+class MetaCartaGeoParser < RCRest
+
+  class Error < RCRest::Error; end
+
+  ##
+  # Raised if a location couldn't be found.
+
+  class AddressError < Error; end
+
+  Location = Struct.new :name, :type, :population, :hierarchy,
+                        :latitude, :longitude, :confidence, :viewbox
+
+  def initialize # :nodoc:
+    @url = URI.parse 'http://labs.metacarta.com/GeoParser/'
+  end
+
+  ##
+  # Locates +place+ and returns a Location object.
+
+  def locate(place)
+    locations, = get :q => place
+    return locations.first
+  end
+
+  ##
+  # Retrieve all locations matching +place+.
+  #
+  # Returns an Array of Location objects and a pair of coordinates that will
+  # surround them.
+
+  def locations(place)
+    get :loc => place
+  end
+
+  def check_error(xml) # :nodoc:
+    raise AddressError, 'bad location' unless xml.elements['Locations/Location']
+  end
+
+  def make_url(params) # :nodoc:
+    params[:output] = 'locations'
+
+    super params
+  end
+
+  def parse_response(xml) # :nodoc:
+    locations = []
+
+    xml.elements['/Locations'].each do |l|
+      next if REXML::Text === l or l.name == 'ViewBox'
+      location = Location.new
+
+      location.viewbox = viewbox_coords l.elements['ViewBox/gml:Box/gml:coordinates']
+
+      location.name = l.attributes['Name']
+      location.type = l.attributes['Type']
+      population = l.attributes['Population'].to_i
+      location.population = population > 0 ? population : nil
+      location.hierarchy = l.attributes['Hierarchy']
+
+      coords = l.elements['Centroid/gml:Point/gml:coordinates'].text.split ','
+      location.latitude = coords.first.to_f
+      location.longitude = coords.last.to_f
+
+      confidence = l.elements['Confidence']
+      location.confidence = confidence.text.to_f if confidence
+
+      locations << location
+    end
+
+    query_viewbox = xml.elements['/Locations/ViewBox/gml:Box/gml:coordinates']
+
+    return locations, viewbox_coords(query_viewbox)
+  end
+
+  ##
+  # Turns a element containing a pair of coordinates into a pair of coordinate
+  # Arrays.
+
+  def viewbox_coords(viewbox) # :nodoc:
+    return viewbox.text.split(' ').map do |coords|
+      coords.split(',').map { |c| c.to_f }
+    end
+
+  end
+
+end
+
+##
+# A Location contains the following fields:
+#
+# +name+:: The name of this location
+# +type+:: The type of this location (no clue what it means)
+# +population+:: The number of people who live here or nil
+# +hierarchy+:: The places above this place
+# +latitude+:: Latitude of the location
+# +longitude+:: Longitude of the location
+# +confidence+:: Accuracy confidence (if any)
+# +viewbox+:: Pair of coordinates forming a box around this place
+# 
+# viewbox runs from lower left to upper right.
+
+class MetaCartaGeoParser::Location
+
+  ##
+  # The latitude and longitude for this location.
+
+  def coordinates
+    [latitude, longitude]
+  end
+
+end
+

data/test/test_metacarta_geoparser.rb

@@ -0,0 +1,200 @@
+require 'test/unit'
+require 'rc_rest/uri_stub'
+require 'metacarta_geoparser'
+
+class TestMetaCartaGeoParser < Test::Unit::TestCase
+
+  def setup
+    URI::HTTP.responses = []
+    URI::HTTP.uris = []
+
+    @mg = MetaCartaGeoParser.new
+  end
+
+  def test_locate
+    URI::HTTP.responses << <<-EOF.strip
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<!DOCTYPE Locations SYSTEM "Locations.dtd">
+
+<Locations
+	xmlns:gml="http://www.opengis.net/gml"
+	CreatedBy="MetaCarta GeoParser v3.5.0-labs-alpha"
+	CreatedOn="Thu Jun 15 23:56:50 2006"
+	ConvertedFromBinaryFormat="False"
+	InputByteLength="0">
+	<ViewBox>
+
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>26.238611,37.293889 40.438611,51.493889</gml:coordinates>
+		</gml:Box>
+	</ViewBox>
+<Location
+
+	Name="Baghdad"
+	Type="PPLC"
+	Population="5672516"
+	Hierarchy="Iraq/Baghdad/Baghdad">
+	<ViewBox>
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>26.238611,37.293889 40.438611,51.493889</gml:coordinates>
+		</gml:Box>
+	</ViewBox>
+	<RemainingQuery></RemainingQuery>
+	<Confidence>0.195185</Confidence>	<Centroid><gml:Point><gml:coordinates>44.393889,33.338611</gml:coordinates></gml:Point></Centroid>
+</Location>
+</Locations>
+    EOF
+
+    expected = MetaCartaGeoParser::Location.new 'Baghdad', 'PPLC', 5672516,
+                                                'Iraq/Baghdad/Baghdad',
+                                                44.393889, 33.338611, 0.195185,
+                                                [[26.238611, 37.293889],
+                                                 [40.438611, 51.493889]]
+
+    location = @mg.locate('baghdad')
+    assert_equal expected, location
+    assert_equal [44.393889, 33.338611], location.coordinates
+
+    assert_equal true, URI::HTTP.responses.empty?
+    assert_equal 1, URI::HTTP.uris.length
+    assert_equal 'http://labs.metacarta.com/GeoParser/?output=locations&q=baghdad',
+                 URI::HTTP.uris.first
+  end
+
+  def test_locate_bad_address
+    URI::HTTP.responses << <<-EOF.strip
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<!DOCTYPE Locations SYSTEM "Locations.dtd">
+
+<Locations
+	xmlns:gml="http://www.opengis.net/gml"
+	CreatedBy="MetaCarta GeoParser v3.5.0-labs-alpha"
+	CreatedOn="Sat Jun 17 02:05:42 2006"
+	ConvertedFromBinaryFormat="False"
+	InputByteLength="0">
+	<ViewBox>
+
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>-90.000000,-180.000000 90.000000,180.000000</gml:coordinates>
+		</gml:Box>
+	</ViewBox>
+</Locations>
+    EOF
+
+    @mg.locate('aoeueou')
+  rescue MetaCartaGeoParser::AddressError => e
+    assert_equal 'bad location', e.message
+
+    assert_equal true, URI::HTTP.responses.empty?
+    assert_equal 1, URI::HTTP.uris.length
+    assert_equal 'http://labs.metacarta.com/GeoParser/?output=locations&q=aoeueou',
+                 URI::HTTP.uris.first
+  else
+    flunk 'expected MetaCartaGeoParser::AddressError'
+  end
+
+  def test_locations
+    URI::HTTP.responses << <<-EOF.strip
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<!DOCTYPE Locations SYSTEM "Locations.dtd">
+
+<Locations
+	xmlns:gml="http://www.opengis.net/gml"
+	CreatedBy="MetaCarta GeoParser v3.5.0-labs-alpha"
+	CreatedOn="Sat Jun 17 02:14:05 2006"
+	ConvertedFromBinaryFormat="False"
+	InputByteLength="1">
+	<ViewBox>
+
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>43.800000,-126.133333 51.406390,-118.530830</gml:coordinates>
+		</gml:Box>
+	</ViewBox>
+<Location
+
+	Name="Seattle"
+	Type="PPL"
+	Population="563374"
+	Hierarchy="United States/Washington/King/Seattle">
+	<ViewBox>
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>43.806390,-126.130830 51.406390,-118.530830</gml:coordinates>
+		</gml:Box>
+	</ViewBox>	<Centroid><gml:Point><gml:coordinates>-122.330830000000006,47.606389999999998</gml:coordinates></gml:Point></Centroid>
+</Location>
+<Location
+
+	Name="Seattle"
+	Type="PRT"
+	Population="-1"
+	Hierarchy="United States/Seattle">
+	<ViewBox>
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>43.800000,-126.133333 51.400000,-118.533333</gml:coordinates>
+		</gml:Box>
+	</ViewBox>	<Centroid><gml:Point><gml:coordinates>-122.333332999999996,47.6</gml:coordinates></gml:Point></Centroid>
+</Location>
+</Locations>
+    EOF
+
+    expected = [
+      MetaCartaGeoParser::Location.new('Seattle', 'PPL', 563374,
+                                       'United States/Washington/King/Seattle',
+                                       -122.33083, 47.60639, nil,
+                                       [[43.806390, -126.130830],
+                                        [51.406390, -118.530830]]),
+      MetaCartaGeoParser::Location.new('Seattle', 'PRT', nil,
+                                       'United States/Seattle',
+                                       -122.333333, 47.6, nil,
+                                       [[43.8, -126.133333],
+                                        [51.4, -118.533333]]),
+    ]
+
+    locations, viewbox = @mg.locations('seattle')
+    assert_equal expected, locations
+    assert_equal [[43.8, -126.133333], [51.40639, -118.53083]], viewbox
+
+    assert_equal true, URI::HTTP.responses.empty?
+    assert_equal 1, URI::HTTP.uris.length
+    assert_equal 'http://labs.metacarta.com/GeoParser/?loc=seattle&output=locations',
+                 URI::HTTP.uris.first
+  end
+
+  def test_locations_bad_address
+    URI::HTTP.responses << <<-EOF.strip
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<!DOCTYPE Locations SYSTEM "Locations.dtd">
+
+<Locations
+	xmlns:gml="http://www.opengis.net/gml"
+	CreatedBy="MetaCarta GeoParser v3.5.0-labs-alpha"
+	CreatedOn="Sat Jun 17 02:05:42 2006"
+	ConvertedFromBinaryFormat="False"
+	InputByteLength="0">
+	<ViewBox>
+
+		<gml:Box srsName="epsg:4326">
+			<gml:coordinates>-90.000000,-180.000000 90.000000,180.000000</gml:coordinates>
+		</gml:Box>
+	</ViewBox>
+</Locations>
+    EOF
+
+    @mg.locations('aoeueou')
+  rescue MetaCartaGeoParser::AddressError => e
+    assert_equal 'bad location', e.message
+
+    assert_equal true, URI::HTTP.responses.empty?
+    assert_equal 1, URI::HTTP.uris.length
+    assert_equal 'http://labs.metacarta.com/GeoParser/?loc=aoeueou&output=locations',
+                 URI::HTTP.uris.first
+  else
+    flunk 'expected MetaCartaGeoParser::AddressError'
+  end
+
+end
+

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.99
+specification_version: 1
+name: metacarta-geoparser
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-06-16 00:00:00 -07:00
+summary: MetaCarta GeoParser API Library
+require_paths: 
+- lib
+email: eric@robotcoop.com
+homepage: 
+rubyforge_project: 
+description: Map addresses to latitude and longitude with MetaCarta's GeoParser API.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Eric Hodel
+files: 
+- LICENSE
+- Manifest.txt
+- README
+- Rakefile
+- lib/metacarta_geoparser.rb
+- test/test_metacarta_geoparser.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rc-rest
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+    version: