geocoder 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a859b82bf025e96ae97b006af3874e58766556b
-  data.tar.gz: 00eb37dfc6a988d08e3d4a2adcb924d0a778d9fa
+  metadata.gz: a3067b487565dbc6f761d20315246d3524e350a4
+  data.tar.gz: a2e89172c147db3050c203e6507da323e54d8a58
 SHA512:
-  metadata.gz: 71456df3a167a0aaa7511c4e61869519d5dd05716d7db7be38801e997525d3d257df5511a772206a7495392b2d65fcc88a5793744cf1360bc1579af83da0e227
-  data.tar.gz: 95faab5c456a219888ad92ba6cd64c6e27a7bc19cfd729ae2997b9e61849f247acd95f9e6c47f616530fee59d879c23b1496d83fe2d6db735c0552d858b6de6e
+  metadata.gz: 811f3224d6926014a1c910b605fd6644078c4808893552b8cedd31987650616323e54ba74564f20cbafbe61b39eb1b347e80912d69ab5c2f84153b4281800408
+  data.tar.gz: bc6301d8b24595749190b0d527ffcd8aecc1f8a804b1fc9cacc68bc7c61b92ea8f544940f09306a428653d65a28bc76536a7545cc76a5d3fd144e3a4c12aa86c

data/CHANGELOG.md

@@ -3,6 +3,13 @@ Changelog
 
 Major changes to Geocoder for each release. Please see the Git log for complete list of changes.
 
+1.4.1 (2016 Dec  2)
+-------------------
+* Add :location_iq lookup (thanks github.com/aleemuddin13 and glsignal).
+* Add :ban_data_gouv_fr lookup (thanks github.com/JulianNacci).
+* Fix :mapbox results when server returns no context (thanks github.com/jcmuller).
+* Deprecate methods in Geocoder::Calculations: to_kilometers, to_miles, to_nautical_miles, mi_in_km, km_in_mi, km_in_nm, nm_in_km.
+
 1.4.0 (2016 Sep  8)
 -------------------
 * Only consider an object geocoded if both lat and lon are present (previously was sufficient to have only one of the two) (thanks github.com/mltsy).

data/README.md

@@ -1,9 +1,9 @@
 Geocoder
 ========
 
-Geocoder is a complete geocoding solution for Ruby. With Rails it adds geocoding (by street or IP address), reverse geocoding (finding street address based on given coordinates), and distance queries. It's as simple as calling `geocode` on your objects, and then using a scope like `Venue.near("Billings, MT")`.
+Geocoder is a complete geocoding solution for Ruby. With Rails, it adds geocoding (by street or IP address), reverse geocoding (finding street address based on given coordinates), and distance queries. It's as simple as calling `geocode` on your objects, and then using a scope like `Venue.near("Billings, MT")`.
 
-_Please note that this README is for the current `HEAD` and may document features not present in the latest gem release. For this reason, you may want to instead view the README for your particular version._
+_Please note that this README is for the current `HEAD` and may document features not present in the latest gem release. For this reason, you may want to instead view the README for your [particular version](https://github.com/alexreisner/geocoder/releases)._
 
 
 Compatibility
@@ -47,7 +47,7 @@ Your model must have two attributes (database columns) for storing latitude and
     rails generate migration AddLatitudeAndLongitudeToModel latitude:float longitude:float
     rake db:migrate
 
-For geocoding your model must provide a method that returns an address. This can be a single attribute, but it can also be a method that returns a string assembled from different attributes (eg: `city`, `state`, and `country`).
+For geocoding, your model must provide a method that returns an address. This can be a single attribute, but it can also be a method that returns a string assembled from different attributes (eg: `city`, `state`, and `country`).
 
 Next, your model must tell Geocoder which method returns your object's geocodable address:
 
@@ -102,7 +102,7 @@ By default, the methods `geocoded_by` and `reverse_geocoded_by` create a geospat
 
 ### Bulk Geocoding
 
-If you have just added geocoding to an existing application with a lot of objects you can use this Rake task to geocode them all:
+If you have just added geocoding to an existing application with a lot of objects, you can use this Rake task to geocode them all:
 
     rake geocode:all CLASS=YourModel
 
@@ -244,16 +244,16 @@ If your model has `street`, `city`, `state`, and `country` attributes you might
       [street, city, state, country].compact.join(', ')
     end
 
-For reverse geocoding you can also specify an alternate name attribute where the address will be stored, for example:
+For reverse geocoding, you can also specify an alternate name attribute where the address will be stored. For example:
 
     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:
+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:
+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 }
 
@@ -278,7 +278,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. Note that `#near` performs both bounding box and radius queries for speed.
+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. Also 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:
@@ -293,7 +293,7 @@ With ActiveRecord, you can specify alternate latitude and longitude column names
 Advanced Geocoding
 ------------------
 
-So far we have looked at shortcuts for assigning geocoding results to object attributes. However, if you need to do something fancy you can skip the auto-assignment by providing a block (takes the object to be geocoded and an array of `Geocoder::Result` objects) in which you handle the parsed geocoding result any way you like, for example:
+So far we have looked at shortcuts for assigning geocoding results to object attributes. However, if you need to do something fancy, you can skip the auto-assignment by providing a block (takes the object to be geocoded and an array of `Geocoder::Result` objects) in which you handle the parsed geocoding result any way you like, for example:
 
     reverse_geocoded_by :latitude, :longitude do |obj,results|
       if geo = results.first
@@ -355,7 +355,7 @@ Some common configuration options are:
 
     )
 
-Please see lib/geocoder/configuration.rb for a complete list of configuration options. Additionally, some lookups have their own configuration options, some of which are directly supported by Geocoder. For example, to specify a value for Google's `bounds` parameter:
+Please see `lib/geocoder/configuration.rb` for a complete list of configuration options. Additionally, some lookups have their own configuration options, some of which are directly supported by Geocoder. For example, to specify a value for Google's `bounds` parameter:
 
     # with Google:
     Geocoder.search("Paris", :bounds => [[32.1,-95.9], [33.9,-94.3]])
@@ -392,7 +392,7 @@ You can also configure multiple geocoding services at once, like this:
 
     )
 
-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.
+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. In the above example, the timeout for all lookups would be 2 seconds, except for Yandex which would be 5.
 
 
 ### Street Address Services
@@ -457,6 +457,17 @@ The [Google Places Details API](https://developers.google.com/places/documentati
 * **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 (eg: `Geocoder.configure(:http_headers => { "User-Agent" => "your contact info" })`). [Data licensed under Open Database License (ODbL) (you must provide attribution).](http://www.openstreetmap.org/copyright)
 
+#### LocationIQ (`:location_iq`)
+
+* **API key**: required
+* **Quota**: 6 request/second (30k req/day), then ability to purchase more
+* **Region**: world
+* **SSL support**: yes
+* **Languages**: ?
+* **Documentation**: http://locationiq.org/#docs
+* **Terms of Service**: https://unwiredlabs.com/tos
+* **Limitations**: [Data licensed under Open Database License (ODbL) (you must provide attribution).](http://www.openstreetmap.org/copyright)
+
 #### OpenCageData (`:opencagedata`)
 
 * **API key**: required
@@ -591,7 +602,7 @@ The [Google Places Details API](https://developers.google.com/places/documentati
 
 #### 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.
+Data Science Toolkit provides an API whose response 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.
@@ -601,7 +612,7 @@ Data Science Toolkit provides an API whose reponse format is like Google's but w
 * **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")`.
+* **Notes**: If you are hosting your own DSTK server you will need to configure the host name, eg: `Geocoder.configure(:lookup => :dstk, :dstk => {:host => "localhost:4567"})`.
 
 #### Baidu (`:baidu`)
 
@@ -685,6 +696,16 @@ This uses the PostcodeAnywhere UK Geocode service, this will geocode any string
 * **Terms of Service**: ?
 * **Limitations**: No restrictions on use
 
+#### Base Adresse Nationale FR (`:ban_data_gouv_fr`)
+
+* **API key**: none
+* **Quota**: none
+* **Region**: FR
+* **SSL support**: yes
+* **Languages**: en / fr
+* **Documentation**: https://adresse.data.gouv.fr/api/ (in french)
+* **Terms of Service**: https://adresse.data.gouv.fr/faq/ (in french)
+* **Limitations**: [Data licensed under Open Database License (ODbL) (you must provide attribution).](http://openstreetmap.fr/ban)
 
 ### IP Address Services
 
@@ -848,7 +869,7 @@ You must add either the *[hive_geoip2](https://rubygems.org/gems/hive_geoip2)* g
 Caching
 -------
 
-It's a good idea, when relying on any external service, to cache retrieved data. When implemented correctly it improves your app's response time and stability. It's easy to cache geocoding results with Geocoder, just configure a cache store:
+When relying on any external service, it's always a good idea to cache retrieved data. When implemented correctly, it improves your app's response time and stability. It's easy to cache geocoding results with Geocoder -- just configure a cache store:
 
     Geocoder.configure(:cache => Redis.new)
 
@@ -875,9 +896,9 @@ If you need to expire cached content:
     # Be aware that this methods spawns a new Lookup object for each Service
     Geocoder::Lookup.all_services.each{|service| Geocoder::Lookup.get(service).cache.expire(:all)}
 
-Do *not* include the prefix when passing a URL to be expired. Expiring `:all` will only expire keys with the configured prefix (won't kill every entry in your key/value store).
+Do *not* include the prefix when passing a URL to be expired. Expiring `:all` will only expire keys with the configured prefix -- it will *not* expire every entry in your key/value store.
 
-For an example of a cache store with URL expiry please see examples/autoexpire_cache.rb
+For an example of a cache store with URL expiry, please see examples/autoexpire_cache.rb
 
 _Before you implement caching in your app please be sure that doing so does not violate the Terms of Service for your geocoding service._
 
@@ -885,7 +906,7 @@ _Before you implement caching in your app please be sure that doing so does not
 Forward and Reverse Geocoding in the Same Model
 -----------------------------------------------
 
-If you apply both forward and reverse geocoding functionality to the same model (say users can supply an address or coordinates and you want to fill in whatever's missing), you will provide two address methods:
+If you apply both forward and reverse geocoding functionality to the same model (i.e. users can supply an address or coordinates and you want to fill in whatever's missing), you will provide two address methods:
 
 * one for storing the fetched address (reverse geocoding)
 * one for providing an address to use when fetching coordinates (forward geocoding)
@@ -912,7 +933,7 @@ However, there can be only one set of latitude/longitude attributes, and whichev
       reverse_geocoded_by :latitude, :longitude
     end
 
-The reason for this is that we don't want ambiguity when doing distance calculations. We need a single, authoritative source for coordinates!
+We don't want ambiguity when doing distance calculations -- we need a single, authoritative source for coordinates!
 
 Once both forward and reverse geocoding has been applied, it is possible to call them sequentially.
 
@@ -924,11 +945,11 @@ For example:
 
     end
 
-For certain geolocation services such as Google geolocation API this may cause issues during subsequent updates to database records if the longtitude and latitude coordinates cannot be associated known location address (on a large body of water for example). On subsequent callbacks the following call:
+For certain geolocation services such as Google's geolocation API, this may cause issues during subsequent updates to database records if the longitude and latitude coordinates cannot be associated with a known location address (on a large body of water for example). On subsequent callbacks the following call:
 
      after_validation :geocode
 
-will alter the longtitude and latitude attributes based on the location field, which would be the closest known location to the original coordinates. In this case it is better to add conditions to each call, as not to override coordinates that do not have known location addresses associated with them.
+will alter the longitude and latitude attributes based on the location field, which would be the closest known location to the original coordinates. In this case it is better to add conditions to each call, as not to override coordinates that do not have known location addresses associated with them.
 
 For example:
 
@@ -988,8 +1009,10 @@ Now, any time Geocoder looks up "New York, NY" its results array will contain on
       ]
     )
 
-Note:
-  Keys must be strings not symbols when calling `add_stub` or `set_default_stub`. For example `'latitude' =>` not `:latitude =>`.
+Notes:
+
+- Keys must be strings not symbols when calling `add_stub` or `set_default_stub`. For example `'latitude' =>` not `:latitude =>`.
+- To clear stubs (e.g. prior to another spec), use `Geocoder::Lookup::Test.reset`. This will clear all stubs _including the default stub_.
 
 
 Command Line Interface
@@ -1007,7 +1030,7 @@ When you install the Geocoder gem it adds a `geocode` command to your shell. You
     Country:          United States
     Google map:       http://maps.google.com/maps?q=29.952211,-90.080563
 
-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.
+There are also a number of options for setting the geocoding API, key, and language, viewing the raw JSON response, and more. Please run `geocode -h` for details.
 
 Numeric Data Types and Precision
 --------------------------------
@@ -1040,16 +1063,16 @@ For consistency with the rest of Geocoder, always use the `to_coordinates` metho
 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:
+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
 
 Optimisation of Distance Queries
 --------------------------------
 
-In MySQL and Postgres the finding of objects near a given point is speeded up by using a bounding box to limit the number of points over which a full distance calculation needs to be done.
+In MySQL and Postgres, the finding of objects near a given point is sped up by using a bounding box to limit the number of points over which a full distance calculation needs to be done.
 
-To take advantage of this optimisation you need to add a composite index on latitude and longitude. In your Rails migration:
+To take advantage of this optimisation, you need to add a composite index on latitude and longitude. In your Rails migration:
 
     add_index :table, [:latitude, :longitude]
 
@@ -1150,7 +1173,7 @@ You can also fetch the response in the console:
 Reporting Issues
 ----------------
 
-When reporting an issue, please list the version of Geocoder you are using and any relevant information about your application (Rails version, database type and version, etc). Also avoid vague language like "it doesn't work." Please describe as specifically as you can what behavior your are actually seeing (eg: an error message? a nil return value?).
+When reporting an issue, please list the version of Geocoder you are using and any relevant information about your application (Rails version, database type and version, etc). Also avoid vague language like "it doesn't work." Please describe as specifically as you can what behavior you are actually seeing (eg: an error message? a nil return value?).
 
 Please DO NOT use GitHub issues to ask questions about how to use Geocoder. Sites like [StackOverflow](http://www.stackoverflow.com/) are a better forum for such discussions.
 

data/lib/geocoder/calculations.rb

@@ -10,12 +10,6 @@ module Geocoder
     #
     COMPASS_POINTS = %w[N NE E SE S SW W NW]
 
-    ##
-    # Radius of the Earth, in kilometers.
-    # Value taken from: http://en.wikipedia.org/wiki/Earth_radius
-    #
-    EARTH_RADIUS = 6371.0
-
     ##
     # Conversion factor: multiply by kilometers to get miles.
     #
@@ -31,6 +25,16 @@ module Geocoder
     #
     DEGREES_PER_RADIAN = 57.2957795
 
+    ##
+    # Radius of the Earth, in kilometers.
+    # Value taken from: http://en.wikipedia.org/wiki/Earth_radius
+    #
+    EARTH_RADII = {km: 6371.0}
+    EARTH_RADII[:mi] = EARTH_RADII[:km] * KM_IN_MI
+    EARTH_RADII[:nm] = EARTH_RADII[:km] * KM_IN_NM
+
+    EARTH_RADIUS = EARTH_RADII[:km] # TODO: deprecate this constant (use `EARTH_RADII[:km]`)
+
     # Not a number constant
     NAN = defined?(::Float::NAN) ? ::Float::NAN : 0 / 0.0
 
@@ -38,19 +42,13 @@ module Geocoder
     # Returns true if all given arguments are valid latitude/longitude values.
     #
     def coordinates_present?(*args)
-      args.each do |a|
-        # note that Float::NAN != Float::NAN
-        # still, this could probably be improved:
-        return false if (!a.is_a?(Numeric) or a.to_s == "NaN")
-      end
-      true
+      args.all? { |a| a.is_a? Numeric and !a.to_f.nan? }
     end
 
     ##
     # Distance spanned by one degree of latitude in the given units.
     #
     def latitude_degree_distance(units = nil)
-      units ||= Geocoder.config.units
       2 * Math::PI * earth_radius(units) / 360
     end
 
@@ -59,7 +57,6 @@ module Geocoder
     # This ranges from around 69 miles at the equator to zero at the poles.
     #
     def longitude_degree_distance(latitude, units = nil)
-      units ||= Geocoder.config.units
       latitude_degree_distance(units) * Math.cos(to_radians(latitude))
     end
 
@@ -80,10 +77,6 @@ module Geocoder
     #   Use Geocoder.configure(:units => ...) to configure default units.
     #
     def distance_between(point1, point2, options = {})
-
-      # set default options
-      options[:units] ||= Geocoder.config.units
-
       # convert to coordinate arrays
       point1 = extract_coordinates(point1)
       point2 = extract_coordinates(point2)
@@ -212,12 +205,11 @@ module Geocoder
     def bounding_box(point, radius, options = {})
       lat,lon = extract_coordinates(point)
       radius  = radius.to_f
-      units   = options[:units] || Geocoder.config.units
       [
-        lat - (radius / latitude_degree_distance(units)),
-        lon - (radius / longitude_degree_distance(lat, units)),
-        lat + (radius / latitude_degree_distance(units)),
-        lon + (radius / longitude_degree_distance(lat, units))
+        lat - (radius / latitude_degree_distance(options[:units])),
+        lon - (radius / longitude_degree_distance(lat, options[:units])),
+        lat + (radius / latitude_degree_distance(options[:units])),
+        lon + (radius / longitude_degree_distance(lat, options[:units]))
       ]
     end
 
@@ -239,10 +231,6 @@ module Geocoder
     #   Use Geocoder.configure(:units => ...) to configure default units.
     # * <tt>:seed</tt> - The seed for the random number generator
     def random_point_near(center, radius, options = {})
-
-      # set default options
-      options[:units] ||= Geocoder.config.units
-
       random = Random.new(options[:seed] || Random.new_seed)
 
       # convert to coordinate arrays
@@ -274,7 +262,6 @@ module Geocoder
     #   which returns a [lat,lon] array
     #
     def endpoint(start, heading, distance, options = {})
-      options[:units] ||= Geocoder.config.units
       radius = earth_radius(options[:units])
 
       start = extract_coordinates(start)
@@ -325,12 +312,10 @@ module Geocoder
     end
 
     def distance_to_radians(distance, units = nil)
-      units ||= Geocoder.config.units
       distance.to_f / earth_radius(units)
     end
 
     def radians_to_distance(radians, units = nil)
-      units ||= Geocoder.config.units
       radians * earth_radius(units)
     end
 
@@ -338,6 +323,7 @@ module Geocoder
     # Convert miles to kilometers.
     #
     def to_kilometers(mi)
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.to_kilometers is deprecated and will be removed in Geocoder 1.5.0. Please multiply by MI_IN_KM instead.")
       mi * mi_in_km
     end
 
@@ -345,14 +331,16 @@ module Geocoder
     # Convert kilometers to miles.
     #
     def to_miles(km)
-      km * km_in_mi
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.to_miles is deprecated and will be removed in Geocoder 1.5.0. Please multiply by KM_IN_MI instead.")
+      km * KM_IN_MI
     end
 
     ##
     # Convert kilometers to nautical miles.
     #
     def to_nautical_miles(km)
-      km * km_in_nm
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.to_nautical_miles is deprecated and will be removed in Geocoder 1.5.0. Please multiply by KM_IN_NM instead.")
+      km * KM_IN_NM
     end
 
     ##
@@ -360,18 +348,14 @@ module Geocoder
     # Use Geocoder.configure(:units => ...) to configure default units.
     #
     def earth_radius(units = nil)
-      units ||= Geocoder.config.units
-      case units
-        when :km; EARTH_RADIUS
-        when :mi; to_miles(EARTH_RADIUS)
-        when :nm; to_nautical_miles(EARTH_RADIUS)
-      end
+      EARTH_RADII[units || Geocoder.config.units]
     end
 
     ##
     # Conversion factor: km to mi.
     #
     def km_in_mi
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.km_in_mi is deprecated and will be removed in Geocoder 1.5.0. Please use the constant KM_IN_MI instead.")
       KM_IN_MI
     end
 
@@ -379,15 +363,15 @@ module Geocoder
     # Conversion factor: km to nm.
     #
     def km_in_nm
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.km_in_nm is deprecated and will be removed in Geocoder 1.5.0. Please use the constant KM_IN_NM instead.")
       KM_IN_NM
     end
 
-
-
     ##
     # Conversion factor: mi to km.
     #
     def mi_in_km
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.mi_in_km is deprecated and will be removed in Geocoder 1.5.0. Please use 1.0 / KM_IN_MI instead.")
       1.0 / KM_IN_MI
     end
 
@@ -395,6 +379,7 @@ module Geocoder
     # Conversion factor: nm to km.
     #
     def nm_in_km
+      Geocoder.log(:warn, "DEPRECATION WARNING: Geocoder::Calculations.nm_in_km is deprecated and will be removed in Geocoder 1.5.0. Please use 1.0 / KM_IN_NM instead.")
       1.0 / KM_IN_NM
     end
 
@@ -407,13 +392,8 @@ module Geocoder
     def extract_coordinates(point)
       case point
       when Array
-        if point.size == 2
-          lat, lon = point
-          if !lat.nil? && lat.respond_to?(:to_f) and
-            !lon.nil? && lon.respond_to?(:to_f)
-          then
-            return [ lat.to_f, lon.to_f ]
-          end
+        if point.size == 2 and coordinates_present?(*point)
+          return point.map {|coords| coords.to_f}
         end
       when String
         point = Geocoder.coordinates(point) and return point
@@ -428,4 +408,3 @@ module Geocoder
     end
   end
 end
-

data/lib/geocoder/lookup.rb

@@ -23,6 +23,7 @@ module Geocoder
     #
     def street_services
       @street_services ||= [
+        :location_iq,
         :dstk,
         :esri,
         :google,
@@ -46,6 +47,7 @@ module Geocoder
         :okf,
         :postcode_anywhere_uk,
         :geoportail_lu,
+        :ban_data_gouv_fr,
         :test,
         :latlon
       ]

data/lib/geocoder/lookups/ban_data_gouv_fr.rb

@@ -0,0 +1,130 @@
+# encoding: utf-8
+
+require 'geocoder/lookups/base'
+require 'geocoder/results/ban_data_gouv_fr'
+
+module Geocoder::Lookup
+  class BanDataGouvFr < Base
+
+    def name
+      "Base Adresse Nationale Française"
+    end
+
+    def map_link_url(coordinates)
+      "https://www.openstreetmap.org/#map=19/#{coordinates.join('/')}"
+    end
+
+    def query_url(query)
+      method = query.reverse_geocode? ? "reverse" : "search"
+      "#{protocol}://api-adresse.data.gouv.fr/#{method}/?" + url_query_string(query)
+    end
+
+    private # ---------------------------------------------------------------
+
+    def any_result?(doc)
+      doc['features'].any?
+    end
+
+    def results(query)
+      if doc = fetch_data(query) and any_result?(doc)
+        [doc]
+      else
+        []
+      end
+    end
+
+    #### PARAMS ####
+
+    def query_url_params(query)
+      query_ban_datagouv_fr_params(query).merge(super)
+    end
+
+    def query_ban_datagouv_fr_params(query)
+      query.reverse_geocode? ? reverse_geocode_ban_fr_params(query) : search_geocode_ban_fr_params(query)
+    end
+
+    #### SEARCH GEOCODING PARAMS ####
+    #
+    #  :q             =>    required, full text search param)
+
+    #  :limit         =>    force limit number of results returned by raw API
+    #                       (default = 5) note : only first result is taken
+    #                       in account in geocoder
+    #
+    #  :autocomplete  =>    pass 0 to disable autocomplete treatment of :q
+    #                       (default = 1)
+    #
+    #  :lat           =>    force filter results around specific lat/lon
+    #
+    #  :lon           =>    force filter results around specific lat/lon
+    #
+    #  :type          =>    force filter the returned result type
+    #                       (check results for a list of accepted types)
+    #
+    #  :postcode      =>    force filter results on a specific city post code
+    #
+    #  :citycode      =>    force filter results on a specific city UUID INSEE code
+    #
+    #  For up to date doc (in french only) : https://adresse.data.gouv.fr/api/
+    #
+    def search_geocode_ban_fr_params(query)
+      params = {
+        q: query.sanitized_text
+      }
+      unless (limit = query.options[:limit]).nil? || !limit_param_is_valid?(limit)
+        params[:limit] = limit.to_i
+      end
+      unless (autocomplete = query.options[:autocomplete]).nil? || !autocomplete_param_is_valid?(autocomplete)
+        params[:autocomplete] = autocomplete.to_s
+      end
+      unless (type = query.options[:type]).nil? || !type_param_is_valid?(type)
+        params[:type] = type.downcase
+      end
+      unless (postcode = query.options[:postcode]).nil? || !code_param_is_valid?(postcode)
+        params[:postcode] = postcode.to_s
+      end
+      unless (citycode = query.options[:citycode]).nil? || !code_param_is_valid?(citycode)
+        params[:citycode] = citycode.to_s
+      end
+      params
+    end
+
+    #### REVERSE GEOCODING PARAMS ####
+    #
+    #  :lat           =>    required
+    #
+    #  :lon           =>    required
+    #
+    #  :type          =>    force returned results type
+    #                       (check results for a list of accepted types)
+    #
+    def reverse_geocode_ban_fr_params(query)
+      lat_lon = query.coordinates
+      params = {
+          lat: lat_lon.first,
+          lon: lat_lon.last
+      }
+      unless (type = query.options[:type]).nil? || !type_param_is_valid?(type)
+        params[:type] = type.downcase
+      end
+      params
+    end
+
+    def limit_param_is_valid?(param)
+      param.to_i.positive?
+    end
+
+    def autocomplete_param_is_valid?(param)
+      [0,1].include?(param.to_i)
+    end
+
+    def type_param_is_valid?(param)
+      %w(housenumber street locality village town city).include?(param.downcase)
+    end
+
+    def code_param_is_valid?(param)
+      (1..99999).include?(param.to_i)
+    end
+
+  end
+end

data/lib/geocoder/lookups/location_iq.rb

@@ -0,0 +1,32 @@
+require 'geocoder/lookups/nominatim'
+require "geocoder/results/location_iq"
+
+module Geocoder::Lookup
+  class LocationIq < Nominatim
+    def name
+      "LocationIq"
+    end
+
+    def required_api_key_parts
+      ["api_key"]
+    end
+    
+    def query_url(query)
+      method = query.reverse_geocode? ? "reverse.php" : "search.php"
+      host = configuration[:host] || "locationiq.org/v1"
+      "#{protocol}://#{host}/#{method}?key=#{configuration.api_key}&" + url_query_string(query)
+    end
+
+    private
+
+    def results(query)
+      return [] unless doc = fetch_data(query)
+
+      if !doc.is_a?(Array) && doc['error'] =~ /Invalid\skey/
+        raise_error(Geocoder::InvalidApiKey, doc['error'])
+      end
+
+      doc.is_a?(Array) ? doc : [doc]
+    end
+  end
+end

data/lib/geocoder/lookups/opencagedata.rb

@@ -47,6 +47,12 @@ module Geocoder::Lookup
         :language => (query.language || configuration.language)
       }.merge(super)
 
+      [:countrycode, :min_confidence, :no_dedupe, :no_annotations, :no_record, :limit].each do |option|
+        unless (option_value = query.options[option]).nil?
+          params[option] = option_value
+        end
+      end
+
       unless (bounds = query.options[:bounds]).nil?
         params[:bounds] = bounds.map{ |point| "%f,%f" % point }.join(',')
       end

data/lib/geocoder/results/ban_data_gouv_fr.rb

@@ -0,0 +1,257 @@
+# encoding: utf-8
+require 'geocoder/results/base'
+
+module Geocoder::Result
+  class BanDataGouvFr < Base
+
+    #### BASE METHODS ####
+
+    def self.response_attributes
+      %w[limit attribution version licence type features]
+    end
+
+    response_attributes.each do |a|
+      unless method_defined?(a)
+        define_method a do
+          @data[a]
+        end
+      end
+    end
+
+    #### BEST RESULT ####
+
+    def result
+      features[0] if features.any?
+    end
+
+    #### GEOMETRY ####
+
+    def geometry
+      result['geometry'] if result
+    end
+
+    def precision
+      geometry['type'] if geometry
+    end
+
+    def coordinates
+      coords = geometry["coordinates"]
+      return [coords[1].to_f, coords[0].to_f]
+    end
+
+    #### PROPERTIES ####
+
+    # List of raw attrbutes returned by BAN data gouv fr API:
+    #
+    #   :id           =>    [string] UUID of the result, said to be not stable
+    #                       atm, based on IGN reference (Institut national de
+    #                       l'information géographique et forestière)
+    #
+    #   :type         =>    [string] result type (housenumber, street, city,
+    #                       town, village, locality)
+    #
+    #   :score        =>    [float] value between 0 and 1 giving result's
+    #                       relevancy
+    #
+    #   :housenumber  =>    [string] street number and extra information
+    #                       (bis, ter, A, B)
+    #
+    #   :street       =>    [string] street name
+    #
+    #   :name         =>    [string] housenumber and street name
+    #
+    #   :postcode     =>    [string] city post code (used for mails by La Poste,
+    #                       beware many cities got severeal postcodes)
+    #
+    #   :citycode     =>    [string] city code (INSEE reference,
+    #                       consider it as a french institutional UUID)
+    #
+    #   :city         =>    [string] city name
+    #
+    #   :context      =>    [string] department code, department name and
+    #                       region code
+    #
+    #   :label        =>    [string] full address without state, country name
+    #                       and country code
+    #
+    # CITIES ONLY PROPERTIES
+    #
+    #   :adm_weight   =>    [string] administrative weight (importance) of
+    #                       the city
+    #
+    #   :population   =>    [float] number of inhabitants with a 1000 factor
+    #
+    # For up to date doc (in french only) : https://adresse.data.gouv.fr/api/
+    #
+    def properties
+      result['properties'] if result
+    end
+
+    # List of usable Geocoder results' methods
+    #
+    #   score                   =>    [float] result relevance 0 to 1
+    #
+    #   location_id             =>    [string] location's IGN UUID
+    #
+    #   result_type             =>    [string] housenumber / street / city
+    #                                 / town / village / locality
+    #
+    #   international_address   =>    [string] full address with country code
+    #
+    #   national_address        =>    [string] full address with country code
+    #
+    #   street_address          =>    [string] housenumber + extra inf
+    #                                 + street name
+    #
+    #   street_number           =>    [string] housenumber + extra inf
+    #                                 (bis, ter, etc)
+    #
+    #   street_name             =>    [string] street's name
+    #
+    #   city_name               =>    [string] city's name
+    #
+    #   city_code               =>    [string] city's INSEE UUID
+    #
+    #   postal_code             =>    [string] city's postal code (used for mails)
+    #
+    #   context                 =>    [string] city's department code, department
+    #                                  name and region name
+    #
+    #   demartment_name         =>    [string] city's department name
+    #
+    #   department_code         =>    [string] city's department INSEE UUID
+    #
+    #   region_name             =>    [string] city's region name
+    #
+    #   population              =>    [string] city's inhabitants count
+    #
+    #   administrative_weight   =>    [integer] city's importance on a scale
+    #                                 from 6 (capital city) to 1 (regular village)
+    #
+    def score
+      properties['score']
+    end
+
+    def location_id
+      properties['id']
+    end
+
+    # Types
+    #
+    #   housenumber
+    #   street
+    #   city
+    #   town
+    #   village
+    #   locality
+    #
+    def result_type
+      properties['type']
+    end
+
+    def international_address
+      "#{national_address}, #{country}"
+    end
+
+    def national_address
+      properties['label']
+    end
+
+    def street_address
+      properties['name']
+    end
+
+    def street_number
+      properties['housenumber']
+    end
+
+    def street_name
+      properties['street']
+    end
+
+    def city_name
+      properties['city']
+    end
+
+    def city_code
+      properties['citycode']
+    end
+
+    def postal_code
+      properties['postcode']
+    end
+
+    def context
+      properties['context'].split(/,/).map(&:strip)
+    end
+
+    def department_code
+      context[0] if context.length > 0
+    end
+
+    # Monkey logic to handle fact Paris is both a city and a department
+    # in Île-de-France region
+    def department_name
+      if context.length > 1
+        if context[1] == "Île-de-France"
+          "Paris"
+        else
+          context[1]
+        end
+      end
+    end
+
+    def region_name
+      if context.length == 2 && context[1] == "Île-de-France"
+        context[1]
+      elsif context.length > 2
+        context[2]
+      end
+    end
+
+    def country
+      "France"
+    end
+
+    # Country code types
+    #    FR : France
+    #    GF : Guyane Française
+    #    RE : Réunion
+    #    NC : Nouvelle-Calédonie
+    #    GP : Guadeloupe
+    #    MQ : Martinique
+    #    MU : Maurice
+    #    PF : Polynésie française
+    #
+    # Will need refacto to handle different country codes, but BAN API
+    # is currently mainly designed for geocode FR country code addresses
+    def country_code
+      "FR"
+    end
+
+    #### ALIAS METHODS ####
+
+    alias_method :address, :international_address
+    alias_method :street, :street_name
+    alias_method :city, :city_name
+    alias_method :state, :region_name
+    alias_method :state_code, :state
+
+    #### CITIES' METHODS ####
+
+    def population
+      (properties['population'].to_f * 1000).to_i if city?(result_type)
+    end
+
+    def administrative_weight
+      properties['adm_weight'].to_i if city?(result_type)
+    end
+
+    private
+
+    def city?(result_type)
+      %w(village town city).include?(result_type)
+    end
+
+  end
+end

data/lib/geocoder/results/google_places_details.rb

@@ -30,6 +30,10 @@ module Geocoder
       def website
         @data["website"]
       end
+
+      def photos
+        @data["photos"]
+      end
     end
   end
 end

data/lib/geocoder/results/location_iq.rb

@@ -0,0 +1,6 @@
+require 'geocoder/results/nominatim'
+
+module Geocoder::Result
+  class LocationIq < Nominatim
+  end
+end

data/lib/geocoder/results/mapbox.rb

@@ -4,43 +4,53 @@ module Geocoder::Result
   class Mapbox < Base
 
     def coordinates
-      @data["geometry"]["coordinates"].reverse.map(&:to_f)
+      data['geometry']['coordinates'].reverse.map(&:to_f)
     end
 
     def place_name
-      @data['text']
+      data['text']
     end
 
     def street
-      @data['properties']['address']
+      data['properties']['address']
     end
 
     def city
-      @data['context'].map { |c| c['text'] if c['id'] =~ /place/ }.compact.first
+      context_part('place')
     end
 
     def state
-      @data['context'].map { |c| c['text'] if c['id'] =~ /region/ }.compact.first
+      context_part('region')
     end
 
     alias_method :state_code, :state
 
     def postal_code
-      @data['context'].map { |c| c['text'] if c['id'] =~ /postcode/ }.compact.first
+      context_part('postcode')
     end
 
     def country
-      @data['context'].map { |c| c['text'] if c['id'] =~ /country/ }.compact.first
+      context_part('country')
     end
 
     alias_method :country_code, :country
 
     def neighborhood
-      @data['context'].map { |c| c['text'] if c['id'] =~ /neighborhood/ }.compact.first
+      context_part('neighborhood')
     end
 
     def address
-      [place_name, street, city, state, postal_code, country].compact.join(", ")
+      [place_name, street, city, state, postal_code, country].compact.join(', ')
+    end
+
+    private
+
+    def context_part(name)
+      context.map { |c| c['text'] if c['id'] =~ Regexp.new(name) }.compact.first
+    end
+
+    def context
+      Array(data['context'])
     end
   end
 end

data/lib/geocoder/version.rb

@@ -1,3 +1,3 @@
 module Geocoder
-  VERSION = "1.4.0"
+  VERSION = "1.4.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geocoder
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Alex Reisner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-08 00:00:00.000000000 Z
+date: 2016-12-02 00:00:00.000000000 Z
 dependencies: []
 description: Provides object geocoding (by street or IP address), reverse geocoding
   (coordinates to street address), distance queries for ActiveRecord and Mongoid,
@@ -49,6 +49,7 @@ files:
 - lib/geocoder/lookup.rb
 - lib/geocoder/lookups/baidu.rb
 - lib/geocoder/lookups/baidu_ip.rb
+- lib/geocoder/lookups/ban_data_gouv_fr.rb
 - lib/geocoder/lookups/base.rb
 - lib/geocoder/lookups/bing.rb
 - lib/geocoder/lookups/dstk.rb
@@ -66,6 +67,7 @@ files:
 - lib/geocoder/lookups/ipapi_com.rb
 - lib/geocoder/lookups/ipinfo_io.rb
 - lib/geocoder/lookups/latlon.rb
+- lib/geocoder/lookups/location_iq.rb
 - lib/geocoder/lookups/mapbox.rb
 - lib/geocoder/lookups/mapquest.rb
 - lib/geocoder/lookups/mapzen.rb
@@ -93,6 +95,7 @@ files:
 - lib/geocoder/request.rb
 - lib/geocoder/results/baidu.rb
 - lib/geocoder/results/baidu_ip.rb
+- lib/geocoder/results/ban_data_gouv_fr.rb
 - lib/geocoder/results/base.rb
 - lib/geocoder/results/bing.rb
 - lib/geocoder/results/dstk.rb
@@ -110,6 +113,7 @@ files:
 - lib/geocoder/results/ipapi_com.rb
 - lib/geocoder/results/ipinfo_io.rb
 - lib/geocoder/results/latlon.rb
+- lib/geocoder/results/location_iq.rb
 - lib/geocoder/results/mapbox.rb
 - lib/geocoder/results/mapquest.rb
 - lib/geocoder/results/mapzen.rb