collectiveidea-graticule 0.2.12

data/lib/graticule/geocoder/multimap.rb

@@ -0,0 +1,73 @@
+module Graticule #:nodoc:
+  module Geocoder #:nodoc:
+
+    # Multimap geocoding API
+    
+    class Multimap < Rest
+      
+      # This precision information is not complete.
+      # More details should be implemented from:
+      # http://www.multimap.com/share/documentation/clientzone/gqcodes.htm
+      
+      PRECISION = {
+        "6"=> :country,
+        "5" => :state,
+        "4" => :postal_code,
+        "3" => :city,
+        "2" => :street,
+        "1" => :address
+      }
+      
+      # Web services initializer.
+      #
+      # The +api_key+ is the Open API key that uniquely identifies your
+      # application.
+      #
+      # See http://www.multimap.com/openapi/
+      
+      def initialize(api_key)
+        @api_key = api_key
+        @url = URI.parse "http://clients.multimap.com/API/geocode/1.2/#{@api_key}"
+      end
+      
+      # Returns a location for an address in the form of a String, Hash or Location.
+      
+      def locate(address)
+        location = address.is_a?(String) ? address : location_from_params(address)
+        case location
+        when String
+          get :qs => location
+        when Location
+          get "street" => location.street, 
+              "region" => location.region, 
+              "city" => location.city, 
+              "postalCode" => location.postal_code, 
+              "countryCode" => location.country
+        end
+      end
+      
+      def parse_response(xml)
+        r = xml.elements['Results/Location[1]']
+        returning Location.new do |location|
+          
+          location.precision = PRECISION[r.attributes['geocodeQuality']] || :unknown
+          
+          location.street = r.elements['Address/Street'].text.titleize unless r.elements['Address/Street'].nil?
+          location.locality = r.elements['Address/Areas/Area'].text.titleize unless r.elements['Address/Areas/Area'].nil?
+          location.region = r.elements['Address/State'].text.titleize unless r.elements['Address/State'].nil?
+          location.postal_code = r.elements['Address/PostalCode'].text unless r.elements['Address/PostalCode'].nil?
+          location.country = r.elements['Address/CountryCode'].text
+          
+          location.latitude = r.elements['Point/Lat'].text.to_f
+          location.longitude = r.elements['Point/Lon'].text.to_f
+        end
+      end
+      
+      def check_error(xml)
+        error = xml.elements['Results'].attributes['errorCode']
+        raise Error, error unless error.nil?
+      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,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,84 @@
+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(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

@@ -0,0 +1,61 @@
+module Graticule
+  
+  # A geographic location
+  class Location
+    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, :precision].inject({}) do |result,attr|
+        result[attr] = self.send(attr) unless self.send(attr).blank?
+        result
+      end
+    end
+    
+    def blank?
+      attributes.except(:precision).empty?
+    end
+    
+    # Returns an Array with latitude and longitude.
+    def coordinates
+      [latitude, longitude]
+    end
+    
+    def ==(other)
+      other.respond_to?(:attributes) ? attributes == other.attributes : false
+    end
+    
+    # Calculate the distance to another location.  See the various Distance formulas
+    # for more information
+    def distance_to(destination, options = {})
+      options = {:formula => :haversine, :units => :miles}.merge(options)
+      "Graticule::Distance::#{options[:formula].to_s.titleize}".constantize.distance(self, destination, options[:units])
+    end
+    
+    # Where would I be if I dug through the center of the earth?
+    def antipode
+      Location.new :latitude => -latitude, :longitude => longitude + (longitude >= 0 ? -180 : 180)
+    end
+    alias_method :antipodal_location, :antipode
+    
+    def to_s(options = {})
+      options = {:coordinates => false, :country => true}.merge(options)
+      result = ""
+      result << "#{street}\n" if street
+      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
+    
+  end
+end

data/lib/graticule/version.rb

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

data/site/index.html

@@ -0,0 +1,114 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+	<title>Graticule</title>
+	<link rel="stylesheet" type="text/css" href="http://opensoul.org/stylesheets/code.css" />
+	<link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
+    <link href="http://opensoul.org/stylesheets/ci.css" rel="stylesheet" type="text/css" />
+    <script src="http://opensoul.org/javascripts/code_highlighter.js" type="text/javascript"></script>
+    <script src="http://opensoul.org/javascripts/ruby.js" type="text/javascript"></script>
+</head>
+
+<body>
+<div id="collectiveidea">
+    <a href="http://collectiveidea.com"><img src="http://opensoul.org/images/header_logo.gif" alt="Collective Idea" class="logo" width="17" height="22" /></a>
+    <ul class="links">
+        <li><a href="http://daniel.collectiveidea.com/blog">Daniel</a></li>
+        <li><a href="http://opensoul.org">Brandon</a></li>
+        <li class="name"><a href="http://collectiveidea.com"><img src="http://opensoul.org/images/header_collectiveidea.gif" alt="Collective Idea" width="123" height="21" /></a></li>
+    </ul>
+</div>
+<div id="main">
+    <div id="header">
+        <h1><a href="/">Graticule</a></h1>
+        <ul id="nav">
+            <li><a href="graticule">API Docs</a></li>
+            <li><a href="plugin.html">Rails Plugin</a></li>
+            <li><a href="http://rubyforge.org/projects/graticule">RubyForge</a></li>
+            <li><a href="http://opensoul.org/tags/geocoding">Blog</a></li>
+        </ul>
+    </div>
+    <div id="content">
+        <dl lang="en" xml:lang="en">
+    		<dt><strong>grat·i·cule</strong>, <span class="pronunciation">|ˈgratəˌkyoōl|</span>,
+    		    <em><abbr title="noun">n.</abbr></em>
+    		    <span class="description">technical</span>
+    		</dt>
+            <dd><em>Navigation.</em> a network of parallels and meridians on a map or chart.</dd>
+        </dl>
+        
+        <p>Graticule is a geocoding API for looking up address coordinates and performing distance calculations. It supports many popular APIs, including:</p>
+        
+        <ul>
+            <li>Yahoo</li>
+            <li>Google</li>
+            <li>Geocoder.ca</li>
+            <li>Geocoder.us</li>
+            <li>PostcodeAnywhere</li>
+            <li>MetaCarta</li>
+        </ul>
+        
+        <p>There is a <a href="plugin.html">companion Rails plugin</a> that makes geocoding seem like magic.</p>
+        
+        <h2>Example</h2>
+        
+        <pre><code class="ruby">require 'rubygems'
+require 'graticule'
+geocoder = Graticule.service(:google).new "api_key"
+location = geocoder.locate "1600 Amphitheatre Parkway, Mountain View, CA"
+location.coordinates    #=> [37.423021, -122.083739]
+location.country        #=> "US"</code></pre>
+
+        <p>See the <a href="graticule">API documentation</a> for more details.</p>
+
+        <h2>International Support</h2>
+        
+        <p>Graticule supports several services with international support. The international geocoders require slightly more structured data than the US ones:</p>
+        
+        <pre><code class="ruby">g = Graticule.service(:local_search_maps).new
+location = g.locate :street => '48 Leicester Square', :locality => 'London', :country => 'UK'
+location.coordinates  #=> [51.510036, -0.130427]</code></pre>
+
+        <h2>Distance Calculation</h2>
+        
+        <p>Graticule includes 3 different distance formulas, Spherical (simplest but least accurate), Vincenty (most accurate and most complicated), and Haversine (somewhere inbetween).</p>
+
+        <pre><code class="ruby">location = geocoder.locate("Holland, MI")
+location.distance_to(geocoder.locate("Chicago, IL"))
+#=> 101.997458788177</code></pre>
+
+        <h2>Command Line</h2>
+        <p>Graticule also includes a command line interface to the various geocoders:</p>
+        
+        <pre>
+$ geocode -s yahoo -a yahookey Washington, DC
+Washington, DC US
+latitude: 38.895222, longitude: -77.036758</pre>
+
+        <h2>Installation</h2>
+        
+        <p>Install the gem by executing:</p>
+        
+        <pre>gem install graticule</pre>
+        
+        <p>Or, download it from <a href="http://rubyforge.org/frs/?group_id=2643">RubyForge</a>.</p>
+        
+        <h2>Contributing</h2>
+        
+        <p>Contributions are welcome and appreciated!  Join the <a href="http://rubyforge.org/mailman/listinfo/graticule-users">mailing list</a> and grab the source from:</p>
+        
+        <pre>http://source.collectiveidea.com/public/geocode/trunk/</pre>
+    </div>
+</div>
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
+</script>
+<script type="text/javascript">
+_uacct = "UA-194397-7";
+urchinTracker();
+</script>
+</body>
+</html>

data/site/plugin.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+	<title>acts_as_geocodable - Graticule</title>
+	<link rel="stylesheet" type="text/css" href="http://opensoul.org/stylesheets/code.css" />
+	<link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
+    <link href="http://opensoul.org/stylesheets/ci.css" rel="stylesheet" type="text/css" />
+    <script src="http://opensoul.org/javascripts/code_highlighter.js" type="text/javascript"></script>
+    <script src="http://opensoul.org/javascripts/ruby.js" type="text/javascript"></script>
+</head>
+
+<body>
+<div id="collectiveidea">
+    <a href="http://collectiveidea.com"><img src="http://opensoul.org/images/header_logo.gif" alt="Collective Idea" class="logo" width="17" height="22" /></a>
+    <ul class="links">
+        <li><a href="http://daniel.collectiveidea.com/blog">Daniel</a></li>
+        <li><a href="http://opensoul.org">Brandon</a></li>
+        <li class="name"><a href="http://collectiveidea.com"><img src="http://opensoul.org/images/header_collectiveidea.gif" alt="Collective Idea" width="123" height="21" /></a></li>
+    </ul>
+</div>
+<div id="main">
+    <div id="header">
+        <h1><a href="/">Graticule</a> » acts_as_geocodable</h1>
+        <ul id="nav">
+            <li><a href="acts_as_geocodable">API Docs</a></li>
+            <li><a href="plugin.html">Rails Plugin</a></li>
+            <li><a href="http://rubyforge.org/projects/graticule">RubyForge</a></li>
+            <li><a href="http://opensoul.org/tags/geocoding">Blog</a></li>
+        </ul>
+    </div>
+    <div id="content">
+        <p>acts_as_geocodable is a Rails plugin that makes your applications geo-aware. A picture (er, example) is worth a thousand words:</p>
+        
+        <h2>Examples</h2>
+        
+        <pre><code class="ruby">event = Event.create :street =&gt; &quot;777 NE Martin Luther King, Jr. Blvd.&quot;,
+  :locality =&gt; &quot;Portland&quot;, :region =&gt; &quot;Oregon&quot;, :postal_code =&gt; 97232
+
+# how far am I from RailsConf 2007?
+event.distance_to &quot;49423&quot; #=&gt; 1807.66560483205
+
+# Find our new event, and any other ones in the area
+Event.find(:all, :within =&gt; 50, :origin =&gt; &quot;97232&quot;)
+
+# Find the nearest restaurant with beer
+Restaurant.find(:nearest, :origin =&gt; event, :conditions =&gt; 'beer = true')</code></pre>
+
+
+        <p>See the <a href="acts_as_geocodable">API documentation</a> for more details.</p>
+
+        <h2>IP-based geocoding</h2>
+        
+        <p>acts_as_geocodable adds a <code>remote_location</code> method to your Rails controllers for retrieving a user's location based on their remote IP address.</p>
+
+        <pre><code class="ruby">@nearest_store = Store.find(:nearest, :origin =&gt; remote_location) if remote_location</code></pre>
+        
+        <p>Don't rely too heavily on remote_location because the location of many IP addresses cannot be determined through <a href="http://hostip.info">HostIP</a>.
+
+        <h2>Installation</h2>
+        
+        <p>Install the plugin by executing:</p>
+        
+        <pre>script/plugin install -x http://source.collectiveidea.com/public/rails/plugins/acts_as_geocodable</pre>
+        
+        <h2>Contributing</h2>
+        
+        <p>Contributions are welcome and appreciated!  Grab the source from:</p>
+        
+        <pre>http://source.collectiveidea.com/public/rails/plugins/acts_as_geocodable</pre>
+    </div>
+</div>
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
+</script>
+<script type="text/javascript">
+_uacct = "UA-194397-7";
+urchinTracker();
+</script>
+</body>
+</html>