geocoder 1.1.9 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6e54ea93888b39c46a8ed298a9d3eca5c6a4533a
-  data.tar.gz: 2b72dcae0e8cc61ba37fb831db4ef88b18543b56
+  metadata.gz: f4a9925e759e3cd83f49edbe16d9258f047d4706
+  data.tar.gz: 647fe2e7bc4731707a75dde07c8eec629622821a
 SHA512:
-  metadata.gz: b30e519cafc13d8e57c300f6249fdae8736e92503ef3f2bb03b2670eca83f956c3640ddff1f8567bfbb3b80b048ae80a4bebf8f08423a8a137a0d7f3dfa83e2b
-  data.tar.gz: dbd472d124b0b795b797abbfe997a9591db207495880c84fbda1f9c2b07626f176be4aab78136e59d347c4492f3b55b41e8381e8e59b85d36945f6d0a18323e1
+  metadata.gz: 1515913cc2e937453458d947421278666ffda78d9388480080fb3af5978cd0a7efd89a5272f33fdfb46e9b89899b675d3064b276cf8b8e97091ce6b218d91f7f
+  data.tar.gz: f76ddc572cfb359718ee5da19451462bfeb442a4986560afb6837444756dcfbaf32d3a36025977d08ab68f9e7f9223ef236ec5c354240932c93b90e42dbb1a3b

data/.gitignore

@@ -3,3 +3,4 @@ rdoc/*
 *.gem
 .bundle
 Gemfile.lock
+api_keys.yml

data/.travis.yml

@@ -1,18 +1,16 @@
 rvm:
-  - 1.8.7
   - 1.9.2
   - 1.9.3
   - 2.0.0
+  - 2.1.0
   - jruby-19mode
+  - rbx
 gemfile:
   - Gemfile
   - gemfiles/Gemfile.mongoid-2.4.x
 env: SSL_CERT_DIR=/etc/ssl/certs
 matrix:
   exclude:
-    - rvm: 1.8.7
-      gemfile: Gemfile
-      env: SSL_CERT_DIR=/etc/ssl/certs
     - rvm: 1.9.2
       gemfile: Gemfile
       env: SSL_CERT_DIR=/etc/ssl/certs
@@ -22,6 +20,12 @@ matrix:
     - rvm: 2.0.0
       gemfile: gemfiles/Gemfile.mongoid-2.4.x
       env: SSL_CERT_DIR=/etc/ssl/certs
+    - rvm: 2.1.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 
+      env: SSL_CERT_DIR=/etc/ssl/certs
+    - rvm: rbx
+      gemfile: gemfiles/Gemfile.mongoid-2.4.x
+      env: SSL_CERT_DIR=/etc/ssl/certs

data/CHANGELOG.md

@@ -3,6 +3,25 @@ Changelog
 
 Major changes to Geocoder for each release. Please see the Git log for complete list of changes.
 
+1.2.0 (2014 Apr 16)
+-----------
+
+* DROP SUPPORT for Ruby 1.8.x.
+* Add :here lookup (thanks github.com/christoph-buente).
+* Add :cloudmade lookup (thanks github.com/spoptchev).
+* Add :smarty_streets lookup (thanks github.com/drinks).
+* Add :maxmind_local IP lookup (thanks github.com/fernandomm).
+* Add :baidu_ip lookup (thanks github.com/yonggu).
+* Add :geocodio lookup (thanks github.com/dblock).
+* Add :lookup option to `Geocoder.search` and `geocoded_by` (thanks github.com/Bonias).
+* Add support for :maxmind_local on JRuby via jgeoip gem (thanks github.com/gxbe).
+* Add support for using :maxmind_local with an SQL database, including Rake tasks for downloading CSV data and populating a local DB.
+* Add support for character encodings based on Content-type header (thanks github.com/timaro).
+* Add :min_radius option to `near` scope (thanks github.com/phallstrom).
+* Fix: Yandex city attribute caused exception with certain responses (thanks github.com/dblock).
+* Change name of MapQuest config option from :licensed to :open and revert default behavior to be MapQuest data (not OpenStreetMaps).
+* Reduce number of Ruby warnings (thanks github.com/exviva).
+
 1.1.9 (2013 Dec 11)
 -------------------
 

data/README.md

@@ -7,12 +7,18 @@ 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, 2.0.0, and JRuby.
+* Supports multiple Ruby versions: Ruby 1.9.2, 1.9.3, 2.0.0, 2.1.0, JRuby and Rubinius.
 * Supports multiple databases: MySQL, PostgreSQL, SQLite, and MongoDB (1.7.0 and higher).
 * 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.
 
 
+Rails 4.1 Note
+--------------
+
+Due to [a change in ActiveRecord's `count` method](https://github.com/rails/rails/pull/10710) you will need to use `count(:all)` to explicitly count all columns ("*") when using a `near` scope. Using `near` and calling `count` with no argument will cause exceptions in many cases.
+
+
 Installation
 ------------
 
@@ -98,9 +104,20 @@ 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. 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:
+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 pause between requests for a given amount of time. You can also load objects in batches to save memory, for example:
+
+    rake geocode:all CLASS=YourModel SLEEP=0.25 BATCH=100
+
+### Avoiding Unnecessary API Requests
 
-    rake geocode:all CLASS=YourModel sleep=0.25
+Geocoding only needs to be performed under certain conditions. To avoid unnecessary work (and quota usage) you will probably want to geocode an object only when:
+
+* an address is present
+* the address has been changed since last save (or it has never been saved)
+
+The exact code will vary depending on the method you use for your geocodable string, but it would be something like this:
+
+    after_validation :geocode, if: ->(obj){ obj.address.present? and obj.address_changed? }
 
 
 Request Geocoding by IP Address
@@ -195,6 +212,11 @@ You are not stuck with using the `latitude` and `longitude` database column name
     geocoded_by :address, :latitude  => :lat, :longitude => :lon # ActiveRecord
     geocoded_by :address, :coordinates => :coords                # MongoDB
 
+This means you can geocode multiple addresses as well:
+
+    geocoded_by :start_address, latitude: :start_latitude, longitude: :start_longitude
+    geocoded_by :end_address, latitude: :end_latitude, longitude: :end_longitude
+
 The `address` method can return any string you'd use to search Google Maps. For example, any of the following are acceptable:
 
 * "714 Green St, Big Town, MO"
@@ -214,6 +236,24 @@ For reverse geocoding you can also specify an alternate name attribute where the
     reverse_geocoded_by :latitude, :longitude, :address => :location  # ActiveRecord
     reverse_geocoded_by :coordinates, :address => :loc                # MongoDB
 
+You can also configure a specific lookup for your model which will override the globally-configured lookup, for example:
+
+    geocoded_by :address, :lookup => :yandex
+
+You can also specify a proc if you want to choose a lookup based on a specific property of an object, for example you can use specialized lookups for different regions:
+
+    geocoded_by :address, :lookup => lambda{ |obj| obj.geocoder_lookup }
+
+    def geocoder_lookup
+      if country_code == "RU"
+        :yandex
+      elsif country_code == "CN"
+        :baidu
+      else
+        :google
+      end
+    end
+
 
 Advanced Querying
 -----------------
@@ -227,6 +267,11 @@ When querying for objects (if you're using ActiveRecord) you can also look withi
 
 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.
 
+You can also specify a minimum radius (if you're using ActiveRecord and not Sqlite) to constrain the
+lower bound (ie. think of a donut, or ring) by using the `:min_radius` option:
+
+    box = Geocoder::Calculations.bounding_box(center_point, distance, :min_radius => 10.5)
+
 
 Advanced Geocoding
 ------------------
@@ -258,10 +303,10 @@ Every `Geocoder::Result` object, `result`, provides the following data:
 If you're familiar with the results returned by the geocoding service you're using you can access even more data, but you'll need to be familiar with the particular `Geocoder::Result` object you're using and the structure of your geocoding service's responses. (See below for links to geocoding service documentation.)
 
 
-Geocoding Services
-------------------
+Geocoding Service ("Lookup") Configuration
+------------------------------------------
 
-By default Geocoder uses Google's geocoding API to fetch coordinates and street addresses (FreeGeoIP is the default for IP address info). However there are several other APIs supported, as well as a variety of settings. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). Some common configuration options are:
+Geocoder supports a variety of street and IP address geocoding services. The default lookups are `:google` for street addresses and `:freegeoip` for IP addresses. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). Some common configuration options are:
 
     # config/initializers/geocoder.rb
     Geocoder.configure(
@@ -269,6 +314,9 @@ By default Geocoder uses Google's geocoding API to fetch coordinates and street
       # geocoding service (see below for supported options):
       :lookup => :yandex,
 
+      # IP address geocoding service (see below for supported options):
+      :ip_lookup => :maxmind,
+
       # to use an API key:
       :api_key => "...",
 
@@ -294,8 +342,33 @@ Please see the [source code for each lookup](https://github.com/alexreisner/geoc
     # with Nominatim:
     Geocoder.search("Paris", :params => {:countrycodes => "gb,de,fr,es,us"})
 
+You can also configure multiple geocoding services at once, like this:
 
-### Listing and Comparison
+    Geocoder.configure(
+
+      :timeout => 2,
+      :cache => Redis.new,
+
+      :yandex => {
+        :api_key => "...",
+        :timeout => 5
+      },
+
+      :baidu => {
+        :api_key => "..."
+      },
+
+      :maxmind => {
+        :api_key => "...",
+        :service => :omni
+      }
+
+    )
+
+The above combines global and service-specific options and could be useful if you specify different geocoding services for different models or under different conditions. Lookup-specific settings override global settings so, for example, in the above the timeout for all lookups would be 2 seconds, except for Yandex which would be 5.
+
+
+### Street Address Services
 
 The following is a comparison of the supported geocoding APIs. The "Limitations" listed for each are a very brief and incomplete summary of some special limitations beyond basic data source attribution. Please read the official Terms of Service for a service before using it.
 
@@ -411,6 +484,17 @@ 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**: ?
 
+#### Here/Nokia (`:here`)
+
+* **API key**: required
+* **Quota**: Depending on the API key
+* **Region**: world
+* **SSL support**: yes
+* **Languages**: The preferred language of address elements in the result. Language code must be provided according to RFC 4647 standard.
+* **Documentation**: http://developer.here.com/rest-apis/documentation/geocoder
+* **Terms of Service**: http://developer.here.com/faqs#l&t
+* **Limitations**: ?
+
 #### ESRI (`:esri`)
 
 * **API key**: none
@@ -419,7 +503,7 @@ Yahoo BOSS is **not a free service**. As of November 17, 2012 Yahoo no longer of
 * **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
+* **Terms of Service**: http://www.esri.com/legal/software-license
 * **Limitations**: ?
 * **Notes**: You can specify which projection you want to use by setting, for example: `Geocoder.configure(:esri => {:outSR => 102100})`.
 
@@ -437,6 +521,53 @@ Data Science Toolkit provides an API whose reponse format is like Google's but w
 * **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")`.
 
+#### 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")`.
+
+#### CloudMade (`:cloudmade`)
+
+* **API key**: required
+* **Quota**: 100,000 free requests, then purchase 100,000 more for $15
+* **Region**: world
+* **SSL support**: yes ($5 per 100,000 requests)
+* **Languages**: en
+* **Documentation**: http://cloudmade.com/documentation/geocoding
+* **Terms of Service**: http://cloudmade.com/api-terms-of-service
+* **Limitations**: ?
+
+#### Geocodio (`:geocodio`)
+
+* **API key**: required
+* **Quota**: 2,500 free requests/day then purchase $.001 for each
+* **Region**: US
+* **SSL support**: no
+* **Languages**: en
+* **Documentation**: http://geocod.io/docs
+* **Terms of Service**: http://geocod.io/terms-of-use
+* **Limitations**: ?
+
+#### SmartyStreets (`:smarty_streets`)
+
+* **API key**: required
+* **Quota**: 10,000 free, 250/month then purchase at sliding scale. Unlimited free for nonprofits & startups
+* **Region**: US
+* **SSL support**: yes
+* **Languages**: en
+* **Documentation**: http://smartystreets.com/kb/liveaddress-api/rest-endpoint
+* **Terms of Service**: http://smartystreets.com/legal/terms-of-service
+* **Limitations**: No reverse geocoding.
+
+### IP Address Services
+
 #### FreeGeoIP (`:freegeoip`)
 
 * **API key**: none
@@ -460,7 +591,40 @@ Data Science Toolkit provides an API whose reponse format is like Google's but w
 * **Limitations**: ?
 * **Notes**: You must specify which MaxMind service you are using in your configuration. For example: `Geocoder.configure(:maxmind => {:service => :omni})`.
 
-#### Baidu (`:baidu`)
+#### MaxMind Local (`:maxmind_local`) - EXPERIMENTAL
+
+This lookup provides methods for geocoding IP addresses without making a call to a remote API (improves speed and availability). It works, but support is new and should not be considered production-ready. Please [report any bugs](https://github.com/alexreisner/geocoder/issues) you encounter.
+
+* **API key**: none (requires the GeoLite City database which can be downloaded from [MaxMind](http://dev.maxmind.com/geoip/legacy/geolite/))
+* **Quota**: none
+* **Region**: world
+* **SSL support**: N/A
+* **Languages**: English
+* **Documentation**: http://www.maxmind.com/en/city
+* **Terms of Service**: ?
+* **Limitations**: ?
+* **Notes**: There are two supported formats for MaxMind local data: binary file, and CSV file imported into an SQL database. **You must download a database from MaxMind and set either the `:file` or `:package` configuration option for local lookups to work.**
+
+**To use a binary file** you must add the *geoip* (or *jgeoip* for JRuby) gem to your Gemfile or have it installed in your system, and specify the path of the MaxMind database in your configuration. For example:
+
+    Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {file: File.join('folder', 'GeoLiteCity.dat')})
+
+**To use a CSV file** you must import it into an SQL database. The GeoLite *City* and *Country* packages are supported. Configure like so:
+
+    Geocoder.configure(ip_lookup: :maxmind_local, maxmind_local: {package: :city})
+
+You can generate ActiveRecord migrations and download and import data via provided rake tasks:
+
+    rails generate geocoder:maxmind:geolite_city
+
+    rake geocoder:maxmind:geolite_city:download
+    rake geocoder:maxmind:geolite_city:extract
+    rake geocoder:maxmind:geolite_city:insert
+    rake geocoder:maxmind:geolite_city:load # runs the above three in sequence
+
+You can replace `city` with `country` in any of the above tasks, generators, and configurations.
+
+#### Baidu IP (`:baidu_ip`)
 
 * **API key**: required
 * **Quota**: No quota limits for geocoding
@@ -470,7 +634,8 @@ Data Science Toolkit provides an API whose reponse format is like Google's but w
 * **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")`.
+* **Notes**: To use Baidu set `Geocoder.configure(:lookup => :baidu_ip, :api_key => "your_api_key")`.
+
 
 Caching
 -------

data/Rakefile

@@ -4,7 +4,7 @@ Bundler::GemHelper.install_tasks
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
-  test.pattern = 'test/*_test.rb'
+  test.pattern = 'test/unit/**/*_test.rb'
   test.verbose = true
 end
 

data/gemfiles/Gemfile.mongoid-2.4.x

@@ -6,6 +6,7 @@ group :development, :test do
   gem 'rake'
   gem 'mongoid', '2.4.11'
   gem 'bson_ext', :platforms => :ruby
+  gem 'geoip'
 
   gem 'rails'
 

data/lib/generators/geocoder/maxmind/geolite_city_generator.rb

@@ -0,0 +1,28 @@
+require 'rails/generators/migration'
+
+module Geocoder
+  module Generators
+    module Maxmind
+      class GeoliteCityGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+
+        source_root File.expand_path('../templates', __FILE__)
+
+        def copy_migration_files
+          migration_template "migration/geolite_city.rb", "db/migrate/geocoder_maxmind_geolite_city.rb"
+        end
+
+        # Define the next_migration_number method (necessary for the
+        # migration_template method to work)
+        def self.next_migration_number(dirname)
+          if ActiveRecord::Base.timestamped_migrations
+            sleep 1 # make sure each time we get a different timestamp
+            Time.new.utc.strftime("%Y%m%d%H%M%S")
+          else
+            "%.3d" % (current_migration_number(dirname) + 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/geocoder/maxmind/geolite_country_generator.rb

@@ -0,0 +1,28 @@
+require 'rails/generators/migration'
+
+module Geocoder
+  module Generators
+    module Maxmind
+      class GeoliteCountryGenerator < Rails::Generators::Base
+        include Rails::Generators::Migration
+
+        source_root File.expand_path('../templates', __FILE__)
+
+        def copy_migration_files
+          migration_template "migration/geolite_country.rb", "db/migrate/geocoder_maxmind_geolite_country.rb"
+        end
+
+        # Define the next_migration_number method (necessary for the
+        # migration_template method to work)
+        def self.next_migration_number(dirname)
+          if ActiveRecord::Base.timestamped_migrations
+            sleep 1 # make sure each time we get a different timestamp
+            Time.new.utc.strftime("%Y%m%d%H%M%S")
+          else
+            "%.3d" % (current_migration_number(dirname) + 1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/geocoder/maxmind/templates/migration/geolite_city.rb

@@ -0,0 +1,27 @@
+class GeocoderMaxmindGeoliteCity < ActiveRecord::Migration
+  def self.up
+    create_table :maxmind_geolite_city_blocks, id: false do |t|
+      t.column :start_ip_num, :bigint, null: false
+      t.column :end_ip_num, :bigint, null: false
+      t.column :loc_id, :bigint, null: false
+    end
+    add_index :maxmind_geolite_city_blocks, :start_ip_num, unique: true
+
+    create_table :maxmind_geolite_city_location, id: false do |t|
+      t.column :loc_id, :bigint, null: false
+      t.string :country, null: false
+      t.string :region, null: false
+      t.string :city
+      t.string :postal_code, null: false
+      t.float :latitude
+      t.float :longitude
+      t.integer :metro_code
+      t.integer :area_code
+    end
+    add_index :maxmind_geolite_city_location, :loc_id, unique: true
+  end
+
+  def self.down
+    drop_table :maxmind_geolite_city
+  end
+end