graticule 0.1.3 → 0.2.0

data/lib/graticule/geocoder/meta_carta.rb

@@ -0,0 +1,38 @@
+
+module Graticule
+  module Geocoder
+
+    # Library for looking up coordinates with MetaCarta's GeoParser API.
+    #
+    # http://labs.metacarta.com/GeoParser/documentation.html
+    class MetaCarta < Rest
+
+      def initialize # :nodoc:
+        @url = URI.parse 'http://labs.metacarta.com/GeoParser/'
+      end
+
+      # Finds +location+ and returns a Location object.
+      def locate(location)
+        get :q => location.is_a?(String) ? location : location_from_params(location).to_s
+      end
+      
+    private
+
+      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:
+        result = xml.elements['/Locations/Location[1]']
+        coords = result.elements['Centroid/gml:Point/gml:coordinates'].text.split ','
+        Location.new :latitude => coords.first.to_f, :longitude => coords.last.to_f
+      end
+      
+    end
+  end
+end

data/lib/graticule/geocoder/postcode_anywhere.rb

@@ -0,0 +1,63 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    class PostcodeAnywhere < Rest
+
+      # http://www.postcodeanywhere.com/register/
+      def initialize(account_code, license_code)
+        @url = URI.parse 'http://services.postcodeanywhere.co.uk/xml.aspx'
+        @account_code = account_code
+        @license_code = license_code
+      end
+
+      def locate(params)
+        location = location_from_params(params)
+        get :address => location.to_s(:country => false), :country => location.country 
+      end
+      
+    private
+    
+      def make_url(params) #:nodoc:
+        params[:account_code] = @account_code
+        params[:license_code] = @license_code
+        params[:action] = 'geocode'
+        super params
+      end
+
+      def parse_response(xml) #:nodoc:
+        result = xml.elements['/PostcodeAnywhere/Data/Item[1]']
+        returning Location.new do |location|
+          location.latitude = result.attribute('latitude').value.to_f
+          location.longitude = result.attribute('longitude').value.to_f
+          location.street = value(result.attribute('line1'))
+          location.locality = value(result.attribute('city'))
+          location.region = value(result.attribute('state'))
+          location.postal_code = value(result.attribute('postal_code'))
+          location.country = value(result.attribute('country'))
+        end
+      end
+      
+      def value(attribute)
+        attribute.value if attribute
+      end
+
+      # http://www.postcodeanywhere.co.uk/developers/documentation/errors.aspx
+      def check_error(xml) #:nodoc:
+        #raise AddressError, xml.text if xml.text == 'couldn\'t find this address! sorry'
+        if error = xml.elements['/PostcodeAnywhere/Data/Item[@error_number][1]']
+          error_number = error.attribute('error_number').value.to_i
+          message = error.attribute('message').value
+          if (1..11).include?(error_number) || (34..38).include?(error_number)
+            raise CredentialsError, message
+          else
+            raise Error, message
+          end
+        elsif xml.elements['/PostcodeAnywhere/Data'].elements.empty?
+          raise AddressError, 'No results returned'
+        end
+        
+      end
+    
+    end
+  end
+end

data/lib/graticule/geocoder/rest.rb

@@ -0,0 +1,110 @@
+require 'open-uri'
+require 'rexml/document'
+
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # Abstract class for implementing REST APIs.
+    #
+    # === Example
+    #
+    # The following methods must be implemented in sublcasses:
+    #
+    # +initialize+:: Sets @url to the service enpoint.
+    # +check_error+:: Checks for errors in the server response.
+    # +parse_response+:: Extracts information from the server response.
+    #
+    # If you have extra URL paramaters (application id, output type) or need to
+    # perform URL customization, override +make_url+.
+    #
+    #   class FakeService < RCRest
+    #   
+    #     class Error < RCRest::Error; end
+    #   
+    #     def initialize(appid)
+    #       @appid = appid
+    #       @url = URI.parse 'http://example.com/test'
+    #     end
+    #   
+    #     def check_error(xml)
+    #       raise Error, xml.elements['error'].text if xml.elements['error']
+    #     end
+    #   
+    #     def make_url(params)
+    #       params[:appid] = @appid
+    #       super params
+    #     end
+    #   
+    #     def parse_response(xml)
+    #       # return Location
+    #     end
+    #   
+    #     def test(query)
+    #       get :q => query
+    #     end
+    #   
+    #   end
+    class Rest
+
+      # Web services initializer.
+      #
+      # Concrete web services implementations must set the +url+ instance
+      # variable which must be a URI.
+      def initialize
+        raise NotImplementedError
+      end
+      
+    private
+    
+      def location_from_params(params)
+        case params
+        when Location then params
+        when Hash then Location.new params
+        else
+          raise ArgumentError, "Expected a Graticule::Location or a hash with :street, :locality, :region, :postal_code, and :country attributes"
+        end
+      end
+
+      # Must extract and raise an error from +xml+, an REXML::Document, if any.
+      # Must returns if no error could be found.
+      def check_error(xml)
+        raise NotImplementedError
+      end
+
+      # Performs a GET request with +params+.  Calls the parse_response method on
+      # the concrete class with an REXML::Document instance and returns its
+      # result.
+      def get(params = {})
+        url = make_url params
+
+        url.open do |response|
+          res = REXML::Document.new response.read
+          check_error(res)
+          return parse_response(res)
+        end
+      rescue OpenURI::HTTPError => e
+        response = REXML::Document.new e.io.read
+        check_error response
+        raise
+      end
+
+      # Creates a URI from the Hash +params+.  Override this then call super if
+      # you need to add extra params like an application id or output type.
+      def make_url(params)
+        escaped_params = params.sort_by { |k,v| k.to_s }.map do |k,v|
+          "#{URI.escape k.to_s}=#{URI.escape v.to_s}"
+        end
+
+        url = @url.dup
+        url.query = escaped_params.join '&'
+        return url
+      end
+
+      # Must parse results from +xml+, an REXML::Document, into a Location.
+      def parse_response(xml)
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/graticule/geocoder/yahoo.rb

@@ -0,0 +1,96 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+  
+    # Yahoo geocoding API.
+    #
+    # http://developer.yahoo.com/maps/rest/V1/geocode.html
+    class Yahoo < Rest
+
+      PRECISION = {
+        "country"=> :country,
+        "state" => :state,
+        "city" => :city,
+        "zip+4" => :zip,
+        "zip+2" => :zip,
+        "zip" => :zip,
+        "street" => :street,
+        "address" => :address
+      }
+
+      # Web services initializer.
+      #
+      # The +appid+ is the Application ID that uniquely identifies your
+      # application.  See: http://developer.yahoo.com/faq/index.html#appid
+      #
+      # Concrete web services implementations need to set the following instance
+      # variables then call super:
+      #
+      # +host+:: API endpoint hostname
+      # +service_name+:: service name
+      # +version+:: service name version number
+      # +method+:: service method call
+      #
+      # See http://developer.yahoo.com/search/rest.html
+      def initialize(appid)
+        @host = 'api.local.yahoo.com'
+        @service_name = 'MapsService'
+        @version = 'V1'
+        @method = 'geocode'
+        @appid = appid
+        @url = URI.parse "http://#{@host}/#{@service_name}/#{@version}/#{@method}"
+      end
+
+      # Returns a Location for +address+.
+      #
+      # The +address+ can be any of:
+      # * city, state
+      # * city, state, zip
+      # * zip
+      # * street, city, state
+      # * street, city, state, zip
+      # * street, zip
+      def locate(address)
+        location = (address.is_a?(String) ? address : location_from_params(address).to_s(:country => false))
+        # yahoo pukes on line breaks
+        get :location => location.gsub("\n", ', ')
+      end
+
+      def parse_response(xml) # :nodoc:
+        r = xml.elements['ResultSet/Result[1]']
+        returning Location.new do |location|
+          location.precision = PRECISION[r.attributes['precision']] || :unknown
+
+          if r.attributes.include? 'warning' then
+            location.warning = r.attributes['warning']
+          end
+
+          location.latitude = r.elements['Latitude'].text.to_f
+          location.longitude = r.elements['Longitude'].text.to_f
+
+          location.street = r.elements['Address'].text.titleize unless r.elements['Address'].text.blank?
+          location.locality = r.elements['City'].text.titleize unless r.elements['City'].text.blank?
+          location.region = r.elements['State'].text
+          location.postal_code = r.elements['Zip'].text
+          location.country = r.elements['Country'].text
+        end
+      end
+
+      # Extracts and raises an error from +xml+, if any.
+      def check_error(xml) #:nodoc:
+        err = xml.elements['Error']
+        raise Error, err.elements['Message'].text if err
+      end
+
+      # Creates a URL from the Hash +params+.  Automatically adds the appid and
+      # sets the output type to 'xml'.
+      def make_url(params) #:nodoc:
+        params[:appid] = @appid
+        params[:output] = 'xml'
+
+        super params
+      end
+
+    end
+    
+  end
+end

data/lib/graticule/location.rb

@@ -2,12 +2,23 @@ module Graticule
   
   # A geographic location
   class Location
-    attr_accessor :latitude, :longitude, :street, :city, :state, :zip, :country, :precision, :warning
+    attr_accessor :latitude, :longitude, :street, :locality, :region, :postal_code, :country, :precision, :warning
+    alias_method :city, :locality
+    alias_method :state, :region
+    alias_method :zip, :postal_code
     
     def initialize(attrs = {})
       attrs.each do |key,value|
         instance_variable_set "@#{key}", value
       end
+      self.precision ||= :unknown
+    end
+    
+    def attributes
+      [:latitude, :longitude, :street, :locality, :region, :postal_code, :country].inject({}) do |result,attr|
+        result[attr] = self.send(attr) if self.send(attr)
+        result
+      end
     end
     
     # Returns an Array with latitude and longitude.
@@ -16,7 +27,7 @@ module Graticule
     end
     
     def ==(object)
-      super(object) || [:latitude, :longitude, :street, :city, :state, :zip, :country, :precision].all? do |m|
+      super(object) || [:latitude, :longitude, :street, :locality, :region, :postal_code, :country, :precision].all? do |m|
         object.respond_to?(m) && self.send(m) == object.send(m)
       end
     end
@@ -29,16 +40,17 @@ module Graticule
     
     # Where would I be if I dug through the center of the earth?
     def antipode
-      new_longitude = longitude + (longitude >= 0 ? -180 : 180)
-      Location.new(:latitude => -latitude, :longitude => new_longitude)
+      Location.new :latitude => -latitude, :longitude => longitude + (longitude >= 0 ? -180 : 180)
     end
     alias_method :antipodal_location, :antipode
     
-    def to_s(coordinates = false)
+    def to_s(options = {})
+      options = {:coordinates => false, :country => true}.merge(options)
       result = ""
       result << "#{street}\n" if street
-      result << [city, [state, zip, country].compact.join(" ")].compact.join(", ")
-      result << "\nlatitude: #{latitude}, longitude: #{longitude}" if coordinates && [latitude, longitude].any?
+      result << [locality, [region, postal_code].compact.join(" ")].compact.join(", ")
+      result << " #{country}" if options[:country] && country
+      result << "\nlatitude: #{latitude}, longitude: #{longitude}" if options[:coordinates] && [latitude, longitude].any?
       result
     end
     

data/lib/graticule/version.rb

@@ -1,8 +1,8 @@
 module Graticule #:nodoc:
   module Version #:nodoc:
     MAJOR = 0
-    MINOR = 1
-    TINY = 3
+    MINOR = 2
+    TINY = 0
   
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/test/fixtures/responses/host_ip/private.txt

@@ -0,0 +1,4 @@
+Country: (Private Address) (XX)
+City: (Private Address)
+Latitude: 
+Longitude:

data/test/fixtures/responses/host_ip/success.txt

@@ -0,0 +1,4 @@
+Country: UNITED STATES (US)
+City: Mountain View, CA
+Latitude: 37.402
+Longitude: -122.078

data/test/fixtures/responses/host_ip/unknown.txt

@@ -0,0 +1,4 @@
+Country: (Unknown Country?) (XX)
+City: (Unknown City?)
+Latitude: 
+Longitude: 

data/test/fixtures/responses/local_search_maps/success.txt

@@ -0,0 +1 @@
+map.centerAndZoom(new GPoint(-0.130427, 51.510036), 4);

data/test/fixtures/responses/postcode_anywhere/badkey.xml

@@ -0,0 +1,9 @@
+<PostcodeAnywhere Server="WS12" Version="3.0" Date="12/03/2007 15:43:33" Duration="0.016s">
+  <Schema Items="2">
+    <Field Name="error_number"/>
+    <Field Name="message"/>
+  </Schema>
+  <Data Items="1">
+    <Item error_number="6" message="License key was not recognised"/>
+  </Data>
+</PostcodeAnywhere>

data/test/fixtures/responses/postcode_anywhere/canada.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PostcodeAnywhere Server="WS12" Version="3.0" Date="17/03/2007 19:01:05" Duration="1.109s">
+  <Schema Items="8">
+    <Field Name="line1"/>
+    <Field Name="line2"/>
+    <Field Name="city"/>
+    <Field Name="state"/>
+    <Field Name="postal_code"/>
+    <Field Name="country"/>
+    <Field Name="longitude"/>
+    <Field Name="latitude"/>
+  </Schema>
+  <Data Items="1">
+    <Item line1="204 Campbell Ave" city="Revelstoke" state="BC" postal_code="V0E" country="Canada" longitude="-118.196970002204" latitude="50.9997350418267"/>
+  </Data>
+</PostcodeAnywhere>

data/test/fixtures/responses/postcode_anywhere/empty.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PostcodeAnywhere Version="3.0" Server="WS03" Date="17/03/2007 19:26:33" Duration="0.016s">
+  <Schema Items="10">
+    <Field Name="id"/>
+    <Field Name="seq"/>
+    <Field Name="location"/>
+    <Field Name="grid_east_m"/>
+    <Field Name="grid_north_m"/>
+    <Field Name="longitude"/>
+    <Field Name="latitude"/>
+    <Field Name="os_reference"/>
+    <Field Name="wgs84_longitude"/>
+    <Field Name="wgs84_latitude"/>
+  </Schema>
+  <Data Items="0"/>
+</PostcodeAnywhere>