graticule 0.1.3 → 0.2.0

data/CHANGELOG.txt

@@ -1,3 +1,14 @@
+0.2.0
+* changed city to locality, state to region, and zip to postal_code
+* added support for PostcodeAnywhere
+* added support for Local Search Maps (James Stewart)
+* added IP-based geocoder
+* moved geocoders to Graticule::Geocoder namespace
+* fixed Google geocoder (again)
+* made Yahoo geocoder consistent with others by returning 1 result
+* geocoders can how take a Hash (:street, :locality, :region, :postal_code, :country)
+  or a Graticule::Location for the #locate call
+
 0.1.3 (2007-02-14)
 * fixed Google geocoder
 * fixed CLI

data/Manifest.txt

@@ -12,12 +12,16 @@ lib/graticule/distance/haversine.rb
 lib/graticule/distance/spherical.rb
 lib/graticule/distance/vincenty.rb
 lib/graticule/geocoder.rb
-lib/graticule/geocoders/bogus.rb
-lib/graticule/geocoders/geocoder_us.rb
-lib/graticule/geocoders/google.rb
-lib/graticule/geocoders/meta_carta.rb
-lib/graticule/geocoders/rest.rb
-lib/graticule/geocoders/yahoo.rb
+lib/graticule/geocoder/bogus.rb
+lib/graticule/geocoder/geocoder_ca.rb
+lib/graticule/geocoder/geocoder_us.rb
+lib/graticule/geocoder/google.rb
+lib/graticule/geocoder/host_ip.rb
+lib/graticule/geocoder/local_search_maps.rb
+lib/graticule/geocoder/meta_carta.rb
+lib/graticule/geocoder/postcode_anywhere.rb
+lib/graticule/geocoder/rest.rb
+lib/graticule/geocoder/yahoo.rb
 lib/graticule/location.rb
 lib/graticule/version.rb
 test/fixtures/responses/geocoder_us/success.xml
@@ -29,18 +33,29 @@ test/fixtures/responses/google/server_error.xml
 test/fixtures/responses/google/success.xml
 test/fixtures/responses/google/unavailable.xml
 test/fixtures/responses/google/unknown_address.xml
+test/fixtures/responses/host_ip/private.txt
+test/fixtures/responses/host_ip/success.txt
+test/fixtures/responses/host_ip/unknown.txt
+test/fixtures/responses/local_search_maps/success.txt
 test/fixtures/responses/meta_carta/bad_address.xml
 test/fixtures/responses/meta_carta/multiple.xml
 test/fixtures/responses/meta_carta/success.xml
+test/fixtures/responses/postcode_anywhere/badkey.xml
+test/fixtures/responses/postcode_anywhere/canada.xml
+test/fixtures/responses/postcode_anywhere/empty.xml
+test/fixtures/responses/postcode_anywhere/success.xml
+test/fixtures/responses/postcode_anywhere/uk.xml
 test/fixtures/responses/yahoo/success.xml
 test/fixtures/responses/yahoo/unknown_address.xml
 test/mocks/uri.rb
 test/test_helper.rb
 test/unit/graticule/distance_test.rb
+test/unit/graticule/geocoder/geocoder_us_test.rb
+test/unit/graticule/geocoder/google_test.rb
+test/unit/graticule/geocoder/host_ip_test.rb
+test/unit/graticule/geocoder/local_search_maps_test.rb
+test/unit/graticule/geocoder/meta_carta_test.rb
+test/unit/graticule/geocoder/postcode_anywhere_test.rb
+test/unit/graticule/geocoder/yahoo_test.rb
 test/unit/graticule/geocoder_test.rb
-test/unit/graticule/geocoders/geocoder_us_test.rb
-test/unit/graticule/geocoders/geocoders.rb
-test/unit/graticule/geocoders/google_test.rb
-test/unit/graticule/geocoders/meta_carta_test.rb
-test/unit/graticule/geocoders/yahoo_test.rb
 test/unit/graticule/location_test.rb

data/README.txt

@@ -1,6 +1,6 @@
 = Graticule
 
-Graticule is a geocoding API for looking up address coordinates.  It supports supports the Yahoo, Google, Geocoder.us, and MetaCarta APIs.
+Graticule is a geocoding API for looking up address coordinates.  It supports many popular APIs, including Yahoo, Google, Geocoder.ca, Geocoder.us, PostcodeAnywhere and MetaCarta.
 
 = Usage
 

data/bin/geocode

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
 
-require 'graticule'
+require 'graticule/cli'
 
 Graticule::Cli.start ARGV

data/lib/graticule.rb

@@ -4,15 +4,17 @@ require 'active_support'
 
 require 'graticule/location'
 require 'graticule/geocoder'
-require 'graticule/geocoders/bogus'
-require 'graticule/geocoders/rest'
-require 'graticule/geocoders/google'
-require 'graticule/geocoders/yahoo'
-require 'graticule/geocoders/geocoder_us'
-require 'graticule/geocoders/meta_carta'
+require 'graticule/geocoder/bogus'
+require 'graticule/geocoder/rest'
+require 'graticule/geocoder/google'
+require 'graticule/geocoder/host_ip'
+require 'graticule/geocoder/yahoo'
+require 'graticule/geocoder/geocoder_ca'
+require 'graticule/geocoder/geocoder_us'
+require 'graticule/geocoder/local_search_maps'
+require 'graticule/geocoder/meta_carta'
+require 'graticule/geocoder/postcode_anywhere'
 require 'graticule/distance'
 require 'graticule/distance/haversine'
 require 'graticule/distance/spherical'
 require 'graticule/distance/vincenty'
-
-require 'graticule/cli'

data/lib/graticule/cli.rb

@@ -1,3 +1,4 @@
+require 'graticule'
 require 'optparse'
 
 module Graticule

data/lib/graticule/geocoder.rb

@@ -8,18 +8,7 @@ module Graticule
   # See the documentation for your specific geocoder for more information
   #
   def self.service(name)
-    self.const_get "#{name}_geocoder".camelize
-  end
-
-  # The Geocode class is the base class for all geocoder implementations. The
-  # geocoders must implement:
-  # 
-  # * locate(address)  
-  #
-  class Geocoder
-    def initialize
-      raise NotImplementedError
-    end
+    Geocoder.const_get name.to_s.camelize
   end
   
   # Base error class

data/lib/graticule/geocoder/bogus.rb

@@ -0,0 +1,15 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # Bogus geocoder that can be used for test purposes
+    class Bogus
+    
+      # returns a new location with the address set to the original query string
+      def locate(address)
+        Location.new :street => address
+      end
+    
+    end
+
+  end
+end

data/lib/graticule/geocoder/geocoder_ca.rb

@@ -0,0 +1,52 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # TODO: Reverse Geocoding
+    class GeocoderCa < Rest
+
+      def initialize(auth = nil)
+        @url = URI.parse 'http://geocoder.ca/'
+        @auth = auth
+      end
+
+      def locate(address)
+        get :locate => address.is_a?(String) ? address : location_from_params(address).to_s(:country => false)
+      end
+      
+      def parse_response(xml) #:nodoc:
+        returning Location.new do |location|
+          location.latitude = xml.elements['geodata/latt'].text.to_f
+          location.longitude = xml.elements['geodata/longt'].text.to_f
+          location.street = xml.elements['geodata/standard/staddress'].text
+          location.locality = xml.elements['geodata/standard/city'].text
+          location.region = xml.elements['geodata/standard/prov'].text
+        end
+      end
+
+      def check_error(xml) #:nodoc:
+        error = xml.elements['geodata/error']
+        if error
+          code = error.elements['code'].text.to_i
+          message = error.elements['description'].text
+          if (1..3).include?(code)
+            raise CredentialsError, message
+          elsif (4..8).include?(code)
+            raise AddressError, message
+          else
+            raise Error, message
+          end
+        end
+      end
+
+      def make_url(params) #:nodoc:
+        params[:auth]       = @auth if @auth
+        params[:standard]   = 1
+        params[:showpostal] = 1
+        params[:geoit]      = 'XML'
+        super params
+      end
+
+
+    end
+  end
+end

data/lib/graticule/geocoder/geocoder_us.rb

@@ -0,0 +1,47 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # A library for lookup up coordinates with geocoder.us' API.
+    #
+    # http://geocoder.us/help/
+    class GeocoderUs < Rest
+
+      # Creates a new GeocoderUs object optionally using +username+ and
+      # +password+.
+      #
+      # You can sign up for a geocoder.us account here:
+      #
+      # http://geocoder.us/user/signup
+      def initialize(user = nil, password = nil)
+        if user and password then
+          @url = URI.parse 'http://geocoder.us/member/service/rest/geocode'
+          @url.user = user
+          @url.password = password
+        else
+          @url = URI.parse 'http://rpc.geocoder.us/service/rest/geocode'
+        end
+      end
+
+      # Locates +address+ and returns the address' latitude and longitude or
+      # raises an AddressError.
+      def locate(address)
+        get :address => address.is_a?(String) ? address : location_from_params(address).to_s(:country => false)
+      end
+
+      def parse_response(xml) #:nodoc:
+        location = Location.new
+        location.street = xml.elements['rdf:RDF/geo:Point/dc:description'].text
+
+        location.latitude = xml.elements['rdf:RDF/geo:Point/geo:lat'].text.to_f
+        location.longitude = xml.elements['rdf:RDF/geo:Point/geo:long'].text.to_f
+
+        return location
+      end
+
+      def check_error(xml) #:nodoc:
+        raise AddressError, xml.text if xml.text == 'couldn\'t find this address! sorry'
+      end
+
+    end
+  end
+end

data/lib/graticule/geocoder/google.rb

@@ -0,0 +1,106 @@
+
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+  
+    # First you need a Google Maps API key.  You can register for one here:
+    # http://www.google.com/apis/maps/signup.html
+    # 
+    # Then you create a GoogleGeocode object and start locating addresses:
+    # 
+    #   require 'rubygems'
+    #   require 'graticule'
+    # 
+    #   gg = Graticule.service(:google).new(:key => MAPS_API_KEY)
+    #   location = gg.locate '1600 Amphitheater Pkwy, Mountain View, CA'
+    #   p location.coordinates
+    # 
+    class Google < Rest
+      # http://www.google.com/apis/maps/documentation/#Geocoding_HTTP_Request
+    
+      # http://www.google.com/apis/maps/documentation/reference.html#GGeoAddressAccuracy
+      PRECISION = {
+        0 => :unknown,      # Unknown location. (Since 2.59)
+        1 => :country,      # Country level accuracy. (Since 2.59)
+        2 => :state,        # Region (state, province, prefecture, etc.) level accuracy. (Since 2.59)
+        3 => :state,        # Sub-region (county, municipality, etc.) level accuracy. (Since 2.59)
+        4 => :city,         # Town (city, village) level accuracy. (Since 2.59)
+        5 => :zip,          # Post code (zip code) level accuracy. (Since 2.59)
+        6 => :street,       # Street level accuracy. (Since 2.59)
+        7 => :street,       # Intersection level accuracy. (Since 2.59)
+        8 => :address       # Address level accuracy. (Since 2.59)
+      }
+
+      # Creates a new GoogleGeocode that will use Google Maps API key +key+.  You
+      # can sign up for an API key here:
+      #
+      # http://www.google.com/apis/maps/signup.html
+      def initialize(key)
+        @key = key
+        @url = URI.parse 'http://maps.google.com/maps/geo'
+      end
+
+      # Locates +address+ returning a Location
+      def locate(address)
+        get :q => address.is_a?(String) ? address : location_from_params(address).to_s
+      end
+
+      # Extracts a Location from +xml+.
+      def parse_response(xml) #:nodoc:
+        address = REXML::XPath.first(xml, '//xal:AddressDetails', 'xal' => "urn:oasis:names:tc:ciq:xsdschema:xAL:2.0")
+
+        longitude, latitude, = xml.elements['/kml/Response/Placemark/Point/coordinates'].text.split(',').map { |v| v.to_f }
+      
+        Location.new \
+          :street => value(address.elements['Country/AdministrativeArea/SubAdministrativeArea/Locality/Thoroughfare/ThoroughfareName/text()']),
+          :locality => value(address.elements['Country/AdministrativeArea/SubAdministrativeArea/Locality/LocalityName/text()']),
+          :region => value(address.elements['Country/AdministrativeArea/AdministrativeAreaName/text()']),
+          :postal_code => value(address.elements['Country/AdministrativeArea/SubAdministrativeArea/Locality/PostalCode/PostalCodeNumber/text()']),
+          :country => value(address.elements['Country/CountryNameCode/text()']),
+          :latitude => latitude,
+          :longitude => longitude,
+          :precision => PRECISION[address.attribute('Accuracy').value.to_i] || :unknown
+      end
+
+      # Extracts and raises an error from +xml+, if any.
+      def check_error(xml) #:nodoc:
+        status = xml.elements['/kml/Response/Status/code'].text.to_i
+        case status
+        when 200 then # ignore, ok
+        when 500 then
+          raise Error, 'server error'
+        when 601 then
+          raise AddressError, 'missing address'
+        when 602 then
+          raise AddressError, 'unknown address'
+        when 603 then
+          raise AddressError, 'unavailable address'
+        when 610 then
+          raise CredentialsError, 'invalid key'
+        when 620 then
+          raise CredentialsError, 'too many queries'
+        else
+          raise Error, "unknown error #{status}"
+        end
+      end
+
+      # Creates a URL from the Hash +params+.  Automatically adds the key and
+      # sets the output type to 'xml'.
+      def make_url(params) #:nodoc:
+        params[:key] = @key
+        params[:output] = 'xml'
+
+        super params
+      end
+    
+      private
+    
+        def value(element)
+          element.value if element
+        end
+    
+        def text(element)
+          element.text if element
+        end
+    end
+  end
+end

data/lib/graticule/geocoder/host_ip.rb

@@ -0,0 +1,50 @@
+require 'yaml'
+
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    class HostIp
+
+      def initialize
+        @url = URI.parse 'http://api.hostip.info/get_html.php'
+      end
+
+      # Geocode an IP address using http://hostip.info
+      def locate(address)
+        make_url(:ip => address, :position => true).open do |response|
+          # add new line so YAML.load doesn't puke
+          result = response.read + "\n"
+          check_error(result)
+          parse_response(YAML.load(result))
+        end
+      end
+    
+    private
+      
+      def parse_response(response) #:nodoc:
+        returning Location.new do |location|
+          location.latitude = response['Latitude']
+          location.longitude = response['Longitude']
+          location.locality, location.region = response['City'].split(', ')
+          country = response['Country'].match(/\((\w+)\)$/)
+          location.country = country[1] if country
+        end
+      end
+
+      def check_error(response) #:nodoc:
+        raise AddressError, 'Unknown' if response =~ /Unknown City/
+        raise AddressError, 'Private Address' if response =~ /Private Address/
+      end
+
+      def make_url(params) #:nodoc:
+        returning @url.dup do |url|
+          url.query = params.map do |k,v| 
+            "#{URI.escape k.to_s}=#{URI.escape v.to_s}"
+          end.join('&')
+        end
+      end
+
+
+    end
+  end
+end

data/lib/graticule/geocoder/local_search_maps.rb

@@ -0,0 +1,45 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # A library for lookup of coordinates with http://geo.localsearchmaps.com/
+    #
+    # See http://emad.fano.us/blog/?p=277
+    class LocalSearchMaps < Rest
+    
+      def initialize
+        @url = URI.parse 'http://geo.localsearchmaps.com/'
+      end
+    
+      # This web service will handle some addresses outside the US
+      # if given more structured arguments than just a string address
+      # So allow input as a hash for the different arguments (:city, :country, :zip)
+      def locate(params)
+        get params.is_a?(String) ? {:loc => params} : map_attributes(location_from_params(params))
+      end
+      
+    private
+    
+      def map_attributes(location)
+        #mapping = {:street => :address, :locality => :city, :region => :state, :postal_code => :zip}
+        mapping = {}
+        mapping.keys.inject({}) do |result,attribute|
+          result[mapping[attribute]] = location.attributes[attribute]
+        end
+      end
+    
+      def check_error(js)
+        raise AddressError, "Empty Response" if js.nil? or js.text.nil?
+        raise AddressError, 'Location not found' if js.text =~ /location not found/
+      end
+    
+      def parse_response(js)
+        returning Location.new do |location|
+          coordinates = js.text.match(/map.centerAndZoom\(new GPoint\((.+?), (.+?)\)/)
+          location.longitude = coordinates[1].to_f
+          location.latitude = coordinates[2].to_f
+        end
+      end
+      
+    end
+  end
+end