geocoder 1.1.8 → 1.1.9

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6e54ea93888b39c46a8ed298a9d3eca5c6a4533a
+  data.tar.gz: 2b72dcae0e8cc61ba37fb831db4ef88b18543b56
+SHA512:
+  metadata.gz: b30e519cafc13d8e57c300f6249fdae8736e92503ef3f2bb03b2670eca83f956c3640ddff1f8567bfbb3b80b048ae80a4bebf8f08423a8a137a0d7f3dfa83e2b
+  data.tar.gz: dbd472d124b0b795b797abbfe997a9591db207495880c84fbda1f9c2b07626f176be4aab78136e59d347c4492f3b55b41e8381e8e59b85d36945f6d0a18323e1

data/.travis.yml

@@ -2,6 +2,7 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - 2.0.0
   - jruby-19mode
 gemfile:
   - Gemfile
@@ -18,6 +19,9 @@ matrix:
     - rvm: 1.9.3
       gemfile: gemfiles/Gemfile.mongoid-2.4.x
       env: SSL_CERT_DIR=/etc/ssl/certs
+    - rvm: 2.0.0
+      gemfile: gemfiles/Gemfile.mongoid-2.4.x
+      env: SSL_CERT_DIR=/etc/ssl/certs
     - rvm: jruby-19mode
       gemfile: gemfiles/Gemfile.mongoid-2.4.x
       env: SSL_CERT_DIR=/etc/ssl/certs 

data/CHANGELOG.md

@@ -1,7 +1,19 @@
 Changelog
 =========
 
-Per-release changes to Geocoder. Note that only major changes are summarized here. Please see the Git log for all changes.
+Major changes to Geocoder for each release. Please see the Git log for complete list of changes.
+
+1.1.9 (2013 Dec 11)
+-------------------
+
+* DEPRECATED support for Ruby 1.8.x. Will be dropped in a future version.
+* Require API key for MapQuest (thanks github.com/robdiciuccio).
+* Add support for geocoder.us and HTTP basic auth (thanks github.com/komba).
+* Add support for Data Science Toolkit lookup (thanks github.com/ejhayes).
+* Add support for Baidu (thanks github.com/mclee).
+* Add Geocoder::Calculations.random_point_near method (thanks github.com/adambray).
+* Fix: #nearbys method with Mongoid (thanks github.com/pascalbetz).
+* Fix: bug in FreeGeoIp lookup that was preventing exception from being raised when configured cache was unavailable.
 
 1.1.8 (2013 Apr 22)
 -------------------

data/README.md

@@ -7,9 +7,9 @@ Geocoder is a complete geocoding solution for Ruby. With Rails it adds geocoding
 Compatibility
 -------------
 
-* Supports multiple Ruby versions: Ruby 1.8.7, 1.9.2, 1.9.3, and JRuby.
+* Supports multiple Ruby versions: Ruby 1.8.7, 1.9.2, 1.9.3, 2.0.0, and JRuby.
 * Supports multiple databases: MySQL, PostgreSQL, SQLite, and MongoDB (1.7.0 and higher).
-* Supports Rails 3.x. If you need to use it with Rails 2 please see the `rails2` branch (no longer maintained, limited feature set).
+* Supports Rails 3 and 4. If you need to use it with Rails 2 please see the `rails2` branch (no longer maintained, limited feature set).
 * Works very well outside of Rails, you just need to install either the `json` (for MRI) or `json_pure` (for JRuby) gem.
 
 
@@ -98,7 +98,9 @@ If you have just added geocoding to an existing application with a lot of object
 
     rake geocode:all CLASS=YourModel
 
-Geocoder will print warnings if you exceed the rate limit for your geocoding service.
+Geocoder will print warnings if you exceed the rate limit for your geocoding service. Some services — Google notably — enforce a per-second limit in addition to a per-day limit. To avoid exceeding the per-second limit, you can add a `sleep` option to the rake task, like so:
+
+    rake geocode:all CLASS=YourModel sleep=0.25
 
 
 Request Geocoding by IP Address
@@ -121,6 +123,8 @@ To find objects by location, use the following scopes:
 
     Venue.near('Omaha, NE, US', 20)    # venues within 20 miles of Omaha
     Venue.near([40.71, 100.23], 20)    # venues within 20 miles of a point
+    Venue.near([40.71, 100.23], 20, :units => :km)
+                                       # venues within 20 kilometres of a point
     Venue.geocoded                     # venues with coordinates
     Venue.not_geocoded                 # venues without coordinates
 
@@ -221,9 +225,7 @@ When querying for objects (if you're using ActiveRecord) you can also look withi
     box = Geocoder::Calculations.bounding_box(center_point, distance)
     Venue.within_bounding_box(box)
 
-This can also dramatically improve query performance, especially when used in conjunction with indexes on the latitude/longitude columns. Note, however, that returned results do not include `distance` and `bearing` attributes. If you want to improve performance AND have access to distance and bearing info, use both scopes:
-
-    Venue.near(center_point, distance).within_bounding_box(box)
+This can also dramatically improve query performance, especially when used in conjunction with indexes on the latitude/longitude columns. Note, however, that returned results do not include `distance` and `bearing` attributes. Note that `#near` performs both bounding box and radius queries for speed.
 
 
 Advanced Geocoding
@@ -300,7 +302,7 @@ The following is a comparison of the supported geocoding APIs. The "Limitations"
 #### Google (`:google`, `:google_premier`)
 
 * **API key**: required for Premier (do NOT use a key for the free version)
-* **Key signup**: http://code.google.com/apis/maps/signup.html
+* **Key signup**: https://developers.google.com/maps/documentation/business/
 * **Quota**: 2,500 requests/day, 100,000 with Google Maps API Premier
 * **Region**: world
 * **SSL support**: yes
@@ -346,7 +348,7 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **Languages**: ?
 * **Documentation**: http://wiki.openstreetmap.org/wiki/Nominatim
 * **Terms of Service**: http://wiki.openstreetmap.org/wiki/Nominatim_usage_policy
-* **Limitations**: Please limit request rate to 1 per second and include your contact information in User-Agent headers. Data licensed under CC-BY-SA (you must provide attribution).
+* **Limitations**: Please limit request rate to 1 per second and include your contact information in User-Agent headers (eg: `Geocoder.configure(:http_headers => { "User-Agent" => "your contact info" })`). Data licensed under CC-BY-SA (you must provide attribution).
 
 #### Yandex (`:yandex`)
 
@@ -370,9 +372,22 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **Terms of Service**: http://geocoder.ca/?terms=1
 * **Limitations**: "Under no circumstances can our data be re-distributed or re-sold by anyone to other parties without our written permission."
 
+#### Geocoder.us (`:geocoder_us`)
+
+* **API key**: HTTP Basic Auth
+* **Sign up**: http://geocoder.us/user/signup
+* **Quota**: You can purchase 20,000 credits at a time for $50
+* **Region**: US
+* **SSL support**: no
+* **Languages**: English
+* **Documentation**: http://geocoder.us/help/
+* **Terms of Service**: http://geocoder.us/terms.shtml
+* **Limitations**: ?
+
 #### Mapquest (`:mapquest`)
 
-* **API key**: required for the licensed API, do not use for open tier
+* **API key**: required
+* **Key signup**: http://developer.mapquest.com/web/products/open
 * **Quota**: ?
 * **HTTP Headers**: in order to use the licensed API you can configure the http_headers to include a referer as so:
     `Geocoder.configure(:http_headers => { "Referer" => "http://foo.com" })`
@@ -383,6 +398,7 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **Documentation**: http://www.mapquestapi.com/geocoding/
 * **Terms of Service**: http://info.mapquest.com/terms-of-use/
 * **Limitations**: ?
+* **Notes**: You can specify the licensed API by setting: `Geocoder.configure(:mapquest => {:licensed => true})` (defaults to free "open" version)
 
 #### Ovi/Nokia (`:ovi`)
 
@@ -395,14 +411,40 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **Terms of Service**: http://www.developer.nokia.com/Develop/Maps/TC.html
 * **Limitations**: ?
 
+#### ESRI (`:esri`)
+
+* **API key**: none
+* **Quota**: Required for some scenarios (see Terms of Service)
+* **Region**: world
+* **SSL support**: yes
+* **Languages**: English
+* **Documentation**: http://resources.arcgis.com/en/help/arcgis-online-geocoding-rest-api/
+* **Terms of Service**: http://www.esri.com/software/arcgis/arcgisonline/services/geoservices
+* **Limitations**: ?
+* **Notes**: You can specify which projection you want to use by setting, for example: `Geocoder.configure(:esri => {:outSR => 102100})`.
+
+#### Data Science Toolkit (`:dstk`)
+
+Data Science Toolkit provides an API whose reponse format is like Google's but which can be set up as a privately hosted service.
+
+* **API key**: none
+* **Quota**: None quota if you are self-hosting the service.
+* **Region**: world
+* **SSL support**: ?
+* **Languages**: en
+* **Documentation**: http://www.datasciencetoolkit.org/developerdocs
+* **Terms of Service**: http://www.datasciencetoolkit.org/developerdocs#googlestylegeocoder
+* **Limitations**: No reverse geocoding.
+* **Notes**: If you are hosting your own DSTK server you will need to configure the host name, eg: `Geocoder.configure(:lookup => :dstk, :host => "localhost:4567")`.
+
 #### FreeGeoIP (`:freegeoip`)
 
 * **API key**: none
-* **Quota**: 1000 requests per hour.  After reaching the hourly quota, all of your requests will result in HTTP 403 (Forbidden) until it clears up on the next roll over.
+* **Quota**: 10000 requests per hour. After reaching the hourly quota, all of your requests will result in HTTP 403 (Forbidden) until it clears up on the next roll over.
 * **Region**: world
 * **SSL support**: no
 * **Languages**: English
-* **Documentation**: http://github.com/fiorix/freegeoip/blob/master/README.rst
+* **Documentation**: http://github.com/fiorix/freegeoip/blob/master/README.md
 * **Terms of Service**: ?
 * **Limitations**: ?
 
@@ -418,18 +460,17 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **Limitations**: ?
 * **Notes**: You must specify which MaxMind service you are using in your configuration. For example: `Geocoder.configure(:maxmind => {:service => :omni})`.
 
-#### ESRI (`:esri`)
-
-* **API key**: none
-* **Quota**: Required for some scenarios (see Terms of Service)
-* **Region**: world
-* **SSL support**: yes
-* **Languages**: English
-* **Documentation**: http://resources.arcgis.com/en/help/arcgis-online-geocoding-rest-api/
-* **Terms of Service**: http://www.esri.com/software/arcgis/arcgisonline/services/geoservices
-* **Limitations**: ?
-* **Notes**: You can specify which projection you want to use by setting, for example: `Geocoder.configure(:esri => {:outSR => 102100})`.
+#### Baidu (`:baidu`)
 
+* **API key**: required
+* **Quota**: No quota limits for geocoding
+* **Region**: China
+* **SSL support**: no
+* **Languages**: Chinese (Simplified)
+* **Documentation**: http://developer.baidu.com/map/webservice-geocoding.htm
+* **Terms of Service**: http://developer.baidu.com/map/law.htm
+* **Limitations**: Only good for non-commercial use. For commercial usage please check http://developer.baidu.com/map/question.htm#qa0013
+* **Notes**: To use Baidu set `Geocoder.configure(:lookup => :baidu, :api_key => "your_api_key")`.
 
 Caching
 -------
@@ -440,10 +481,9 @@ It's a good idea, when relying on any external service, to cache retrieved data.
 
 This example uses Redis, but the cache store can be any object that supports these methods:
 
-* `store#[](key)`         - retrieves a value
-* `store#[]=(key, value)` - stores a value
-* `store#keys`            - lists all keys
-* `store#del(url)`        - deletes a value
+* `store#[](key)` or `#get` or `#read` - retrieves a value
+* `store#[]=(key, value)` or `#set` or `#write` - stores a value
+* `store#del(url)` - deletes a value
 
 Even a plain Ruby hash will work, though it's not a great choice (cleared out when app is restarted, not shared between app instances, etc).
 
@@ -520,7 +560,7 @@ For example:
       after_validation :reverse_geocode, :if => :has_coordinates
       after_validation :geocode, :if => :has_location, :unless => :has_coordinates
 
-    end  
+    end
 
 Use Outside of Rails
 --------------------
@@ -590,6 +630,13 @@ When you install the Geocoder gem it adds a `geocode` command to your shell. You
 
 There are also a number of options for setting the geocoding API, key, and language, viewing the raw JSON reponse, and more. Please run `geocode -h` for details.
 
+Numeric Data Types and Precision
+--------------------------------
+
+Geocoder works with any numeric data type (e.g. float, double, decimal) on which trig (and other mathematical) functions can be performed.
+
+A summary of the relationship between geographic precision and the number of decimal places in latitude and longitude degree values is available on [Wikipedia](http://en.wikipedia.org/wiki/Decimal_degrees#Accuracy). As an example: at the equator, latitude/longitude values with 4 decimal places give about 11 metres precision, whereas 5 decimal places gives roughly 1 metre precision.
+
 Notes on MongoDB
 ----------------
 
@@ -616,7 +663,7 @@ Notes on Non-Rails Frameworks
 
 If you are using Geocoder with ActiveRecord and a framework other than Rails (like Sinatra or Padrino) you will need to add this in your model before calling Geocoder methods:
 
-    extend Geocoder::Model::ActiveRecord 
+    extend Geocoder::Model::ActiveRecord
 
 Optimisation of Distance Queries
 --------------------------------
@@ -715,12 +762,35 @@ When reporting an issue, please list the version of Geocoder you are using and a
 Known Issue
 -----------
 
-You cannot use the `near` scope with another scope that provides an `includes` option because the `SELECT` clause generated by `near` will overwrite it (or vice versa). Instead, try using `joins` and pass a `:select` option to the `near` scope to get the columns you want. For example:
+You cannot use the `near` scope with another scope that provides an `includes` option because the `SELECT` clause generated by `near` will overwrite it (or vice versa).
+
+Instead of using `includes` to reduce the number of database queries, try using `joins` with either the `:select` option or a call to `preload`. For example:
 
-    # instead of City.near(...).includes(:venues)
+    # Pass a :select option to the near scope to get the columns you want.
+    # Instead of City.near(...).includes(:venues), try:
     City.near("Omaha, NE", 20, :select => "cities.*, venues.*").joins(:venues)
 
+    # This preload call will normally trigger two queries regardless of the
+    # number of results; one query on hotels, and one query on administrators.
+    # Instead of Hotel.near(...).includes(:administrator), try:
+    Hotel.near("London, UK", 50).joins(:administrator).preload(:administrator)
+
 If anyone has a more elegant solution to this problem I am very interested in seeing it.
 
 
+Contributing
+------------
+
+Contributions are welcome via pull requests on Github. Please respect the following guidelines:
+
+* Each pull request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one pull request.
+* Do not commit changes to files that are irrelevant to your feature or bugfix (eg: `.gitignore`).
+* Do not add dependencies on other gems.
+* Do not add unnecessary `require` statements which could cause LoadErrors on certain systems.
+* Remember: Geocoder needs to run outside of Rails. Don't assume things like ActiveSupport are available.
+* Do not add to base configuration options; instead document required lookup-specific options in the README.
+* Be willing to accept criticism and work on improving your code; Geocoder is used by thousands of developers and care must be taken not to introduce bugs.
+* Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request.
+
+
 Copyright (c) 2009-12 Alex Reisner, released under the MIT license

data/Rakefile

@@ -14,7 +14,7 @@ Rake::TestTask.new(:integration) do |test|
   test.verbose = true
 end
 
-task :default => [:test, :integration]
+task :default => [:test]
 
 require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|

data/examples/autoexpire_cache_dalli.rb

@@ -20,7 +20,7 @@ class AutoexpireCacheDalli
     if value.nil?
       del(url)
     else
-      key_cache_add(url) if @store.add(key, YAML::dump(value), @ttl)
+      key_cache_add(url) if @store.add(url, YAML::dump(value), @ttl)
     end
     value
   end
@@ -30,7 +30,7 @@ class AutoexpireCacheDalli
   end
 
   def del(url)
-    key_cache_delete(url) if @store.delete(key)
+    key_cache_delete(url) if @store.delete(url)
   end
 
   private

data/examples/cache_bypass.rb

@@ -0,0 +1,48 @@
+# This class allows you to configure how Geocoder should treat errors that occur when
+# the cache is not available.
+# Configure it like this
+# config/initializers/geocoder.rb
+# Geocoder.configure(
+#  :cache => Geocoder::CacheBypass.new(Redis.new)
+# )
+#
+# Depending on the value of @bypass this will either
+# raise the exception (true) or swallow it and pretend the cache did not return a hit (false)
+#
+class Geocoder::CacheBypass
+  def initialize(target, bypass = true)
+    @target = target
+    @bypass = bypass
+  end
+
+
+  def [](key)
+    with_bypass { @target[key] }
+  end
+
+  def []=(key, value)
+    with_bypass(value) { @target[key] = value }
+  end
+
+  def keys
+    with_bypass([]) { @target.keys }
+  end
+
+  def del(key)
+    with_bypass { @target.del(key) }
+  end
+
+  private
+
+  def with_bypass(return_value_if_exception = nil, &block)
+    begin
+      yield
+    rescue
+      if @bypass
+        return_value_if_exception
+      else
+        raise # reraise original exception
+      end
+    end
+  end
+end

data/lib/geocoder/calculations.rb

@@ -216,6 +216,44 @@ module Geocoder
       ]
     end
 
+    ##
+    # Random point within a circle of provided radius centered
+    # around the provided point
+    # Takes one point, one radius, and an options hash.
+    # The points are given in the same way that points are given to all
+    # Geocoder methods that accept points as arguments. They can be:
+    #
+    # * an array of coordinates ([lat,lon])
+    # * a geocodable address (string)
+    # * a geocoded object (one which implements a +to_coordinates+ method
+    #   which returns a [lat,lon] array
+    #
+    # The options hash supports:
+    #
+    # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
+    #   Use Geocoder.configure(:units => ...) to configure default units.
+    def random_point_near(center, radius, options = {})
+
+      # set default options
+      options[:units] ||= Geocoder.config.units
+
+      # convert to coordinate arrays
+      center = extract_coordinates(center)
+
+      earth_circumference = 2 * Math::PI * earth_radius(options[:units])
+      max_degree_delta =  360.0 * (radius / earth_circumference)
+
+      # random bearing in radians
+      theta = 2 * Math::PI * rand
+
+      # random radius, use the square root to ensure a uniform
+      # distribution of points over the circle
+      r = Math.sqrt(rand) * max_degree_delta
+
+      delta_lat, delta_long = [r * Math.cos(theta), r * Math.sin(theta)]
+      [center[0] + delta_lat, center[1] + delta_long]
+    end
+
     ##
     # Convert degrees to radians.
     # If an array (or multiple arguments) is passed,

data/lib/geocoder/cli.rb

@@ -8,6 +8,11 @@ module Geocoder
       show_url  = false
       show_json = false
 
+      # remove arguments that are probably coordinates so they are not
+      # processed as arguments (eg: -31.96047031,115.84274631)
+      coords = args.select{ |i| i.match(/^-\d/) }
+      args -= coords
+
       OptionParser.new{ |opts|
         opts.banner = "Usage:\n    geocode [options] <location>"
         opts.separator "\nOptions: "
@@ -65,7 +70,9 @@ module Geocoder
         end
       }.parse!(args)
 
-      query = args.join(" ")
+      # concatenate args with coords that might have been removed
+      # before option processing
+      query = (args + coords).join(" ")
 
       if query == ""
         out << "Please specify a location (run `geocode -h` for more info).\n"

data/lib/geocoder/lookup.rb

@@ -21,16 +21,19 @@ module Geocoder
     #
     def street_services
       [
+        :dstk,
         :esri,
         :google,
         :google_premier,
         :yahoo,
         :bing,
         :geocoder_ca,
+        :geocoder_us,
         :yandex,
         :nominatim,
         :mapquest,
         :ovi,
+        :baidu,
         :test
       ]
     end