geokit 1.7.1 → 1.8.0

data/lib/geokit/geocoders/base_ip.rb

@@ -0,0 +1,43 @@
+module Geokit
+  module Geocoders
+    class BaseIpGeocoder < Geocoder
+      # A number of non-routable IP ranges.
+      #
+      # --
+      # Sources for these:
+      #   RFC 3330: Special-Use IPv4 Addresses
+      #   The bogon list: http://www.cymru.com/Documents/bogon-list.html
+
+      NON_ROUTABLE_IP_RANGES = [
+        IPAddr.new('0.0.0.0/8'),      # "This" Network
+        IPAddr.new('10.0.0.0/8'),     # Private-Use Networks
+        IPAddr.new('14.0.0.0/8'),     # Public-Data Networks
+        IPAddr.new('127.0.0.0/8'),    # Loopback
+        IPAddr.new('169.254.0.0/16'), # Link local
+        IPAddr.new('172.16.0.0/12'),  # Private-Use Networks
+        IPAddr.new('192.0.2.0/24'),   # Test-Net
+        IPAddr.new('192.168.0.0/16'), # Private-Use Networks
+        IPAddr.new('198.18.0.0/15'),  # Network Interconnect Device Benchmark Testing
+        IPAddr.new('224.0.0.0/4'),    # Multicast
+        IPAddr.new('240.0.0.0/4')     # Reserved for future use
+      ].freeze
+
+      def self.valid_ip?(ip)
+        ip?(ip) && !private_ip_address?(ip)
+      end
+
+      def self.ip?(ip)
+        /^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})?$/.match(ip)
+      end
+
+      # Checks whether the IP address belongs to a private address range.
+      #
+      # This function is used to reduce the number of useless queries made to
+      # the geocoding service. Such queries can occur frequently during
+      # integration tests.
+      def self.private_ip_address?(ip)
+        NON_ROUTABLE_IP_RANGES.any? { |range| range.include?(ip) }
+      end
+    end
+  end
+end

data/lib/geokit/geocoders/bing.rb

@@ -0,0 +1,101 @@
+module Geokit
+  module Geocoders
+    # Bing geocoder implementation.  Requires the Geokit::Geocoders::bing variable to
+    # contain a Bing Maps API key.  Conforms to the interface set by the Geocoder class.
+    class BingGeocoder < Geocoder
+
+      private
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        url = submit_url(address)
+        res = call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        xml = transcode_to_utf8(res.body)
+        logger.debug "Bing geocoding. Address: #{address}. Result: #{xml}"
+        parse :xml, xml
+      end
+
+      def self.submit_url(address)
+        options = Geokit::Geocoders::bing_options
+        culture = options && options[:culture]
+        culture_string = culture ? "&c=#{culture}" : ''
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        "http://dev.virtualearth.net/REST/v1/Locations/#{URI.escape(address_str)}?key=#{Geokit::Geocoders::bing}#{culture_string}&o=xml"
+      end
+
+      def self.parse_xml(xml)
+        return GeoLoc.new if xml.elements['//Response/StatusCode'].try(:text) != '200'
+        loc = nil
+        # Bing can return multiple results as //Location elements.
+        # iterate through each and extract each location as a geoloc
+        xml.each_element('//Location') do |l|
+          extracted_geoloc = extract_location(l)
+          loc.nil? ? loc = extracted_geoloc : loc.all.push(extracted_geoloc)
+        end
+        loc
+      end
+
+      # extracts a single geoloc from a //Location element in the bing results xml
+      def self.extract_location(xml)
+        loc                 = GeoLoc.new
+        loc.provider        = 'bing'
+        set_address_components(loc, xml)
+        set_precision(loc, xml)
+        set_bounds(loc, xml)
+        loc.success         = true
+        loc
+      end
+
+      XML_MAPPINGS = {
+        :street_address => 'Address/AddressLine',
+        :full_address   => 'Address/FormattedAddress',
+        :city           => 'Address/Locality',
+        :state          => 'Address/AdminDistrict',
+        :province       => 'Address/AdminDistrict2',
+        :zip            => 'Address/PostalCode',
+        :country        => 'Address/CountryRegion',
+        :lat            => 'Point/Latitude',
+        :lng            => 'Point/Longitude'
+      }
+
+      def self.set_address_components(loc, xml)
+        set_mappings(loc, xml, XML_MAPPINGS)
+      end
+
+      def self.set_precision(loc, xml)
+        if xml.elements['.//Confidence']
+          loc.accuracy      = case xml.elements['.//Confidence'].text
+          when 'High'    then 8
+          when 'Medium'  then 5
+          when 'Low'     then 2
+          else             0
+          end
+        end
+
+        if xml.elements['.//EntityType']
+          loc.precision     = case xml.elements['.//EntityType'].text
+          when 'Sovereign'      then 'country'
+          when 'AdminDivision1' then 'state'
+          when 'AdminDivision2' then 'state'
+          when 'PopulatedPlace' then 'city'
+          when 'Postcode1'      then 'zip'
+          when 'Postcode2'      then 'zip'
+          when 'RoadBlock'      then 'street'
+          when 'Address'        then 'address'
+          else                    'unkown'
+          end
+        end
+      end
+
+      def self.set_bounds(loc, xml)
+        if suggested_bounds = xml.elements['.//BoundingBox']
+          bounds = suggested_bounds.elements
+          loc.suggested_bounds = Bounds.normalize(
+            [bounds['.//SouthLatitude'].text, bounds['.//WestLongitude'].text],
+            [bounds['.//NorthLatitude'].text, bounds['.//EastLongitude'].text])
+        end
+      end
+    end
+  end
+end

data/lib/geokit/geocoders/ca_geocoder.rb

@@ -0,0 +1,50 @@
+
+# Geocoder CA geocoder implementation.  Requires the Geokit::Geocoders::GEOCODER_CA variable to
+# contain true or false based upon whether authentication is to occur.  Conforms to the
+# interface set by the Geocoder class.
+#
+# Returns a response like:
+# <?xml version="1.0" encoding="UTF-8" ?>
+# <geodata>
+#   <latt>49.243086</latt>
+#   <longt>-123.153684</longt>
+# </geodata>
+module Geokit
+ module Geocoders
+   class CaGeocoder < Geocoder
+
+     private
+
+     # Template method which does the geocode lookup.
+     def self.do_geocode(loc)
+       raise ArgumentError('Geocoder.ca requires a GeoLoc argument') unless loc.is_a?(GeoLoc)
+       url = submit_url(loc)
+       res = call_geocoder_service(url)
+       return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+       xml = res.body
+       logger.debug "Geocoder.ca geocoding. Address: #{loc}. Result: #{xml}"
+       parse :xml, xml, loc
+    end
+
+    def self.parse_xml(xml, loc)
+       loc.lat = xml.elements['//latt'].text
+       loc.lng = xml.elements['//longt'].text
+       loc.success = true
+       loc
+     end
+
+     # Formats the request in the format acceptable by the CA geocoder.
+     def self.submit_url(loc)
+       args = []
+       args << "stno=#{loc.street_number}" if loc.street_address
+       args << "addresst=#{Geokit::Inflector::url_escape(loc.street_name)}" if loc.street_address
+       args << "city=#{Geokit::Inflector::url_escape(loc.city)}" if loc.city
+       args << "prov=#{loc.state}" if loc.state
+       args << "postal=#{loc.zip}" if loc.zip
+       args << "auth=#{Geokit::Geocoders::geocoder_ca}" if Geokit::Geocoders::geocoder_ca
+       args << "geoit=xml"
+       'http://geocoder.ca/?' + args.join('&')
+     end
+   end
+ end
+end

data/lib/geokit/{services → geocoders}/fcc.rb

@@ -6,11 +6,12 @@ module Geokit
       # Template method which does the reverse-geocode lookup.
       def self.do_reverse_geocode(latlng)
         latlng=LatLng.normalize(latlng)
-        res = self.call_geocoder_service("http://data.fcc.gov/api/block/find?format=json&latitude=#{Geokit::Inflector::url_escape(latlng.lat.to_s)}&longitude=#{Geokit::Inflector::url_escape(latlng.lng.to_s)}")
-        return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+        url = "http://data.fcc.gov/api/block/find?format=json&latitude=#{Geokit::Inflector::url_escape(latlng.lat.to_s)}&longitude=#{Geokit::Inflector::url_escape(latlng.lng.to_s)}"
+        res = call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
         json = res.body
         logger.debug "FCC reverse-geocoding. LL: #{latlng}. Result: #{json}"
-        return self.json2GeoLoc(json)
+        parse :json, json
       end
 
       # Template method which does the geocode lookup.
@@ -26,11 +27,8 @@ module Geokit
       # "State"=>{"name"=>"Indiana", "code"=>"IN", "FIPS"=>"18"},
       # "status"=>"OK"}
 
-      def self.json2GeoLoc(json, address="")
-        ret = nil
-        results = MultiJson.load(json)
-
-        if results.has_key?('Err') and results['Err']["msg"] == 'There are no results for this location'
+      def self.parse_json(results)
+        if results.has_key?('Err') && results['Err']["msg"] == 'There are no results for this location'
           return GeoLoc.new
         end
         # this should probably be smarter.
@@ -38,18 +36,17 @@ module Geokit
           raise Geokit::Geocoders::GeocodeError
         end
 
-        res = GeoLoc.new
-        res.provider      = 'fcc'
-        res.success       = true
-        res.precision     = 'block'
-        res.country_code  = 'US'
-        res.district      = results['County']['name']
-        res.district_fips = results['County']['FIPS']
-        res.state         = results['State']['code']
-        res.state_fips    = results['State']['FIPS']
-        res.block_fips    = results['Block']['FIPS']
-
-        res
+        loc = GeoLoc.new
+        loc.provider      = 'fcc'
+        loc.success       = true
+        loc.precision     = 'block'
+        loc.country_code  = 'US'
+        loc.district      = results['County']['name']
+        loc.district_fips = results['County']['FIPS']
+        loc.state         = results['State']['code']
+        loc.state_fips    = results['State']['FIPS']
+        loc.block_fips    = results['Block']['FIPS']
+        loc
       end
     end
 

data/lib/geokit/geocoders/free_geo_ip.rb

@@ -0,0 +1,34 @@
+module Geokit
+  module Geocoders
+    # Provides geocoding based upon an IP address.  The underlying web service is freegeoip.net
+    class FreeGeoIpGeocoder < BaseIpGeocoder
+      private
+
+      def self.do_geocode(ip)
+        return GeoLoc.new unless valid_ip?(ip)
+        url = "http://freegeoip.net/xml/#{ip}"
+        res = call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        parse :xml, res.body
+      end
+
+      XML_MAPPINGS = {
+        :city         => 'City',
+        :state        => 'RegionCode',
+        :zip          => 'ZipCode',
+        :country_code => 'CountryCode',
+        :lat          => 'Latitude',
+        :lng          => 'Longitude'
+      }
+
+      def self.parse_xml(xml)
+        loc = GeoLoc.new
+        loc.provider = 'freegeoip'
+        set_mappings(loc, xml.elements['Response'], XML_MAPPINGS)
+        loc.success = !!loc.city && !loc.city.empty?
+        loc
+      end
+    end
+
+  end
+end

data/lib/geokit/geocoders/geo_plugin.rb

@@ -0,0 +1,33 @@
+module Geokit
+  module Geocoders
+    # Provides geocoding based upon an IP address.  The underlying web service is geoplugin.net
+    class GeoPluginGeocoder < BaseIpGeocoder
+      private
+
+      def self.do_geocode(ip)
+        return GeoLoc.new unless valid_ip?(ip)
+        url = "http://www.geoplugin.net/xml.gp?ip=#{ip}"
+        res = call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+        parse :xml, res.body
+      end
+
+      XML_MAPPINGS = {
+        :city         => 'geoplugin_city',
+        :state        => 'geoplugin_region',
+        :country_code => 'geoplugin_countryCode',
+        :lat          => 'geoplugin_latitude',
+        :lng          => 'geoplugin_longitude'
+      }
+
+      def self.parse_xml(xml)
+        loc = GeoLoc.new
+        loc.provider = 'geoPlugin'
+        set_mappings(loc, xml.elements['geoPlugin'], XML_MAPPINGS)
+        loc.success = !!loc.city && !loc.city.empty?
+        loc
+      end
+    end
+
+  end
+end

data/lib/geokit/geocoders/geonames.rb

@@ -0,0 +1,53 @@
+module Geokit
+  module Geocoders
+    # Another geocoding web service
+    # http://www.geonames.org
+    class GeonamesGeocoder < Geocoder
+
+      private
+
+      # Template method which does the geocode lookup.
+      def self.do_geocode(address)
+        url = submit_url(address)
+        res = call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
+
+        xml = res.body
+        logger.debug "Geonames geocoding. Address: #{address}. Result: #{xml}"
+        parse :xml, xml
+      end
+
+      def self.submit_url(address)
+        address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
+        # geonames need a space seperated search string
+        address_str.gsub!(/,/, " ")
+        params = "/postalCodeSearch?placename=#{Geokit::Inflector::url_escape(address_str)}&maxRows=10"
+
+        if Geokit::Geocoders::geonames
+          "http://ws.geonames.net#{params}&username=#{Geokit::Geocoders::geonames}"
+        else
+          "http://ws.geonames.org#{params}"
+        end
+      end
+
+      XML_MAPPINGS = {
+        :city         => 'name',
+        :state        => 'adminName1',
+        :zip          => 'postalcode',
+        :country_code => 'countryCode',
+        :lat          => 'lat',
+        :lng          => 'lng'
+      }
+
+      def self.parse_xml(xml)
+        return GeoLoc.new unless xml.elements['geonames/totalResultsCount'].text.to_i > 0
+        loc = GeoLoc.new
+        loc.provider = 'genomes'
+        # only take the first result
+        set_mappings(loc, xml.elements['geonames/code'], XML_MAPPINGS)
+        loc.success = true
+        loc
+      end
+    end
+  end
+end

data/lib/geokit/{services/google3.rb → geocoders/google.rb}

@@ -1,17 +1,17 @@
 module Geokit
   module Geocoders
-    class GoogleGeocoder3 < Geocoder
+    class GoogleGeocoder < Geocoder
 
       private
       # Template method which does the reverse-geocode lookup.
       def self.do_reverse_geocode(latlng)
         latlng=LatLng.normalize(latlng)
-        submit_url = submit_url("/maps/api/geocode/json?sensor=false&latlng=#{Geokit::Inflector::url_escape(latlng.ll)}")
-        res = self.call_geocoder_service(submit_url)
-        return GeoLoc.new unless (res.is_a?(Net::HTTPSuccess) || res.is_a?(Net::HTTPOK))
+        url = submit_url("/maps/api/geocode/json?sensor=false&latlng=#{Geokit::Inflector::url_escape(latlng.ll)}")
+        res = call_geocoder_service(url)
+        return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
         json = res.body
         logger.debug "Google reverse-geocoding. LL: #{latlng}. Result: #{CGI.escape(json)}"
-        return self.json2GeoLoc(json)
+        parse :json, json
       end
 
       # Template method which does the geocode lookup.
@@ -43,15 +43,15 @@ module Geokit
         bias_str = options[:bias] ? construct_bias_string_from_options(options[:bias]) : ''
         language_str = options[:language] ? "&language=#{options[:language]}" : ''
         address_str = address.is_a?(GeoLoc) ? address.to_geocodeable_s : address
-        submit_url = submit_url("/maps/api/geocode/json?sensor=false&address=#{Geokit::Inflector::url_escape(address_str)}#{bias_str}#{language_str}")
+        url = submit_url("/maps/api/geocode/json?sensor=false&address=#{Geokit::Inflector::url_escape(address_str)}#{bias_str}#{language_str}")
 
-        res = self.call_geocoder_service(submit_url)
+        res = call_geocoder_service(url)
         return GeoLoc.new if !res.is_a?(Net::HTTPSuccess)
 
         json = res.body
         logger.debug "Google geocoding. Address: #{address}. Result: #{CGI.escape(json)}"
 
-        return self.json2GeoLoc(json, address)
+        parse :json, json
       end
 
       # This code comes from Googles Examples
@@ -64,13 +64,14 @@ module Geokit
         # create a signature using the private key and the URL
         rawSignature = OpenSSL::HMAC.digest('sha1', rawKey, urlToSign)
         # encode the signature into base64 for url use form.
-        return Base64.encode64(rawSignature).tr('+/','-_').gsub(/\n/, '')
+        Base64.encode64(rawSignature).tr('+/','-_').gsub(/\n/, '')
       end
 
 
       def self.submit_url(query_string)
-        if !Geokit::Geocoders::google_client_id.nil? and !Geokit::Geocoders::google_cryptographic_key.nil?
-          urlToSign = query_string + "&client=#{Geokit::Geocoders::google_client_id}" + "#{(!Geokit::Geocoders::google_channel.nil? ? ("&channel="+ Geokit::Geocoders::google_channel) : "")}"
+        if Geokit::Geocoders::google_client_id && Geokit::Geocoders::google_cryptographic_key
+          channel = Geokit::Geocoders::google_channel ? "&channel=#{Geokit::Geocoders::google_channel}" : ''
+          urlToSign = query_string + "&client=#{Geokit::Geocoders::google_client_id}" + channel
           signature = sign_gmap_bus_api_url(urlToSign, Geokit::Geocoders::google_cryptographic_key)
           "http://maps.googleapis.com" + urlToSign + "&signature=#{signature}"
         else
@@ -91,11 +92,9 @@ module Geokit
         end
       end
 
-      def self.json2GeoLoc(json, address="")
-        results = MultiJson.load(json)
-
+      def self.parse_json(results)
         case results['status']
-        when 'OVER_QUERY_LIMIT' then raise Geokit::TooManyQueriesError
+        when 'OVER_QUERY_LIMIT' then raise Geokit::Geocoders::TooManyQueriesError
         when 'ZERO_RESULTS' then return GeoLoc.new
         end
         # this should probably be smarter.
@@ -138,66 +137,69 @@ module Geokit
       }
 
       def self.single_json_to_geoloc(addr)
-        res = GeoLoc.new
-        res.provider = 'google3'
-        res.success = true
-        res.full_address = addr['formatted_address']
+        loc = GeoLoc.new
+        loc.provider = 'google'
+        loc.success = true
+        loc.full_address = addr['formatted_address']
+
+        set_address_components(loc, addr)
+        set_precision(loc, addr)
+        if loc.street_name
+          loc.street_address=[loc.street_number, loc.street_name].join(' ').strip
+        end
+
+        ll = addr['geometry']['location']
+        loc.lat = ll['lat'].to_f
+        loc.lng = ll['lng'].to_f
+
+        viewport = addr['geometry']['viewport']
+        ne = Geokit::LatLng.from_json(viewport['northeast'])
+        sw = Geokit::LatLng.from_json(viewport['southwest'])
+        loc.suggested_bounds = Geokit::Bounds.new(sw, ne)
+
+        loc
+      end
 
+      def self.set_address_components(loc, addr)
         addr['address_components'].each do |comp|
           case
           when comp['types'].include?("subpremise")
-            res.sub_premise = comp['short_name']
+            loc.sub_premise = comp['short_name']
           when comp['types'].include?("street_number")
-            res.street_number = comp['short_name']
+            loc.street_number = comp['short_name']
           when comp['types'].include?("route")
-            res.street_name = comp['long_name']
+            loc.street_name = comp['long_name']
           when comp['types'].include?("locality")
-            res.city = comp['long_name']
+            loc.city = comp['long_name']
           when comp['types'].include?("administrative_area_level_1")
-            res.state = comp['short_name']
-            res.province = comp['short_name']
+            loc.state = comp['short_name']
+            loc.province = comp['short_name']
           when comp['types'].include?("postal_code")
-            res.zip = comp['long_name']
+            loc.zip = comp['long_name']
           when comp['types'].include?("country")
-            res.country_code = comp['short_name']
-            res.country = comp['long_name']
+            loc.country_code = comp['short_name']
+            loc.country = comp['long_name']
           when comp['types'].include?("administrative_area_level_2")
-            res.district = comp['long_name']
+            loc.district = comp['long_name']
           when comp['types'].include?('neighborhood')
-            res.neighborhood = comp['short_name']
+            loc.neighborhood = comp['short_name']
           end
         end
-        if res.street_name
-          res.street_address=[res.street_number,res.street_name].join(' ').strip
-        end
-        res.accuracy = ACCURACY[addr['geometry']['location_type']]
-        res.precision=%w{unknown country state state city zip zip+4 street address building}[res.accuracy]
+      end
+
+      def self.set_precision(loc, addr)
+        loc.accuracy = ACCURACY[addr['geometry']['location_type']]
+        loc.precision=%w{unknown country state state city zip zip+4 street address building}[loc.accuracy]
         # try a few overrides where we can
-        if res.sub_premise
-          res.accuracy = 9
-          res.precision = 'building'
+        if loc.sub_premise
+          loc.accuracy = 9
+          loc.precision = 'building'
         end
-        if res.street_name && res.precision=='city'
-          res.precision = 'street'
-          res.accuracy = 7
+        if loc.street_name && loc.precision=='city'
+          loc.precision = 'street'
+          loc.accuracy = 7
         end
-
-        res.lat=addr['geometry']['location']['lat'].to_f
-        res.lng=addr['geometry']['location']['lng'].to_f
-
-        ne=Geokit::LatLng.new(
-          addr['geometry']['viewport']['northeast']['lat'].to_f,
-          addr['geometry']['viewport']['northeast']['lng'].to_f
-        )
-        sw=Geokit::LatLng.new(
-          addr['geometry']['viewport']['southwest']['lat'].to_f,
-          addr['geometry']['viewport']['southwest']['lng'].to_f
-        )
-        res.suggested_bounds = Geokit::Bounds.new(sw,ne)
-
-        res
       end
     end
-    Google3Geocoder = GoogleGeocoder3
   end
 end