geokit 1.7.1 → 1.8.0

data/fixtures/vcr_cassettes/ripe_geocode.yml

@@ -0,0 +1,66 @@
+--- 
+http_interactions: 
+- request: 
+    method: get
+    uri: http://stat.ripe.net/data/geoloc/data.json?resource=74.125.237.209
+    body: 
+      encoding: US-ASCII
+      string: ""
+    headers: 
+      Accept: 
+      - "*/*"
+      User-Agent: 
+      - Ruby
+  response: 
+    status: 
+      code: 200
+      message: OK
+    headers: 
+      Vary: 
+      - Cookie, Accept-Encoding
+      Content-Type: 
+      - application/json; charset=utf-8
+      Set-Cookie: 
+      - stat-session=36d43b5353a80b7f74c583a0bda4ea17; expires=Fri, 27-Dec-2013 15:12:05 GMT; Max-Age=1209600; Path=/
+      Transfer-Encoding: 
+      - chunked
+      Date: 
+      - Fri, 13 Dec 2013 15:12:05 GMT
+      Server: 
+      - lighttpd/1.4.32
+    body: 
+      encoding: US-ASCII
+      string: |-
+        {
+            "cached": true, 
+            "data": {
+                "locations": [
+                    {
+                        "city": "Mountain View", 
+                        "country": "CA(US)", 
+                        "covered_percentage": 100, 
+                        "latitude": 37.419199999999996, 
+                        "longitude": -122.0574, 
+                        "prefixes": [
+                            "74.125.192.0/18"
+                        ]
+                    }
+                ], 
+                "query_time": "2013-11-01T00:00:00", 
+                "resource": "74.125.237.209", 
+                "unknown_percentage": 0.0
+            }, 
+            "data_call_status": "supported", 
+            "messages": [], 
+            "process_time": 3, 
+            "query_id": "ed345b04-6408-11e3-9667-782bcb346712", 
+            "see_also": [], 
+            "server_id": "stat-app2", 
+            "status": "ok", 
+            "status_code": 200, 
+            "time": "2013-12-13T15:12:05.342893", 
+            "version": "2.0"
+        }
+    http_version: 
+  recorded_at: Fri, 13 Dec 2013 15:12:02 GMT
+recorded_with: VCR 2.8.0

data/fixtures/vcr_cassettes/ripe_geocode_au.yml

@@ -0,0 +1,66 @@
+--- 
+http_interactions: 
+- request: 
+    method: get
+    uri: http://stat.ripe.net/data/geoloc/data.json?resource=118.210.24.54
+    body: 
+      encoding: US-ASCII
+      string: ""
+    headers: 
+      Accept: 
+      - "*/*"
+      User-Agent: 
+      - Ruby
+  response: 
+    status: 
+      code: 200
+      message: OK
+    headers: 
+      Vary: 
+      - Cookie, Accept-Encoding
+      Content-Type: 
+      - application/json; charset=utf-8
+      Set-Cookie: 
+      - stat-session=8dcf7a7e881c4ec64aa1a7dfcc1335c9; expires=Fri, 27-Dec-2013 15:14:20 GMT; Max-Age=1209600; Path=/
+      Transfer-Encoding: 
+      - chunked
+      Date: 
+      - Fri, 13 Dec 2013 15:14:20 GMT
+      Server: 
+      - lighttpd/1.4.32
+    body: 
+      encoding: US-ASCII
+      string: |-
+        {
+            "cached": true, 
+            "data": {
+                "locations": [
+                    {
+                        "city": "Adelaide", 
+                        "country": "AU", 
+                        "covered_percentage": 100, 
+                        "latitude": -34.928699999999999, 
+                        "longitude": 138.5986, 
+                        "prefixes": [
+                            "118.210.16.0/20"
+                        ]
+                    }
+                ], 
+                "query_time": "2013-11-01T00:00:00", 
+                "resource": "118.210.24.54", 
+                "unknown_percentage": 0.0
+            }, 
+            "data_call_status": "supported", 
+            "messages": [], 
+            "process_time": 3, 
+            "query_id": "3dfcd85e-6409-11e3-a402-782bcb346712", 
+            "see_also": [], 
+            "server_id": "stat-app2", 
+            "status": "ok", 
+            "status_code": 200, 
+            "time": "2013-12-13T15:14:20.874304", 
+            "version": "2.0"
+        }
+    http_version: 
+  recorded_at: Fri, 13 Dec 2013 15:14:18 GMT
+recorded_with: VCR 2.8.0

data/geokit.gemspec

@@ -6,7 +6,7 @@ require 'geokit/version'
 Gem::Specification.new do |spec|
   spec.name          = "geokit"
   spec.version       = Geokit::VERSION
-  spec.authors       = ["Michael Noack, James Cox, Andre Lewis & Bill Eisenhauer"]
+  spec.authors       = ["Michael Noack", "James Cox", "Andre Lewis", "Bill Eisenhauer"]
   spec.email         = ["michael+geokit@noack.com.au"]
   spec.description   = %q{Geokit provides geocoding and distance calculation in an easy-to-use API}
   spec.summary       = %q{Geokit: encoding and distance calculation gem}

data/lib/geokit.rb

@@ -22,5 +22,10 @@ end
 
 path = File.expand_path(File.dirname(__FILE__))
 $:.unshift path unless $:.include?(path)
+require 'geokit/core_ext'
 require 'geokit/geocoders'
 require 'geokit/mappable'
+require 'geokit/bounds'
+require 'geokit/lat_lng'
+require 'geokit/geo_loc'
+require 'geokit/polygon'

data/lib/geokit/bounds.rb

@@ -0,0 +1,96 @@
+module Geokit
+  # Bounds represents a rectangular bounds, defined by the SW and NE corners
+  class Bounds
+    # sw and ne are LatLng objects
+    attr_accessor :sw, :ne
+
+    # provide sw and ne to instantiate a new Bounds instance
+    def initialize(sw,ne)
+      raise ArgumentError if !(sw.is_a?(Geokit::LatLng) && ne.is_a?(Geokit::LatLng))
+      @sw,@ne=sw,ne
+    end
+
+    #returns the a single point which is the center of the rectangular bounds
+    def center
+      @sw.midpoint_to(@ne)
+    end
+
+    # a simple string representation:sw,ne
+    def to_s
+      "#{@sw.to_s},#{@ne.to_s}"
+    end
+
+    # a two-element array of two-element arrays: sw,ne
+    def to_a
+      [@sw.to_a, @ne.to_a]
+    end
+
+    # Returns true if the bounds contain the passed point.
+    # allows for bounds which cross the meridian
+    def contains?(point)
+      point=Geokit::LatLng.normalize(point)
+      res = point.lat > @sw.lat && point.lat < @ne.lat
+      if crosses_meridian?
+        res &= point.lng < @ne.lng || point.lng > @sw.lng
+      else
+        res &= point.lng < @ne.lng && point.lng > @sw.lng
+      end
+      res
+    end
+
+    # returns true if the bounds crosses the international dateline
+    def crosses_meridian?
+      @sw.lng > @ne.lng
+    end
+
+    # Returns true if the candidate object is logically equal.  Logical equivalence
+    # is true if the lat and lng attributes are the same for both objects.
+    def ==(other)
+      return false unless other.is_a?(Bounds)
+      sw == other.sw && ne == other.ne
+    end
+
+    # Equivalent to Google Maps API's .toSpan() method on GLatLng's.
+    #
+    # Returns a LatLng object, whose coordinates represent the size of a rectangle
+    # defined by these bounds.
+    def to_span
+      lat_span = (@ne.lat - @sw.lat).abs
+      lng_span = (crosses_meridian? ? 360 + @ne.lng - @sw.lng : @ne.lng - @sw.lng).abs
+      Geokit::LatLng.new(lat_span, lng_span)
+    end
+
+    class <<self
+
+      # returns an instance of bounds which completely encompases the given circle
+      def from_point_and_radius(point,radius,options={})
+        point=LatLng.normalize(point)
+        p0=point.endpoint(0,radius,options)
+        p90=point.endpoint(90,radius,options)
+        p180=point.endpoint(180,radius,options)
+        p270=point.endpoint(270,radius,options)
+        sw=Geokit::LatLng.new(p180.lat,p270.lng)
+        ne=Geokit::LatLng.new(p0.lat,p90.lng)
+        Geokit::Bounds.new(sw,ne)
+      end
+
+      # Takes two main combinations of arguments to create a bounds:
+      # point,point   (this is the only one which takes two arguments
+      # [point,point]
+      # . . . where a point is anything LatLng#normalize can handle (which is quite a lot)
+      #
+      # NOTE: everything combination is assumed to pass points in the order sw, ne
+      def normalize (thing,other=nil)
+        # maybe this will be simple -- an actual bounds object is passed, and we can all go home
+        return thing if thing.is_a? Bounds
+
+        # no? OK, if there's no "other," the thing better be a two-element array
+        thing,other=thing if !other && thing.is_a?(Array) && thing.size==2
+
+        # Now that we're set with a thing and another thing, let LatLng do the heavy lifting.
+        # Exceptions may be thrown
+        Bounds.new(Geokit::LatLng.normalize(thing),Geokit::LatLng.normalize(other))
+      end
+    end
+  end
+end

data/lib/geokit/core_ext.rb

@@ -0,0 +1,17 @@
+unless nil.respond_to?(:try)
+  class Object 
+    def try(*a, &b)
+      if a.empty? && block_given?
+        yield self
+      else
+        __send__(*a, &b)
+      end
+    end
+  end
+
+  class NilClass
+    def try(*args)
+      nil
+    end
+  end
+end

data/lib/geokit/geo_loc.rb

@@ -0,0 +1,134 @@
+module Geokit
+  # This class encapsulates the result of a geocoding call.
+  # It's primary purpose is to homogenize the results of multiple
+  # geocoding providers. It also provides some additional functionality, such as
+  # the "full address" method for geocoders that do not provide a
+  # full address in their results (for example, Yahoo), and the "is_us" method.
+  #
+  # Some geocoders can return multple results. Geoloc can capture multiple results through
+  # its "all" method.
+  #
+  # For the geocoder setting the results, it would look something like this:
+  #     geo=GeoLoc.new(first_result)
+  #     geo.all.push(second_result)
+  #     geo.all.push(third_result)
+  #
+  # Then, for the user of the result:
+  #
+  #     puts geo.full_address     # just like usual
+  #     puts geo.all.size  => 3   # there's three results total
+  #     puts geo.all.first        # all is just an array or additional geolocs,
+  #                                 so do what you want with it
+  class GeoLoc < LatLng
+
+    # Location attributes.  Full address is a concatenation of all values.  For example:
+    # 100 Spear St, San Francisco, CA, 94101, US
+    # Street number and street name are extracted from the street address attribute if they don't exist
+    attr_accessor :street_number, :street_name, :street_address, :city, :state, :zip, :country_code, :country
+    attr_accessor :full_address, :all, :district, :province, :sub_premise, :neighborhood
+    # Attributes set upon return from geocoding.  Success will be true for successful
+    # geocode lookups.  The provider will be set to the name of the providing geocoder.
+    # Finally, precision is an indicator of the accuracy of the geocoding.
+    attr_accessor :success, :provider, :precision, :suggested_bounds
+    # accuracy is set for Yahoo and Google geocoders, it is a numeric value of the
+    # precision. see http://code.google.com/apis/maps/documentation/geocoding/#GeocodingAccuracy
+    attr_accessor :accuracy
+    # FCC Attributes
+    attr_accessor :district_fips, :state_fips, :block_fips
+
+
+    # Constructor expects a hash of symbols to correspond with attributes.
+    def initialize(h={})
+      @all = [self]
+
+      @street_address=h[:street_address]
+      @sub_premise=nil
+      @street_number=nil
+      @street_name=nil
+      @city=h[:city]
+      @state=h[:state]
+      @zip=h[:zip]
+      @country_code=h[:country_code]
+      @province = h[:province]
+      @success=false
+      @precision='unknown'
+      @full_address=nil
+      super(h[:lat],h[:lng])
+    end
+
+    # Returns true if geocoded to the United States.
+    def is_us?
+      country_code == 'US'
+    end
+
+    def success?
+      success == true
+    end
+
+    # full_address is provided by google but not by yahoo. It is intended that the google
+    # geocoding method will provide the full address, whereas for yahoo it will be derived
+    # from the parts of the address we do have.
+    def full_address
+      @full_address ? @full_address : to_geocodeable_s
+    end
+
+    # Extracts the street number from the street address where possible.
+    def street_number
+      @street_number ||= street_address[/(\d*)/] if street_address
+      @street_number
+    end
+
+    # Returns the street name portion of the street address where possible
+    def street_name
+      @street_name||=street_address[street_number.length, street_address.length].strip if street_address
+      @street_name
+    end
+
+    # gives you all the important fields as key-value pairs
+    def hash
+      res={}
+      [:success, :lat, :lng, :country_code, :city, :state, :zip, :street_address, :province,
+       :district, :provider, :full_address, :is_us?, :ll, :precision, :district_fips, :state_fips,
+       :block_fips, :sub_premise].each { |s| res[s] = self.send(s.to_s) }
+      res
+    end
+    alias to_hash hash
+
+    # Sets the city after capitalizing each word within the city name.
+    def city=(city)
+      @city = Geokit::Inflector::titleize(city) if city
+    end
+
+    # Sets the street address after capitalizing each word within the street address.
+    def street_address=(address)
+      @street_address = if address && provider != 'google'
+        Geokit::Inflector::titleize(address)
+      else
+        address
+      end
+    end
+
+    # Returns a comma-delimited string consisting of the street address, city, state,
+    # zip, and country code.  Only includes those attributes that are non-blank.
+    def to_geocodeable_s
+      a=[street_address, district, city, province, state, zip, country_code].compact
+      a.delete_if { |e| !e || e == '' }
+      a.join(', ')
+    end
+
+    def to_yaml_properties
+      (instance_variables - ['@all', :@all]).sort
+    end
+
+    def encode_with(coder)
+      to_yaml_properties.each do |name|
+        coder[name[1..-1].to_s] = instance_variable_get(name.to_s)
+      end
+    end
+
+    # Returns a string representation of the instance.
+    def to_s
+      "Provider: #{provider}\nStreet: #{street_address}\nCity: #{city}\nState: #{state}\nZip: #{zip}\nLatitude: #{lat}\nLongitude: #{lng}\nCountry: #{country_code}\nSuccess: #{success}"
+    end
+  end
+end

data/lib/geokit/geocoders.rb

@@ -10,9 +10,6 @@ require 'multi_json'
 module Geokit
   require File.join(File.dirname(__FILE__), 'inflectors')
 
-  class TooManyQueriesError < StandardError; end
-
-
   # Contains a range of geocoders:
   #
   # ### "regular" address geocoders
@@ -33,15 +30,14 @@ module Geokit
   #
   # Some of these geocoders require configuration. You don't have to provide it here. See the README.
   module Geocoders
-    @@proxy_addr = nil
-    @@proxy_port = nil
-    @@proxy_user = nil
-    @@proxy_pass = nil
+    @@proxy = nil
     @@request_timeout = nil
+    @@bing = 'REPLACE_WITH_YOUR_BING_KEY'
+    @@bing_options = {}
     @@yahoo_consumer_key = 'REPLACE_WITH_YOUR_YAHOO_BOSS_OAUTH_CONSUMER_KEY'
     @@yahoo_consumer_secret = 'REPLACE_WITH_YOUR_YAHOO_BOSS_OAUTH_CONSUMER_SECRET'
-    @@yandex = 'REPLACE_WITH_YOUR_YANDEX_KEY'
-    @@google = 'REPLACE_WITH_YOUR_GOOGLE_KEY'
+    @@yandex = nil
+    @@mapquest = 'REPLACE_WITH_YOUR_MAPQUEST_KEY'
     @@google_client_id = nil
     @@google_cryptographic_key = nil
     @@google_channel = nil
@@ -84,6 +80,7 @@ module Geokit
 
     # Error which is thrown in the event a geocoding error occurs.
     class GeocodeError < StandardError; end
+    class TooManyQueriesError < StandardError; end
 
     # -------------------------------------------------------------------------------------------
     # Geocoder Base class -- every geocoder should inherit from this
@@ -95,36 +92,39 @@ module Geokit
       # Main method which calls the do_geocode template method which subclasses
       # are responsible for implementing.  Returns a populated GeoLoc or an
       # empty one with a failed success code.
-      def self.geocode(address, options = {})
-        res = do_geocode(address, options)
-        return res.nil? ? GeoLoc.new : res
+      def self.geocode(address, *args)
+        do_geocode(address, *args) || GeoLoc.new
+      rescue TooManyQueriesError, GeocodeError
+        raise
+      rescue
+        logger.error "Caught an error during #{self.class} geocoding call: #{$!}"
+        GeoLoc.new
       end
       # Main method which calls the do_reverse_geocode template method which subclasses
       # are responsible for implementing.  Returns a populated GeoLoc or an
       # empty one with a failed success code.
       def self.reverse_geocode(latlng)
-        res = do_reverse_geocode(latlng)
-        return res.success? ? res : GeoLoc.new
+        do_reverse_geocode(latlng) || GeoLoc.new
       end
 
       # Call the geocoder service using the timeout if configured.
       def self.call_geocoder_service(url)
         Timeout::timeout(Geokit::Geocoders::request_timeout) { return self.do_get(url) } if Geokit::Geocoders::request_timeout
-        return self.do_get(url)
+        self.do_get(url)
       rescue TimeoutError
-        return nil
+        nil
       end
 
       # Not all geocoders can do reverse geocoding. So, unless the subclass explicitly overrides this method,
       # a call to reverse_geocode will return an empty GeoLoc. If you happen to be using MultiGeocoder,
       # this will cause it to failover to the next geocoder, which will hopefully be one which supports reverse geocoding.
       def self.do_reverse_geocode(latlng)
-        return GeoLoc.new
+        GeoLoc.new
       end
 
       protected
 
-      def self.logger()
+      def self.logger
         Geokit::Geocoders::logger
       end
 
@@ -135,31 +135,44 @@ module Geokit
         uri = URI.parse(url)
         req = Net::HTTP::Get.new(url)
         req.basic_auth(uri.user, uri.password) if uri.userinfo
-        res = Net::HTTP::new(uri.host, uri.port,
-                Geokit::Geocoders::proxy_addr,
-                Geokit::Geocoders::proxy_port,
-                Geokit::Geocoders::proxy_user,
-                Geokit::Geocoders::proxy_pass).start { |http| http.request(req) }
-        return res
+        net_http_args = [uri.host, uri.port]
+        if (proxy_uri_string = Geokit::Geocoders::proxy)
+          proxy_uri = URI.parse(proxy_uri_string)
+          net_http_args += [proxy_uri.host, proxy_uri.port, proxy_uri.user, proxy_uri.password]
+        end
+        Net::HTTP::new(*net_http_args).start { |http| http.request(req) }
+      end
+
+      def self.parse(format, body, *args)
+        case format
+        when :json then parse_json(MultiJson.load(body), *args)
+        when :xml  then parse_xml(REXML::Document.new(body), *args)
+        when :yaml then parse_yaml(YAML::load(body), *args)
+        end
       end
 
-      # Adds subclass' geocode method making it conveniently available through
-      # the base class.
-      def self.inherited(clazz)
-        class_name = clazz.name.split('::').last
-        src = <<-END_SRC
-          def self.#{Geokit::Inflector.underscore(class_name)}(address, options = {})
-            #{class_name}.geocode(address, options)
-          end
-        END_SRC
-        class_eval(src)
+      def self.set_mappings(loc, xml, mappings)
+        mappings.each_pair do |field, xml_field|
+          loc.send("#{field}=", xml.elements[xml_field].try(:text))
+        end
+      end
+
+      def self.transcode_to_utf8(body)
+        require 'iconv' unless String.method_defined?(:encode)
+        if String.method_defined?(:encode)
+          body.encode!('UTF-8', 'UTF-8', :invalid => :replace)
+        else
+          ic = Iconv.new('UTF-8', 'UTF-8//IGNORE')
+          body = ic.iconv(body)
+        end
       end
     end
 
     # -------------------------------------------------------------------------------------------
     # "Regular" Address geocoders
     # -------------------------------------------------------------------------------------------
-    Dir[File.join(File.dirname(__FILE__), "/services/*.rb")].each {|f| require f}
+    require File.join(File.dirname(__FILE__), 'geocoders/base_ip')
+    Dir[File.join(File.dirname(__FILE__), "/geocoders/*.rb")].each {|f| require f}
 
     require File.join(File.dirname(__FILE__), 'multi_geocoder')
   end