google-geo 1.0

data/CHANGELOG

@@ -0,0 +1 @@
+= 1.0 Initial Release

data/README

@@ -0,0 +1,27 @@
+= Google::Geo
+
+A simple, elegant library for getting geocoding information from Google Maps. Very much inspired by the google-geocode gem, but completely dependency free!
+
+== Examples
+
+  geo = Google::Geo.new API_KEY
+  
+  address = geo.locate '1600 Amphitheatre Parkway, Mountain View, CA'
+  
+  address.country      # 'US'
+  address.city         # 'Mountain View'
+  address.full_address # '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA'
+  
+  address.query        # '1600 Amphitheatre Parkway, Mountain View, CA'
+  address.accuracy     # 8
+  
+In the case of sufficiently vague queries, +Google::Geo+ will return an +Array+:
+  
+  addresses = geo.locate 'hell'
+  
+  addresses.size                  # 2
+  addresses.map { |a| a.country } # ['US', 'NO']
+
+== Contributors
+    
+Seth Thomas Rasmussen - http://sethrasmussen.com - sethrasmussen@gmail.com

data/lib/google/geo.rb

@@ -0,0 +1,190 @@
+require 'open-uri'
+
+module Google
+
+# = Google::Geo
+# 
+# A simple, elegant library for getting geocoding information from Google Maps. Very much inspired by the google-geocode gem, but completely dependency free!
+# 
+# == Examples
+# 
+#   geo = Google::Geo.new API_KEY
+# 
+#   address = geo.locate '1600 Amphitheatre Parkway, Mountain View, CA'
+# 
+#   address.country      # 'US'
+#   address.city         # 'Mountain View'
+#   address.full_address # '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA'
+# 
+#   address.query        # '1600 Amphitheatre Parkway, Mountain View, CA'
+#   address.accuracy     # 8
+# 
+# In the case of sufficiently vague queries, +Google::Geo+ will return an +Array+:
+# 
+#   addresses = geo.locate 'hell'
+# 
+#   addresses.size                  # 2
+#   addresses.map { |a| a.country } # ['US', 'NO']
+# 
+# == Contributors
+# 
+# Seth Thomas Rasmussen - http://sethrasmussen.com - sethrasmussen@gmail.com
+class  Geo    
+  # API key provided by Google allowing access to the Geocode API
+  attr_accessor :key
+  
+  def initialize(key)
+    @key = key
+  end
+  
+  # Returns an +Address+ object with accessors for all the components of a location. 
+  # The +query+ argument should be a string.
+  def locate(query)
+    xml = open(uri(query)).read
+    res = Response.new(xml, key)
+    
+    res.placemarks.map { |place| Address.new place, res.query }
+  end
+  
+  # Generate a request URI from a given search string.
+  def uri(address) #:nodoc:
+    "http://maps.google.com/maps/geo?q=#{URI.escape address}&key=#{key}&output=xml"
+  end
+  private :uri
+  
+  ###
+  
+  module Parser #:nodoc:
+    # Fetch contents of an XML element of the response.
+    def fetch(element) #:nodoc:
+      @xml.slice %r{<#{element}>(.+?)</#{element}>}, 1
+    end
+    
+    # Like fetch, but for the only piece of data locked away in an attribute.
+    def fetch_accuracy #:nodoc:
+      @xml.slice(%r{Accuracy="([^"]+)">}, 1).to_i
+    end
+  end
+  
+  ###
+  
+  # Represents locations returned in response to geocoding queries.
+  class Address
+    include Parser
+    
+    attr_reader :street
+    alias :thoroughfare :street
+    
+    attr_reader :city
+    alias :locality :city
+    
+    attr_reader :zip
+    alias :postal_code :zip
+    
+    attr_reader :county
+    alias :subadministrative_area :county
+    
+    attr_reader :state
+    alias :administrative_area :state
+    
+    attr_reader :country
+    alias :country_code :country
+    
+    # An array containing the standard three elements of a coordinate triple: latitude, longitude, elevation.
+    attr_reader :coordinates
+    
+    # A float, the standard first element of a coordinate triple.
+    attr_reader :longitude
+    alias :lng :longitude
+    
+    # A float, the standard second element of a coordinate triple.
+    attr_reader :latitude
+    alias :lat :latitude
+    
+    # A float, the standard third element of a coordinate triple.
+    attr_reader :elevation
+    
+    # An integer, Google's rating of the accuracy of the supplied address.
+    attr_reader :accuracy
+    
+    # All address attributes as one string, formatted by the service.
+    attr_reader :full_address
+    alias :to_s :full_address
+    
+    # The address query sent to the service. i.e. The user input.
+    attr_reader :query
+    
+    def initialize(placemark, query) #:nodoc
+      @xml   = placemark
+      @query = query
+      
+      {
+        :@street       => :ThoroughfareName,
+        :@city         => :LocalityName,
+        :@zip          => :PostalCodeNumber,
+        :@county       => :SubAdministrativeAreaName,
+        :@state        => :AdministrativeAreaName,
+        :@country      => :CountryNameCode,
+        
+        :@full_address => :address
+      }.each do |attribute, element|
+        instance_variable_set(attribute, (fetch(element) rescue nil))
+      end
+      
+      @longitude, @latitude, @elevation = @coordinates = fetch(:coordinates).split(',').map { |x| x.to_f }
+      
+      @accuracy = fetch_accuracy
+    end
+  end
+  
+  ###
+  
+  class Response #:nodoc:
+    include Parser
+    
+    attr_reader :query, :status, :placemarks
+    
+    def initialize(xml, geo_key) #:nodoc
+      @xml, @geo_key = xml, geo_key
+      
+      @query  = fetch(:name)
+      @status = fetch(:code).to_i
+      
+      check_for_errors
+      
+      @placemarks = @xml.scan %r{<Placemark(?: id="p\d+")?>.+?</Placemark>}m
+    end
+    
+    def check_for_errors #:nodoc:
+      case status
+        when 200 then # Success
+        when 500 then raise ServerError, "Unknown error from Google's server"
+        when 601 then raise MissingAddressError, "Missing address"
+        when 602 then raise UnknownAddressError, "Unknown address: #{@query}"
+        when 603 then raise UnavailableAddressError, "Unavailable address: #{@query}"
+        when 610 then raise InvalidMapKeyError, "Invalid map key: #{@geo_key}"
+        when 620 then raise TooManyQueriesError, "Too many queries for map key: #{@geo_key}"
+        else          raise UnknownError, "Unknown error: #{@status}"
+      end
+    end
+  end
+  
+  ###    
+  
+  class Error < Exception; end
+    
+  class ServerError  < Error; end
+    
+  class AddressError < Error; end
+  class MissingAddressError     < AddressError; end
+  class UnknownAddressError     < AddressError; end
+  class UnavailableAddressError < AddressError; end
+    
+  class MapKeyError < Error; end
+  class InvalidMapKeyError  < MapKeyError; end
+  class TooManyQueriesError < MapKeyError; end
+  
+  class UnknownError < Error; end
+end
+
+end

data/test/geo_test.rb

@@ -0,0 +1,88 @@
+require 'test/unit'
+$:.unshift "#{File.dirname __FILE__}/../vendor/mocha-0.4.0/lib"
+require 'mocha'
+require "#{File.dirname __FILE__}/../lib/google/geo"
+
+class Google::GeoTest < Test::Unit::TestCase  
+  def setup    
+    @geo = Google::Geo.new 'API_KEY'
+  end
+
+  def test_success
+    @geo.expects(:open).
+         with("http://maps.google.com/maps/geo?q=1600%20Amphitheatre%20Parkway,%20Mountain%20View,%20CA&key=API_KEY&output=xml"). # show that query is escaped
+         returns(response(:success))
+    
+    query = '1600 Amphitheatre Parkway, Mountain View, CA'
+    
+    address = @geo.locate(query).first
+    
+    assert_equal '1600 Amphitheatre Pkwy', address.street
+    assert_equal address.street, address.thoroughfare
+    
+    assert_equal 'Mountain View', address.city
+    assert_equal address.city, address.locality
+    
+    assert_equal '94043', address.zip
+    assert_equal address.zip, address.postal_code
+    
+    assert_equal 'Santa Clara', address.county
+    assert_equal address.county, address.subadministrative_area
+    
+    assert_equal 'CA', address.state
+    assert_equal address.state, address.administrative_area
+    
+    assert_equal 'US', address.country
+    assert_equal address.country, address.country_code
+    
+    assert_equal -122.083739, address.longitude
+    assert_equal address.longitude, address.lng
+    
+    assert_equal 37.423021, address.latitude
+    assert_equal address.latitude, address.lat
+    
+    assert_equal 0, address.elevation
+    
+    assert_equal [address.longitude, address.latitude, address.elevation], address.coordinates
+    
+    assert_equal 8, address.accuracy
+    
+    assert_equal '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA', address.full_address
+    assert_equal query, address.query
+  end
+
+  def test_invalid_map_key
+    @geo.expects(:open).returns(response(:invalid_map_key))
+    assert_raises(Google::Geo::InvalidMapKeyError) { @geo.locate 'foo' }
+  end
+
+  def test_missing_address
+    @geo.expects(:open).returns(response(:missing_address))
+    assert_raises(Google::Geo::MissingAddressError) { @geo.locate 'foo' }
+  end
+
+  def test_server_error
+    @geo.expects(:open).returns(response(:server_error))
+    assert_raises(Google::Geo::ServerError) { @geo.locate 'foo' }
+  end
+
+  def test_too_many_queries
+    @geo.expects(:open).returns(response(:too_many_queries))    
+    assert_raises(Google::Geo::TooManyQueriesError) { @geo.locate 'foo' }
+  end
+
+  def test_unavailable_address
+    @geo.expects(:open).returns(response(:unavailable_address))
+    assert_raises(Google::Geo::UnavailableAddressError) { @geo.locate 'foo' }
+  end
+
+  def test_unknown_address
+    @geo.expects(:open).returns(response(:unknown_address))
+    assert_raises(Google::Geo::UnknownAddressError) { @geo.locate 'foo' }
+  end
+  
+  private
+    def response(filename)
+      File.new "#{File.dirname __FILE__}/fixtures/#{filename}.xml"
+    end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.2
+specification_version: 1
+name: google-geo
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+date: 2007-05-24 00:00:00 -07:00
+summary: A simple, elegant library for getting geocoding information from Google Maps. Very much inspired by the google-geocode gem, but completely dependency free!
+require_paths: 
+- lib
+email: 
+homepage: 
+rubyforge_project: 
+description: 
+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: 
+- "    \n"
+files: 
+- lib/google
+- lib/google/geo.rb
+- README
+- CHANGELOG
+test_files: 
+- test/geo_test.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+- CHANGELOG
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+