projects.mako.cc - selectricity/blob - vendor/plugins/geokit/lib/geo_kit/geocoders.rb

   1 require 'net/http'
   2 require 'rexml/document'
   3 require 'yaml'
   4 require 'timeout'
   5
   6 module GeoKit
   7   # Contains a set of geocoders which can be used independently if desired.  The list contains:
   8   #
   9   # * Google Geocoder - requires an API key.
  10   # * Yahoo Geocoder - requires an API key.
  11   # * Geocoder.us - may require authentication if performing more than the free request limit.
  12   # * Geocoder.ca - for Canada; may require authentication as well.
  13   # * IP Geocoder - geocodes an IP address using hostip.info's web service.
  14   # * Multi Geocoder - provides failover for the physical location geocoders.
  15   #
  16   # Some configuration is required for these geocoders and can be located in the environment
  17   # configuration files.
  18   module Geocoders
  19     @@proxy_addr = nil
  20     @@proxy_port = nil
  21     @@proxy_user = nil
  22     @@proxy_pass = nil
  23     @@timeout = nil
  24     @@yahoo = 'REPLACE_WITH_YOUR_YAHOO_KEY'
  25     @@google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
  26     @@geocoder_us = false
  27     @@geocoder_ca = false
  28     @@provider_order = [:google,:us]
  29
  30     [:yahoo, :google, :geocoder_us, :geocoder_ca, :provider_order, :timeout,
  31      :proxy_addr, :proxy_port, :proxy_user, :proxy_pass].each do |sym|
  32       class_eval <<-EOS, __FILE__, __LINE__
  33         def self.#{sym}
  34           if defined?(#{sym.to_s.upcase})
  35             #{sym.to_s.upcase}
  36           else
  37             @@#{sym}
  38           end
  39         end
  40
  41         def self.#{sym}=(obj)
  42           @@#{sym} = obj
  43         end
  44       EOS
  45     end
  46
  47     # Error which is thrown in the event a geocoding error occurs.
  48     class GeocodeError < StandardError; end
  49
  50     # The Geocoder base class which defines the interface to be used by all
  51     # other geocoders.
  52     class Geocoder
  53       # Main method which calls the do_geocode template method which subclasses
  54       # are responsible for implementing.  Returns a populated GeoLoc or an
  55       # empty one with a failed success code.
  56       def self.geocode(address)
  57         res = do_geocode(address)
  58         return res.success ? res : GeoLoc.new
  59       end
  60
  61       # Call the geocoder service using the timeout if configured.
  62       def self.call_geocoder_service(url)
  63         timeout(GeoKit::Geocoders::timeout) { return self.do_get(url) } if GeoKit::Geocoders::timeout
  64         return self.do_get(url)
  65       rescue TimeoutError
  66         return nil
  67       end
  68
  69       protected
  70
  71       def self.logger() RAILS_DEFAULT_LOGGER; end
  72
  73       private
  74
  75       # Wraps the geocoder call around a proxy if necessary.
  76       def self.do_get(url)
  77         return Net::HTTP::Proxy(GeoKit::Geocoders::proxy_addr, GeoKit::Geocoders::proxy_port,
  78             GeoKit::Geocoders::proxy_user, GeoKit::Geocoders::proxy_pass).get_response(URI.parse(url))
  79       end
  80
  81       # Adds subclass' geocode method making it conveniently available through
  82       # the base class.
  83       def self.inherited(clazz)
  84         class_name = clazz.name.split('::').last
  85         src = <<-END_SRC
  86           def self.#{class_name.underscore}(address)
  87             #{class_name}.geocode(address)
  88           end
  89         END_SRC
  90         class_eval(src)
  91       end
  92     end
  93
  94     # Geocoder CA geocoder implementation.  Requires the GeoKit::Geocoders::GEOCODER_CA variable to
  95     # contain true or false based upon whether authentication is to occur.  Conforms to the
  96     # interface set by the Geocoder class.
  97     #
  98     # Returns a response like:
  99     # <?xml version="1.0" encoding="UTF-8" ?>
 100     # <geodata>
 101     #   <latt>49.243086</latt>
 102     #   <longt>-123.153684</longt>
 103     # </geodata>
 104     class CaGeocoder < Geocoder
 105
 106       private
 107
 108       # Template method which does the geocode lookup.
 109       def self.do_geocode(address)
 110         raise ArgumentError('Geocoder.ca requires a GeoLoc argument') unless address.is_a?(GeoLoc)
 111         url = construct_request(address)
 112         res = self.call_geocoder_service(url)
 113         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
 114         xml = res.body
 115         logger.debug "Geocoder.ca geocoding. Address: #{address}. Result: #{xml}"
 116         # Parse the document.
 117         doc = REXML::Document.new(xml)
 118         address.lat = doc.elements['//latt'].text
 119         address.lng = doc.elements['//longt'].text
 120         address.success = true
 121         return address
 122       rescue
 123         logger.error "Caught an error during Geocoder.ca geocoding call: "+$!
 124         return GeoLoc.new
 125       end
 126
 127       # Formats the request in the format acceptable by the CA geocoder.
 128       def self.construct_request(location)
 129         url = ""
 130         url += add_ampersand(url) + "stno=#{location.street_number}" if location.street_address
 131         url += add_ampersand(url) + "addresst=#{CGI.escape(location.street_name)}" if location.street_address
 132         url += add_ampersand(url) + "city=#{CGI.escape(location.city)}" if location.city
 133         url += add_ampersand(url) + "prov=#{location.state}" if location.state
 134         url += add_ampersand(url) + "postal=#{location.zip}" if location.zip
 135         url += add_ampersand(url) + "auth=#{GeoKit::Geocoders::geocoder_ca}" if GeoKit::Geocoders::geocoder_ca
 136         url += add_ampersand(url) + "geoit=xml"
 137         'http://geocoder.ca/?' + url
 138       end
 139
 140       def self.add_ampersand(url)
 141         url && url.length > 0 ? "&" : ""
 142       end
 143     end
 144
 145     # Google geocoder implementation.  Requires the GeoKit::Geocoders::GOOGLE variable to
 146     # contain a Google API key.  Conforms to the interface set by the Geocoder class.
 147     class GoogleGeocoder < Geocoder
 148
 149       private
 150
 151       # Template method which does the geocode lookup.
 152       def self.do_geocode(address)
 153         address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
 154         res = self.call_geocoder_service("http://maps.google.com/maps/geo?q=#{CGI.escape(address_str)}&output=xml&key=#{GeoKit::Geocoders::google}&oe=utf-8")
 155 #        res = Net::HTTP.get_response(URI.parse("http://maps.google.com/maps/geo?q=#{CGI.escape(address_str)}&output=xml&key=#{GeoKit::Geocoders::google}&oe=utf-8"))
 156         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
 157         xml=res.body
 158         logger.debug "Google geocoding. Address: #{address}. Result: #{xml}"
 159         doc=REXML::Document.new(xml)
 160
 161         if doc.elements['//kml/Response/Status/code'].text == '200'
 162           res = GeoLoc.new
 163           coordinates=doc.elements['//coordinates'].text.to_s.split(',')
 164
 165           #basics
 166           res.lat=coordinates[1]
 167           res.lng=coordinates[0]
 168           res.country_code=doc.elements['//CountryNameCode'].text
 169           res.provider='google'
 170
 171           #extended -- false if not not available
 172           res.city = doc.elements['//LocalityName'].text if doc.elements['//LocalityName']
 173           res.state = doc.elements['//AdministrativeAreaName'].text if doc.elements['//AdministrativeAreaName']
 174           res.full_address = doc.elements['//address'].text if doc.elements['//address'] # google provides it
 175           res.zip = doc.elements['//PostalCodeNumber'].text if doc.elements['//PostalCodeNumber']
 176           res.street_address = doc.elements['//ThoroughfareName'].text if doc.elements['//ThoroughfareName']
 177           # Translate accuracy into Yahoo-style token address, street, zip, zip+4, city, state, country
 178           # For Google, 1=low accuracy, 8=high accuracy
 179           address_details=doc.elements['//AddressDetails','urn:oasis:names:tc:ciq:xsdschema:xAL:2.0']
 180           accuracy = address_details ? address_details.attributes['Accuracy'].to_i : 0
 181           res.precision=%w{unknown country state state city zip zip+4 street address}[accuracy]
 182           res.success=true
 183
 184           return res
 185         else
 186           logger.info "Google was unable to geocode address: "+address
 187           return GeoLoc.new
 188         end
 189
 190         rescue
 191           logger.error "Caught an error during Google geocoding call: "+$!
 192           return GeoLoc.new
 193       end
 194     end
 195
 196     # Provides geocoding based upon an IP address.  The underlying web service is a hostip.info
 197     # which sources their data through a combination of publicly available information as well
 198     # as community contributions.
 199     class IpGeocoder < Geocoder
 200
 201       private
 202
 203       # Given an IP address, returns a GeoLoc instance which contains latitude,
 204       # longitude, city, and country code.  Sets the success attribute to false if the ip
 205       # parameter does not match an ip address.
 206       def self.do_geocode(ip)
 207         return GeoLoc.new unless /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
 208         url = "http://api.hostip.info/get_html.php?ip=#{ip}&position=true"
 209         response = self.call_geocoder_service(url)
 210         response.is_a?(Net::HTTPSuccess) ? parse_body(response.body) : GeoLoc.new
 211       rescue
 212         logger.error "Caught an error during HostIp geocoding call: "+$!
 213         return GeoLoc.new
 214       end
 215
 216       # Converts the body to YAML since its in the form of:
 217       #
 218       # Country: UNITED STATES (US)
 219       # City: Sugar Grove, IL
 220       # Latitude: 41.7696
 221       # Longitude: -88.4588
 222       #
 223       # then instantiates a GeoLoc instance to populate with location data.
 224       def self.parse_body(body) # :nodoc:
 225         yaml = YAML.load(body)
 226         res = GeoLoc.new
 227         res.provider = 'hostip'
 228         res.city, res.state = yaml['City'].split(', ')
 229         country, res.country_code = yaml['Country'].split(' (')
 230         res.lat = yaml['Latitude']
 231         res.lng = yaml['Longitude']
 232         res.country_code.chop!
 233         res.success = res.city != "(Private Address)"
 234         res
 235       end
 236     end
 237
 238     # Geocoder Us geocoder implementation.  Requires the GeoKit::Geocoders::GEOCODER_US variable to
 239     # contain true or false based upon whether authentication is to occur.  Conforms to the
 240     # interface set by the Geocoder class.
 241     class UsGeocoder < Geocoder
 242
 243       private
 244
 245       # For now, the geocoder_method will only geocode full addresses -- not zips or cities in isolation
 246       def self.do_geocode(address)
 247         address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
 248         url = "http://"+(GeoKit::Geocoders::geocoder_us || '')+"geocoder.us/service/csv/geocode?address=#{CGI.escape(address_str)}"
 249         res = self.call_geocoder_service(url)
 250         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
 251         data = res.body
 252         logger.debug "Geocoder.us geocoding. Address: #{address}. Result: #{data}"
 253         array = data.chomp.split(',')
 254
 255         if array.length == 6
 256           res=GeoLoc.new
 257           res.lat,res.lng,res.street_address,res.city,res.state,res.zip=array
 258           res.country_code='US'
 259           res.success=true
 260           return res
 261         else
 262           logger.info "geocoder.us was unable to geocode address: "+address
 263           return GeoLoc.new
 264         end
 265         rescue
 266           logger.error "Caught an error during geocoder.us geocoding call: "+$!
 267           return GeoLoc.new
 268       end
 269     end
 270
 271     # Yahoo geocoder implementation.  Requires the GeoKit::Geocoders::YAHOO variable to
 272     # contain a Yahoo API key.  Conforms to the interface set by the Geocoder class.
 273     class YahooGeocoder < Geocoder
 274
 275       private
 276
 277       # Template method which does the geocode lookup.
 278       def self.do_geocode(address)
 279         address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
 280         url="http://api.local.yahoo.com/MapsService/V1/geocode?appid=#{GeoKit::Geocoders::yahoo}&location=#{CGI.escape(address_str)}"
 281         res = self.call_geocoder_service(url)
 282         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
 283         xml = res.body
 284         doc = REXML::Document.new(xml)
 285         logger.debug "Yahoo geocoding. Address: #{address}. Result: #{xml}"
 286
 287         if doc.elements['//ResultSet']
 288           res=GeoLoc.new
 289
 290           #basic
 291           res.lat=doc.elements['//Latitude'].text
 292           res.lng=doc.elements['//Longitude'].text
 293           res.country_code=doc.elements['//Country'].text
 294           res.provider='yahoo'
 295
 296           #extended - false if not available
 297           res.city=doc.elements['//City'].text if doc.elements['//City'] && doc.elements['//City'].text != nil
 298           res.state=doc.elements['//State'].text if doc.elements['//State'] && doc.elements['//State'].text != nil
 299           res.zip=doc.elements['//Zip'].text if doc.elements['//Zip'] && doc.elements['//Zip'].text != nil
 300           res.street_address=doc.elements['//Address'].text if doc.elements['//Address'] && doc.elements['//Address'].text != nil
 301           res.precision=doc.elements['//Result'].attributes['precision'] if doc.elements['//Result']
 302           res.success=true
 303           return res
 304         else
 305           logger.info "Yahoo was unable to geocode address: "+address
 306           return GeoLoc.new
 307         end
 308
 309         rescue
 310           logger.info "Caught an error during Yahoo geocoding call: "+$!
 311           return GeoLoc.new
 312       end
 313     end
 314
 315     # Provides methods to geocode with a variety of geocoding service providers, plus failover
 316     # among providers in the order you configure.
 317     #
 318     # Goal:
 319     # - homogenize the results of multiple geocoders
 320     #
 321     # Limitations:
 322     # - currently only provides the first result. Sometimes geocoders will return multiple results.
 323     # - currently discards the "accuracy" component of the geocoding calls
 324     class MultiGeocoder < Geocoder
 325       private
 326
 327       # This method will call one or more geocoders in the order specified in the
 328       # configuration until one of the geocoders work.
 329       #
 330       # The failover approach is crucial for production-grade apps, but is rarely used.
 331       # 98% of your geocoding calls will be successful with the first call
 332       def self.do_geocode(address)
 333         GeoKit::Geocoders::provider_order.each do |provider|
 334           begin
 335             klass = GeoKit::Geocoders.const_get "#{provider.to_s.capitalize}Geocoder"
 336             res = klass.send :geocode, address
 337             return res if res.success
 338           rescue
 339             logger.error("Something has gone very wrong during geocoding, OR you have configured an invalid class name in GeoKit::Geocoders::provider_order. Address: #{address}. Provider: #{provider}")
 340           end
 341         end
 342         # If we get here, we failed completely.
 343         GeoLoc.new
 344       end
 345     end
 346   end
 347 end