aub-graticule 0.2.11

data/lib/graticule/distance/spherical.rb

@@ -0,0 +1,52 @@
+module Graticule
+  module Distance
+
+    #
+    # The Spherical Law of Cosines is the simplist though least accurate distance
+    # formula (earth isn't a perfect sphere).
+    #
+    class Spherical < DistanceFormula
+
+      # Calculate the distance between two Locations using the Spherical formula
+      #
+      #   Graticule::Distance::Spherical.distance(
+      #     Graticule::Location.new(:latitude => 42.7654, :longitude => -86.1085),
+      #     Graticule::Location.new(:latitude => 41.849838, :longitude => -87.648193)
+      #   )
+      #   #=> 101.061720831853
+      #
+      def self.distance(from, to, units = :miles)
+        from_longitude  = from.longitude.to_radians
+        from_latitude   = from.latitude.to_radians
+        to_longitude    = to.longitude.to_radians
+        to_latitude     = to.latitude.to_radians
+
+        Math.acos(
+            Math.sin(from_latitude) *
+            Math.sin(to_latitude) +
+
+            Math.cos(from_latitude) * 
+            Math.cos(to_latitude) *
+            Math.cos(to_longitude - from_longitude)
+        ) * EARTH_RADIUS[units.to_sym]
+      end
+
+      def self.to_sql(options)
+        options = {
+          :units => :miles,
+          :latitude_column => 'latitude',
+          :longitude_column => 'longitude'
+        }.merge(options)
+        %{(ACOS(
+            SIN(RADIANS(#{options[:latitude]})) *
+            SIN(RADIANS(#{options[:latitude_column]})) +
+            COS(RADIANS(#{options[:latitude]})) *
+            COS(RADIANS(#{options[:latitude_column]})) *
+            COS(RADIANS(#{options[:longitude_column]}) - RADIANS(#{options[:longitude]}))
+          ) * #{Graticule::Distance::EARTH_RADIUS[options[:units].to_sym]})
+        }.gsub("\n", '').squeeze(" ")
+      end
+  
+    end
+  end
+end

data/lib/graticule/distance/vincenty.rb

@@ -0,0 +1,76 @@
+module Graticule
+  module Distance
+
+    #
+    # The Vincenty Formula uses an ellipsoidal model of the earth, which is very accurate.
+    #
+    # Thanks to Chris Veness (http://www.movable-type.co.uk/scripts/LatLongVincenty.html)
+    # for distance formulas.
+    #
+    class Vincenty < DistanceFormula
+
+      # Calculate the distance between two Locations using the Vincenty formula
+      #
+      #   Graticule::Distance::Vincenty.distance(
+      #     Graticule::Location.new(:latitude => 42.7654, :longitude => -86.1085),
+      #     Graticule::Location.new(:latitude => 41.849838, :longitude => -87.648193)
+      #   )
+      #   #=> 101.070118000159
+      #
+      def self.distance(from, to, units = :miles)
+        from_longitude  = from.longitude.to_radians
+        from_latitude   = from.latitude.to_radians
+        to_longitude    = to.longitude.to_radians
+        to_latitude     = to.latitude.to_radians
+        
+        earth_major_axis_radius = EARTH_MAJOR_AXIS_RADIUS[units.to_sym]
+        earth_minor_axis_radius = EARTH_MINOR_AXIS_RADIUS[units.to_sym]
+
+        f = (earth_major_axis_radius - earth_minor_axis_radius) / earth_major_axis_radius
+
+        l = to_longitude - from_longitude
+        u1 = atan((1-f) * tan(from_latitude))
+        u2 = atan((1-f) * tan(to_latitude))
+        sin_u1 = sin(u1)
+        cos_u1 = cos(u1)
+        sin_u2 = sin(u2)
+        cos_u2 = cos(u2)
+
+        lambda = l
+        lambda_p = 2 * PI
+        iteration_limit = 20
+        while (lambda-lambda_p).abs > 1e-12 && (iteration_limit -= 1) > 0
+          sin_lambda = sin(lambda)
+          cos_lambda = cos(lambda)
+          sin_sigma = sqrt((cos_u2*sin_lambda) * (cos_u2*sin_lambda) + 
+            (cos_u1*sin_u2-sin_u1*cos_u2*cos_lambda) * (cos_u1*sin_u2-sin_u1*cos_u2*cos_lambda))
+          return 0 if sin_sigma == 0  # co-incident points
+          cos_sigma = sin_u1*sin_u2 + cos_u1*cos_u2*cos_lambda
+          sigma = atan2(sin_sigma, cos_sigma)
+          sin_alpha = cos_u1 * cos_u2 * sin_lambda / sin_sigma
+          cosSqAlpha = 1 - sin_alpha*sin_alpha
+          cos2SigmaM = cos_sigma - 2*sin_u1*sin_u2/cosSqAlpha
+
+          cos2SigmaM = 0 if cos2SigmaM.nan?  # equatorial line: cosSqAlpha=0 (§6)
+
+          c = f/16*cosSqAlpha*(4+f*(4-3*cosSqAlpha))
+          lambda_p = lambda
+          lambda = l + (1-c) * f * sin_alpha *
+            (sigma + c*sin_sigma*(cos2SigmaM+c*cos_sigma*(-1+2*cos2SigmaM*cos2SigmaM)))
+       end
+       # formula failed to converge (happens on antipodal points)
+       # We'll call Haversine formula instead.
+       return Haversine.distance(from, to, units) if iteration_limit == 0 
+
+       uSq = cosSqAlpha * (earth_major_axis_radius**2 - earth_minor_axis_radius**2) / (earth_minor_axis_radius**2)
+       a = 1 + uSq/16384*(4096+uSq*(-768+uSq*(320-175*uSq)))
+       b = uSq/1024 * (256+uSq*(-128+uSq*(74-47*uSq)))
+       delta_sigma = b*sin_sigma*(cos2SigmaM+b/4*(cos_sigma*(-1+2*cos2SigmaM*cos2SigmaM)-
+         b/6*cos2SigmaM*(-3+4*sin_sigma*sin_sigma)*(-3+4*cos2SigmaM*cos2SigmaM)))
+         
+        earth_minor_axis_radius * a * (sigma-delta_sigma)
+      end
+  
+    end
+  end
+end

data/lib/graticule/distance.rb

@@ -0,0 +1,18 @@
+module Graticule
+  module Distance
+    
+    EARTH_RADIUS = { :kilometers => 6378.135, :miles => 3963.1676 }
+    # WGS-84 numbers
+    EARTH_MAJOR_AXIS_RADIUS = { :kilometers => 6378.137, :miles => 3963.19059 }
+    EARTH_MINOR_AXIS_RADIUS = { :kilometers => 6356.7523142, :miles => 3949.90276 }
+
+    class DistanceFormula
+      include Math
+      extend Math
+       
+      def initialize
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/graticule/geocoder/base.rb

@@ -0,0 +1,116 @@
+require 'open-uri'
+
+module Graticule #:nodoc:
+  module Geocoder
+
+    # Abstract class for implementing geocoders.
+    #
+    # === 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.
+    #
+    # Optionally, you can also override
+    #
+    # * +prepare_response+:: Convert the string response into a different format
+    #   that gets passed on to +check_error+ and +parse_response+.
+    #
+    # If you have extra URL paramaters (application id, output type) or need to
+    # perform URL customization, override +make_url+.
+    #
+    #   class FakeGeocoder < Base
+    #   
+    #     def initialize(appid)
+    #       @appid = appid
+    #       @url = URI.parse 'http://example.com/test'
+    #     end
+    #
+    #     def locate(query)
+    #       get :q => query
+    #     end
+    #   
+    #   private
+    #   
+    #     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(response)
+    #       # return Location
+    #     end
+    #   
+    #   end
+    #
+    class Base
+      USER_AGENT = "Mozilla/5.0 (compatible; Graticule/#{Graticule::Version::STRING}; http://graticule.rubyforge.org)"
+
+      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
+
+      # Check for errors in +response+ and raise appropriate error, if any.
+      # Must return if no error could be found.
+      def check_error(response)
+        raise NotImplementedError
+      end
+
+      # Performs a GET request with +params+.  Calls +check_error+ and returns
+      # the result of +parse_response+.
+      def get(params = {})
+        response = prepare_response(make_url(params).open('User-Agent' => USER_AGENT).read)
+        check_error(response)
+        if params[:multiple]
+          parse_response(response)
+        else
+          parse_response(response)[0]
+        end
+      rescue OpenURI::HTTPError => e
+        check_error(prepare_response(e.io.read))
+        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
+      
+      # Override to convert the response to something besides a String, which
+      # will get passed to +check_error+ and +parse_response+.
+      def prepare_response(response)
+        response
+      end
+
+      # Must parse results from +response+ into a Location.
+      def parse_response(response)
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

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,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(xml) #:nodoc:
+        location = Location.new
+        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
+        [location]
+      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,51 @@
+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(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
+
+        [location]
+      end
+
+      def check_error(xml) #:nodoc:
+        raise AddressError, xml.text if xml.text =~ /couldn't find this address! sorry/
+        raise Error, xml.text if xml.text =~ /Your browser sent a request that this server could not understand./
+        raise Error, xml.text if !(xml.text =~ /geo:Point/)
+      end
+
+    end
+  end
+end

data/lib/graticule/geocoder/google.rb

@@ -0,0 +1,100 @@
+
+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(address)
+        get :q => address.is_a?(String) ? address : location_from_params(address).to_s
+      end
+
+    private
+
+      # Extracts a Location from +xml+.
+      def parse_response(xml) #:nodoc:
+        longitude, latitude, = xml.elements['/kml/Response/Placemark/Point/coordinates'].text.split(',').map { |v| v.to_f }
+        location = Location.new(:latitude => latitude, :longitude => longitude)
+        address = REXML::XPath.first(xml, '//xal:AddressDetails',
+          'xal' => "urn:oasis:names:tc:ciq:xsdschema:xAL:2.0")
+
+        if address
+          location.street = value(address.elements['.//ThoroughfareName/text()'])
+          location.locality = value(address.elements['.//LocalityName/text()'])
+          location.region = value(address.elements['.//AdministrativeAreaName/text()'])
+          location.postal_code = value(address.elements['.//PostalCodeNumber/text()'])
+          location.country = value(address.elements['.//CountryNameCode/text()'])
+          location.precision = PRECISION[address.attribute('Accuracy').value.to_i] || :unknown
+        end
+        [location]
+      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(response) #:nodoc:
+        location = Location.new
+        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
+        [location]
+      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,44 @@
+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(js)
+        location = Location.new
+        coordinates = js.match(/map.centerAndZoom\(new GPoint\((.+?), (.+?)\)/)
+        location.longitude = coordinates[1].to_f
+        location.latitude = coordinates[2].to_f
+        [location]
+      end
+    end
+  end
+end

data/lib/graticule/geocoder/mapquest.rb

@@ -0,0 +1,96 @@
+require 'ruby-debug'
+
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # Mapquest requires both a client id and a password, which you can
+    # get by registering at:
+    # http://developer.mapquest.com/Home/Register?_devAPISignup_WAR_devAPISignup_action=signup&_devAPISignup_WAR_devAPISignup_clientType=Developer
+    #
+    # mq = Graticule.service(:mapquest).new(CLIENT_ID, PASSWORD)
+    # location = gg.locate('44 Allen Rd., Lovell, ME 04051') 
+    # [42.78942, -86.104424]
+    #
+    class Mapquest < Rest 
+      # I would link to the documentation here, but there is none that will do anything but confuse you.
+
+      PRECISION = {
+        'L1' => :address,
+        'I1' => :street,
+        'B1' => :street,
+        'B2' => :street,
+        'B3' => :street,
+        'Z3' => :zip,
+        'Z4' => :zip,
+        'Z2' => :zip,
+        'Z1' => :zip,
+        'A5' => :city,
+        'A4' => :county,
+        'A3' => :state,
+        'A1' => :country
+      }
+
+      def initialize(client_id, password)
+        @password = password
+        @client_id = client_id
+        @url = URI.parse('http://geocode.dev.mapquest.com/mq/mqserver.dll')
+      end
+
+      # Locates +address+ returning a Location
+      def locate(address)
+        do_locate(address, false)
+      end
+
+      def locate_all(address)
+        do_locate(address, true)
+      end
+
+      protected
+
+      def do_locate(address, multi)
+        get(:q => address.is_a?(String) ? address : location_from_params(address).to_s, :multiple => multi)
+      end
+
+      def make_url(params) #:nodoc
+        query = "e=5&<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?><Geocode Version=\"1\">#{address_string(params[:q])}#{authentication_string}</Geocode>"
+        url = @url.dup
+        url.query = URI.escape(query)
+        url
+      end
+
+      # Extracts a location from +xml+.
+      def parse_response(xml) #:nodoc:
+        locations = []
+        REXML::XPath.each(xml, '/GeocodeResponse/LocationCollection/GeoAddress') do |elem|
+          longitude = elem.elements['LatLng/Lng'].text.to_f
+          latitude = elem.elements['LatLng/Lat'].text.to_f
+          location = Location.new(:latitude => latitude, :longitude => longitude)
+          location.street = value(elem.elements['Street'])
+          location.locality = value(elem.elements['AdminArea5'])
+          location.region = value(elem.elements['AdminArea3'])
+          location.postal_code = value(elem.elements['PostalCode'])
+          location.country = value(elem.elements['AdminArea1'])
+          location.precision = PRECISION[value(elem.elements['ResultCode'])[0,2]]
+          locations << location
+        end
+        locations
+      end
+
+      # Extracts and raises any errors in +xml+
+      def check_error(xml) #:nodoc
+      end
+
+      def value(element)
+        element.text if element
+      end
+
+      def authentication_string
+        "<Authentication Version=\"2\"><Password>#{@password}</Password><ClientId>#{@client_id}</ClientId></Authentication>"
+      end
+
+      def address_string(query)
+        "<Address><Street>#{query}</Street></Address><GeocodeOptionsCollection Count=\"0\"/>"
+      end
+    end
+  end
+end