norman-graticule 0.2.7

data/lib/graticule/geocoder/geocoder_ca.rb

@@ -0,0 +1,54 @@
+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
+      
+    private
+      
+      def parse_response(parse_type, 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,49 @@
+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
+      
+    private
+
+      def parse_response(parse_type, 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,120 @@
+
+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
+    # 
+    #   gg = Graticule.service(:google).new(MAPS_API_KEY)
+    #   location = gg.locate '1600 Amphitheater Pkwy, Mountain View, CA'
+    #   p location.coordinates
+    #   #=> [37.423111, -122.081783
+    #
+    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+.
+      def initialize(key)
+        @key = key
+        @url = URI.parse 'http://maps.google.com/maps/geo'
+      end
+
+      # Locates +address+ returning a Location
+      def locate(*args)
+        case args.first
+          when :first then get :first, :location => extract_location(args[1]) 
+          when :all then get :all, :location => extract_location(args[1])
+          else get :first, :location => extract_location(args.first)
+        end
+      end
+
+    private
+
+      def extract_location(address)
+        address.is_a?(String) ? address : location_from_params(address).to_s        
+      end
+
+      # Extracts a Location from +xml+.
+      def parse_response(parse_type, xml) #:nodoc:
+        # puts xml.elements['//Placemark[1]'].to_s
+        if parse_type == :all
+          locations = []
+          xml.elements['//Placemark'].each do |element|
+            locations << parse_location_xml(element)
+          end
+          return locations        
+        else
+          return parse_location_xml(xml.elements['//Placemark[1]'])
+        end
+      end
+      
+      def parse_location_xml(xml)
+        longitude, latitude, = xml.elements['//Point/coordinates'].text.split(',').map { |v| v.to_f }
+        returning Location.new(:latitude => latitude, :longitude => longitude) do |l|
+          address = REXML::XPath.first(xml, '//xal:AddressDetails',
+            'xal' => "urn:oasis:names:tc:ciq:xsdschema:xAL:2.0")
+          if address
+            l.street = value(address.elements['//ThoroughfareName/text()'])
+            l.locality = value(address.elements['//LocalityName/text()'])
+            l.region = value(address.elements['//AdministrativeAreaName/text()'])
+            l.postal_code = value(address.elements['//PostalCodeNumber/text()'])
+            l.country = value(address.elements['//CountryNameCode/text()'])
+            l.precision = PRECISION[address.attribute('Accuracy').value.to_i] || :unknown
+          end
+        end
+      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
+    
+      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,41 @@
+require 'yaml'
+
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    class HostIp < Base
+
+      def initialize
+        @url = URI.parse 'http://api.hostip.info/get_html.php'
+      end
+
+      # Geocode an IP address using http://hostip.info
+      def locate(address)
+        get :ip => address, :position => true
+      end
+    
+    private
+    
+      def prepare_response(response)
+        # add new line so YAML.load doesn't puke
+        YAML.load(response + "\n")
+      end
+      
+      def parse_response(parse_type, 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['City'] =~ /Unknown City/
+        raise AddressError, 'Private Address' if response['City'] =~ /Private Address/
+      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 < Base
+    
+      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 => :street, :locality => :city, :region => :state, :postal_code => :zip, :country => :country}
+        mapping.keys.inject({}) do |result,attribute|
+          result[mapping[attribute]] = location.attributes[attribute] unless location.attributes[attribute].blank?
+          result
+        end
+      end
+    
+      def check_error(js)
+        raise AddressError, "Empty Response" if js.nil?
+        raise AddressError, 'Location not found' if js =~ /location not found/
+      end
+    
+      def parse_response(parse_type, js)
+        returning Location.new do |location|
+          coordinates = js.match(/map.centerAndZoom\(new GPoint\((.+?), (.+?)\)/)
+          location.longitude = coordinates[1].to_f
+          location.latitude = coordinates[2].to_f
+        end
+      end
+      
+    end
+  end
+end

data/lib/graticule/geocoder/map_quest.rb

@@ -0,0 +1,109 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # First you need a Mapquest API key.  You can register for one here:
+    # http://www.mapquest.com/features/main.adp?page=developer_tools_oapi
+    #
+    # Then you create a MapquestGeocode object and start locating addresses:
+    #
+    #   gg = Graticule.service(:map_quest).new(MAPS_API_KEY)
+    #   location = gg.locate :street => '1600 Amphitheater Pkwy', :locality => 'Mountain View', :region => 'CA'
+    #   p location.coordinates
+    #
+    class MapQuest < Rest
+      # http://trc.mapquest.com
+
+      PRECISION = {
+        0 => :unknown,
+        'COUNTRY' => :country,
+        'STATE' => :state,
+        'COUNTY' => :state,
+        'CITY' => :city,
+        'ZIP' => :zip,'ZIP7' => :zip,'ZIP9' => :zip,
+        'INTERSECTIONS' => :street,
+        'STREET' => :street,
+        'ADDRESS' => :address
+      }
+
+      # Creates a new MapquestGeocode that will use Mapquest API key +key+.
+      #
+      # WARNING: The MapQuest API Keys tend to be already URI encoded. If this is the case
+      # be sure to URI.unescape the key in the call to new
+      def initialize(key)
+        @key = key
+        @url = URI.parse 'http://web.openapi.mapquest.com/oapi/transaction'
+      end
+
+      # Locates +address+ returning a Location
+      def locate(address)
+        get map_attributes(location_from_params(address))
+      end
+
+    private
+
+      def map_attributes(location)
+        mapping = {:street => :address, :locality => :city, :region => :stateProvince, :postal_code => :postalcoe, :country => :country}
+        mapping.keys.inject({}) do |result,attribute|
+          result[mapping[attribute]] = location.attributes[attribute] unless location.attributes[attribute].blank?
+          result
+        end
+      end
+      
+      # Extracts a Location from +xml+.
+      def parse_response(parse_type, xml) #:nodoc:
+        address = REXML::XPath.first(xml, '/advantage/geocode/locations/location')
+
+        Location.new \
+        :street => value(address.elements['//address/text()']),
+        :locality => value(address.elements['//city/text()']),
+        :region => value(address.elements['//stateProvince/text()']),
+        :postal_code => value(address.elements['//postalCode/text()']),
+        :country => value(address.elements['//country/text()']),
+        :latitude => value(address.elements['//latitude/text()']),
+        :longitude => value(address.elements['//longitude/text()']),
+        :precision => PRECISION[address.elements['//geocodeQuality'].text] || :unknown
+      end
+
+      # Extracts and raises an error from +xml+, if any.
+      def check_error(xml) #:nodoc:
+        return unless xml.elements['//error']
+        status = xml.elements['//error/code'].text.to_i
+        msg = xml.elements['//error/text'].text
+        case status
+        when 255..299 then
+          raise CredentialsError, msg
+        when 400..500 then
+          raise AddressError, msg
+        when 600.699 then
+          raise Error, msg
+        when 900 then
+          raise AddressError, 'invalid latitude'
+        when 901 then
+          raise AddressError, 'invalid longitude'
+        when 902 then
+          raise AddressError, 'error parsing params'
+        when 9902 then
+          raise CredentialsError, 'invalid key'
+        when 9904 then
+          raise CredentialsError, 'key missing'
+        else
+          raise Error, "unknown error #{status}: #{msg}"
+        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:
+        super params.merge({:key => @key, :transaction => 'geocode', :ambiguities => 0})
+      end
+
+      def value(element)
+        element.value if element
+      end
+
+      def text(element)
+        element.text if element
+      end
+    end
+  end
+end

data/lib/graticule/geocoder/meta_carta.rb

@@ -0,0 +1,33 @@
+
+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, :output => 'locations'
+      end
+      
+    private
+
+      def check_error(xml) # :nodoc:
+        raise AddressError, 'bad location' unless xml.elements['Locations/Location']
+      end
+
+      def parse_response(parse_type, 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/multi.rb

@@ -0,0 +1,46 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+    class Multi
+      
+      # The Multi geocoder allows you to use multiple geocoders in succession.
+      #
+      #   geocoder = Graticule.service(:multi).new(
+      #     Graticule.service(:google).new("api_key"),
+      #     Graticule.service(:yahoo).new("api_key"),
+      #   )
+      #   geocoder.locate '49423' # <= tries geocoders in succession
+      #
+      # The Multi geocoder will try the geocoders in order if a Graticule::AddressError
+      # is raised.  You can customize this behavior by passing in a block to the Multi
+      # geocoder.  For example, to try the geocoders until one returns a result with a
+      # high enough precision:
+      #
+      #   geocoder = Graticule.service(:multi).new(geocoders) do |result|
+      #     [:address, :street].include?(result.precision)
+      #   end
+      #
+      # Geocoders will be tried in order until the block returned true for one of the results
+      #
+      def initialize(*geocoders, &acceptable)
+        @acceptable = acceptable || lambda { true }
+        @geocoders = geocoders.flatten
+      end
+      
+      def locate(address)
+        last_error = nil
+        @geocoders.each do |geocoder|
+          begin
+            result = geocoder.locate address
+            return result if @acceptable.call(result)
+          rescue Error => e
+            last_error = e
+          rescue Errno::ECONNREFUSED
+            logger.error("Connection refused to #{service}")
+          end
+        end
+        raise last_error || AddressError.new("Couldn't find '#{address}' with any of the services")
+      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(parse_type, 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,18 @@
+require 'rexml/document'
+
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # Abstract class for implementing REST geocoders. Passes on a REXML::Document
+    # to +check_errors+ and +parse_response+.
+    class Rest < Base
+      
+    private
+    
+      def prepare_response(response)
+        REXML::Document.new(response)
+      end
+      
+    end
+  end
+end

data/lib/graticule/geocoder/yahoo.rb

@@ -0,0 +1,102 @@
+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
+      #
+      # See http://developer.yahoo.com/search/rest.html
+      def initialize(appid)
+        @appid = appid
+        @url = URI.parse "http://api.local.yahoo.com/MapsService/V1/geocode"
+      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(*args)
+        case args.first
+          when :first then get :first, :location => extract_location(args[1]) 
+          when :all then get :all, :location => extract_location(args[1])
+          else get :first, :location => extract_location(args.first)
+        end
+      end
+      
+      def extract_location(address)
+        location = (address.is_a?(String) ? address : location_from_params(address).to_s(:country => false))
+        # yahoo pukes on line breaks
+        location.gsub("\n", ', ')
+      end
+      
+      def parse_response(parse_type, xml)
+        if parse_type == :all
+          locations = []
+          xml.elements['ResultSet'].each do |element|
+            locations << parse_location_xml(element)
+          end
+          return locations
+        else
+          return parse_location_xml(xml.elements['ResultSet/Result[1]'])
+        end
+      end
+
+      def parse_location_xml(element)
+        returning Location.new do |location|
+          location.precision = PRECISION[element.attributes['precision']] || :unknown
+
+          if element.attributes.include? 'warning' then
+            location.warning = element.attributes['warning']
+          end
+          location.latitude = element.elements['Latitude'].text.to_f
+          location.longitude = element.elements['Longitude'].text.to_f
+
+          location.street = element.elements['Address'].text.titleize unless element.elements['Address'].text.blank?
+          location.locality = element.elements['City'].text.titleize unless element.elements['City'].text.blank?
+          location.region = element.elements['State'].text
+          location.postal_code = element.elements['Zip'].text
+          location.country = element.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