geocoder 0.9.13 → 1.0.0

data/CHANGELOG.rdoc

@@ -2,6 +2,15 @@
 
 Per-release changes to Geocoder.
 
+== 1.0.0 (2011 May 9)
+
+* Add command line interface.
+* Add support for local proxy (thanks github.com/Olivier).
+* Add support for Yandex.ru geocoding service.
+* Add support for Bing geocoding service (thanks github.com/astevens).
+* Fix single table inheritance bug (reported by github.com/enrico).
+* Fix bug when Google result supplies no city (thanks github.com/jkeen).
+
 == 0.9.13 (2011 Apr 11)
 
 * Fix "can't find special index: 2d" error when using Mongoid with Ruby 1.8.
@@ -23,9 +32,9 @@ Per-release changes to Geocoder.
 * Add support for Geocoder.ca geocoding service.
 * Add +bearing+ attribute to objects returned by geo-aware queries (thanks github.com/matellis).
 * Add config setting: language.
-* Add config settings: use_https, google_api_key (thanks github.com/svesely).
-* DEPRECATION: Geocoder.search now returns an array instead of a single result.
-* DEPRECATION: obj.nearbys second argument is now an options hash (instead of units). Please change <tt>obj.nearbys(20, :km)</tt> to: <tt>obj.nearbys(20, :units => :km)</tt>.
+* Add config settings: +use_https+, +google_api_key+ (thanks github.com/svesely).
+* DEPRECATION: <tt>Geocoder.search</tt> now returns an array instead of a single result.
+* DEPRECATION: <tt>obj.nearbys</tt> second argument is now an options hash (instead of units). Please change <tt>obj.nearbys(20, :km)</tt> to: <tt>obj.nearbys(20, :units => :km)</tt>.
 
 == 0.9.10 (2011 Mar 9)
 
@@ -42,15 +51,15 @@ Per-release changes to Geocoder.
 * Gem now works outside of Rails.
 * DEPRECATION: +fetch_coordinates+ no longer takes an argument.
 * DEPRECATION: +fetch_address+ no longer takes an argument.
-* DEPRECATION: Geocoder.search now returns a single result instead of an array.
+* DEPRECATION: <tt>Geocoder.search</tt> now returns a single result instead of an array.
 * DEPRECATION: <tt>fetch_coordinates!</tt> has been superceded by +geocode+ (then save your object manually).
 * DEPRECATION: <tt>fetch_address!</tt> has been superceded by +reverse_geocode+ (then save your object manually).
 * Fix: don't die when trying to get coordinates with a nil address (github.com/zmack).
 
 == 0.9.8 (2011 Feb 8)
 
-* Include geocode:all Rake task in gem (was missing!).
-* Add Geocoder.search for access to Google's full response.
+* Include <tt>geocode:all</tt> Rake task in gem (was missing!).
+* Add <tt>Geocoder.search</tt> for access to Google's full response.
 * Add ability to configure Google connection timeout.
 * Emit warnings on Google connection problems and errors.
 * Refactor: insert Geocoder into ActiveRecord via Railtie.
@@ -133,7 +142,7 @@ Per-release changes to Geocoder.
 
 == 0.8.1 (2009 Oct 8)
 
-* Extract XML-fetching code from Geocoder.search and place in Geocoder._fetch_xml (for ease of mocking).
+* Extract XML-fetching code from <tt>Geocoder.search</tt> and place in Geocoder._fetch_xml (for ease of mocking).
 * Add tests for coordinate-fetching instance methods.
 
 == 0.8.0 (2009 Oct 1)

data/README.rdoc

@@ -208,68 +208,121 @@ Every <tt>Geocoder::Result</tt> object, +result+, provides the following data:
 * <tt>result.coordinates</tt> - array of the above two
 * <tt>result.address</tt> - string
 * <tt>result.city</tt> - string
+* <tt>result.state</tt> - string
+* <tt>result.state_code</tt> - string
 * <tt>result.postal_code</tt> - string
 * <tt>result.country_name</tt> - string
 * <tt>result.country_code</tt> - string
 
-and if you're familiar with the results returned by the geocoding service you're using, you can access even more (see code comments for details: <tt>lib/geocoder/results/*</tt>).
+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 <tt>Geocoder::Result</tt> object you're using and the structure of your geocoding service's responses. (See below for links to geocoding service documentation.)
 
 
 == Geocoding Services
 
-By default Geocoder uses Google's geocoding API to fetch coordinates and addresses. However if you wish to use Yahoo's geocoding API you can simply add this to an initializer:
+By default Geocoder uses Google's geocoding API to fetch coordinates and street addresses (FreeGeoIP is used 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). The configuration options are:
 
   # config/initializers/geocoder.rb
-  Geocoder::Configuration.lookup = :yahoo
-
-Street address geocoding services currently supported (valid settings for the above):
-
-* Google: <tt>:google</tt>
-* Yahoo: <tt>:yahoo</tt>
-* Geocoder.ca: <tt>:geocoder_ca</tt> (US and Canada only)
-
-Note that the result objects returned by different geocoding services all implement the methods listed above. Beyond that, however, you must be familiar with your particular subclass of <tt>Geocoder::Result</tt> and the geocoding service's result structure:
 
-* Google: http://code.google.com/apis/maps/documentation/geocoding/#JSON
-* Yahoo: http://developer.yahoo.com/geo/placefinder/guide/responses.html
-* Geocoder.ca: (???)
-* FreeGeoIP: http://github.com/fiorix/freegeoip/blob/master/README.rst
-
-=== API Keys
-
-To use your Google API key or Yahoo app ID:
+  # geocoding service (see below for supported options):
+  Geocoder::Configuration.lookup = :yahoo
 
+  # to use an API key:
   Geocoder::Configuration.api_key = "..."
 
-To obtain an API key (not required):
-
-* Yahoo: https://developer.apps.yahoo.com/wsregapp
-* Google: http://code.google.com/apis/maps/signup.html
-
-=== Timeout
-
-You can set the timeout used for connections to the geocoding service. The default is 3 seconds but if you want to set it to 5, for example, put the following in an initializer:
-
+  # geocoding service request timeout, in seconds (default 3):
   Geocoder::Configuration.timeout = 5
 
-=== Language
-
-You can set the language used for reverse geocoding results to German, for example, by setting the following:
+  # use HTTPS for geocoding service connections:
+  Geocoder::Configuration.use_https = true
 
+  # language to use (for search queries and reverse geocoding):
   Geocoder::Configuration.language = :de
 
-For a list of supported languages see the documentation for the geocoding service you're using.
-
-=== HTTPS
+  # use a proxy to access the service:
+  Geocoder::Configuration.http_proxy  = "127.4.4.1"
+  Geocoder::Configuration.https_proxy = "127.4.4.2" # only if HTTPS is needed
 
-If you want to use HTTPS for geocoding service connections:
-
-  Geocoder::Configuration.use_https = true
-
-Note that currently the only service that supports HTTPS is Google.
+  # caching (see below for details)
+  Geocoder::Configuration.cache = Redis.new
+  Geocoder::Configuration.cache_prefix = "..."
 
 
-== Caching Results
+=== Listing and Comparison
+
+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.
+
+==== Google (<tt>:google</tt>)
+
+API key:: optional (required for Premier)
+Key signup:: http://code.google.com/apis/maps/signup.html
+Quota:: 2,500 requests/day, 100,000 with Google Maps API Premier
+Region:: world
+SSL support:: yes
+Languages:: ar, eu, bg, bn, ca, cs, da, de, el, en, en-AU, en-GB, es, eu, fa, fi, fil, fr, gl, gu, hi, hr, hu, id, it, iw, ja, kn, ko, lt, lv, ml, mr, nl, no, pl, pt, pt-BR, pt-PT, ro, ru, sk, sl, sr, sv, tl, ta, te, th, tr, uk, vi, zh-CN, zh-TW (see http://spreadsheets.google.com/pub?key=p9pdwsai2hDMsLkXsoM05KQ&gid=1)
+Documentation:: http://code.google.com/apis/maps/documentation/geocoding/#JSON
+Terms of Service:: http://code.google.com/apis/maps/terms.html#section_10_12
+Limitations:: "You must not use or display the Content without a corresponding Google map, unless you are explicitly permitted to do so in the Maps APIs Documentation, or through written permission from Google." "You must not pre-fetch, cache, or store any Content, except that you may store: (i) limited amounts of Content for the purpose of improving the performance of your Maps API Implementation..."
+
+==== Yahoo (<tt>:yahoo</tt>)
+
+API key:: optional in development (required for production apps)
+Key signup:: https://developer.apps.yahoo.com/wsregapp
+Quota:: 50,000 requests/day, more available by special arrangement
+Region:: world
+SSL support:: no
+Languages:: ?
+Documentation:: http://developer.yahoo.com/geo/placefinder/guide/responses.html
+Terms of Service:: http://info.yahoo.com/legal/us/yahoo/maps/mapsapi/mapsapi-2141.html
+Limitations:: "YOU SHALL NOT... (viii) store or allow end users to store map imagery, map data or geocoded location information from the Yahoo! Maps APIs for any future use; (ix) use the stand-alone geocoder for any use other than displaying Yahoo! Maps or displaying points on Yahoo! Maps;"
+
+==== Bing (<tt>:bing</tt>)
+
+API key:: required
+Key signup:: http://www.bingmapsportal.com
+Quota:: 50,000 requests/24 hrs
+Region:: world
+SSL support:: no
+Languages:: ?
+Documentation:: http://msdn.microsoft.com/en-us/library/ff701715.aspx
+Terms of Service:: http://www.microsoft.com/maps/product/terms.html
+Limitations:: No country codes or state names. Must be used on "public-facing, non-password protected web sites," "in conjunction with Bing Maps or an application that integrates Bing Maps."
+
+==== Yandex (<tt>:yandex</tt>)
+
+API key:: required
+Key signup:: http://api.yandex.ru/maps/intro/concepts/intro.xml#apikey
+Quota:: ?
+Region:: Russia
+SSL support:: no
+Languages:: Russian, Belarusian, and Ukrainian
+Documentation:: http://api.yandex.ru/maps/geocoder/doc/desc/concepts/response_structure.xml
+Terms of Service:: http://api.yandex.com/direct/eula.xml?ncrnd=8453
+Limitations:: ?
+
+==== Geocoder.ca (<tt>:geocoder_ca</tt>)
+
+API key:: none
+Quota:: ?
+Region:: US and Canada
+SSL support:: no
+Languages:: English
+Documentation:: ?
+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."
+
+==== FreeGeoIP
+
+API key:: none
+Quota:: ?
+Region:: world
+SSL support:: no
+Languages:: English
+Documentation:: http://github.com/fiorix/freegeoip/blob/master/README.rst
+Terms of Service:: ?
+Limitations:: ?
+
+
+== 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:
 
@@ -296,6 +349,8 @@ If you need to expire cached content:
 
 Do *not* include the prefix when passing a URL to be expired. Expiring <tt>:all</tt> will only expire keys with the configured prefix (won't kill every entry in your key/value store).
 
+<i>Before you implement caching in your app please be sure that doing so does not violate the Terms of Service for your geocoding service.</i>
+
 
 == Forward and Reverse Geocoding in the Same Model
 
@@ -338,6 +393,23 @@ You can use Geocoder outside of Rails by calling the <tt>Geocoder.search</tt> me
 This returns an array of <tt>Geocoder::Result</tt> objects with all information provided by the geocoding service. Please see above and in the code for details.
 
 
+== Command Line Interface
+
+When you install the Geocoder gem it adds a +geocode+ command to your shell. You can search for a street address, IP address, postal code, coordinates, etc just like you can with the Geocoder.search method for example:
+
+  $ geocode 29.951,-90.081
+  Latitude:         29.952211
+  Longitude:        -90.080563
+  Full address:     1500 Sugar Bowl Dr, New Orleans, LA 70112, USA
+  City:             New Orleans
+  State/province:   Louisiana
+  Postal code:      70112
+  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 <tt>geocode -h</tt> for details.
+
+
 == Notes on Mongoid
 
 === The Near Method
@@ -346,7 +418,7 @@ Mongoid document classes have a built-in +near+ scope, but since it only works t
 
 === Latitude/Longitude Order
 
-Coordinates are generally printed and spoken as latitude, then logitude ([lat,lon]). Geocoder respects this convention and always expects method arguments to be given in [lat,lon] order. However, MongoDB requires that coordinates be stored in [lon,lat] order as per the GeoJSON spec (http://geojson.org/geojson-spec.html#positions), so internally they are stored "backwards." However, this does not affect order of arguments to methods when using Mongoid. I mention this only in case you notice it and freak out. Don't worry. Everything is going to be OK.
+Coordinates are generally printed and spoken as latitude, then logitude ([lat,lon]). Geocoder respects this convention and always expects method arguments to be given in [lat,lon] order. However, MongoDB requires that coordinates be stored in [lon,lat] order as per the GeoJSON spec (http://geojson.org/geojson-spec.html#positions), so internally they are stored "backwards." However, this does not affect order of arguments to methods when using Mongoid.
 
 
 == Distance Queries in SQLite
@@ -376,19 +448,12 @@ http://github.com/alexreisner/geocoder_test
 
 == 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 <tt>:select</tt> option to the +near+ scope to get the columns you want. For example, in Rails 2 syntax:
+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 <tt>:select</tt> option to the +near+ scope to get the columns you want. For example:
 
-  # instead of :includes => :venues:
-  City.near("Omaha, NE", 20, :select => "venues.*").all(:joins => :venues)
+  # instead of City.near(...).includes(:venues)
+  City.near("Omaha, NE", 20, :select => "cities.*, venues.*").joins(:venues)
 
 If anyone has a more elegant solution to this problem I am very interested in seeing it.
 
 
-== Roadmap
-
-* add support for more ORMs (Mongoid, DataMapper)
-* add support for more geocoding services
-* maintain the same simple interface
-
-
 Copyright (c) 2009-11 Alex Reisner, released under the MIT license

data/bin/geocode

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'geocoder/cli'
+
+Geocoder::Cli.run ARGV

data/lib/geocoder.rb

@@ -11,32 +11,8 @@ module Geocoder
   ##
   # Search for information about an address or a set of coordinates.
   #
-  def search(query, *args)
-    # convert coordinates as separate arguments to an array
-    if query.is_a?(Numeric) and args.first.is_a?(Numeric)
-      warn "DEPRECATION WARNING: Instead of passing latitude/longitude as separate arguments to the search method, please pass an array: [#{query},#{args.first}]. The old argument format will not be supported in Geocoder v.1.0."
-      query = [query, args.first]
-    end
-    if blank_query?(query)
-      results = []
-    else
-      results = lookup(ip_address?(query)).search(query)
-    end
-    results.instance_eval do
-      def warn_search_deprecation(attr)
-        warn "DEPRECATION WARNING: Geocoder.search now returns an array of Geocoder::Result objects. " +
-          "Calling '%s' directly on the returned array will cause an exception in Geocoder v1.0." % attr
-      end
-
-      def coordinates; warn_search_deprecation('coordinates'); first.coordinates if first; end
-      def latitude; warn_search_deprecation('latitude'); first.latitude if first; end
-      def longitude; warn_search_deprecation('longitude'); first.longitude if first; end
-      def address; warn_search_deprecation('address'); first.address if first; end
-      def city; warn_search_deprecation('city'); first.city if first; end
-      def country; warn_search_deprecation('country'); first.country if first; end
-      def country_code; warn_search_deprecation('country_code'); first.country_code if first; end
-    end
-    return results
+  def search(query)
+    blank_query?(query) ? [] : lookup(query).search(query)
   end
 
   ##
@@ -52,11 +28,7 @@ module Geocoder
   # Look up the address of the given coordinates ([lat,lon])
   # or IP address (string).
   #
-  def address(query, *args)
-    if lon = args.first
-      warn "DEPRECATION WARNING: Instead of passing latitude/longitude as separate arguments to the address method, please pass an array: [#{query},#{args.first}]. The old argument format will not be supported in Geocoder v.1.0."
-      query = [query, lon]
-    end
+  def address(query)
     if (results = search(query)).size > 0
       results.first.address
     end
@@ -72,6 +44,27 @@ module Geocoder
     @cache
   end
 
+  ##
+  # Array of valid Lookup names.
+  #
+  def valid_lookups
+    street_lookups + ip_lookups
+  end
+
+  ##
+  # All street address lookups, default first.
+  #
+  def street_lookups
+    [:google, :yahoo, :bing, :geocoder_ca, :yandex]
+  end
+
+  ##
+  # All IP address lookups, default first.
+  #
+  def ip_lookups
+    [:freegeoip]
+  end
+
 
   # exception classes
   class Error < StandardError; end
@@ -82,13 +75,14 @@ module Geocoder
 
   ##
   # Get a Lookup object (which communicates with the remote geocoding API).
-  # Returns an IP address lookup if +ip+ parameter true.
+  # Takes a search query and returns an IP or street address Lookup
+  # depending on the query contents.
   #
-  def lookup(ip = false)
-    if ip
-      get_lookup :freegeoip
+  def lookup(query)
+    if ip_address?(query)
+      get_lookup(ip_lookups.first)
     else
-      get_lookup Configuration.lookup || :google
+      get_lookup(Configuration.lookup || street_lookups.first)
     end
   end
 
@@ -121,13 +115,6 @@ module Geocoder
     end
   end
 
-  ##
-  # Array of valid Lookup names.
-  #
-  def valid_lookups
-    [:google, :yahoo, :geocoder_ca, :freegeoip]
-  end
-
   ##
   # Does the given value look like an IP address?
   #

data/lib/geocoder/calculations.rb

@@ -51,13 +51,7 @@ module Geocoder
     #
     # * <tt>:units</tt> - <tt>:mi</tt> (default) or <tt>:km</tt>
     #
-    def distance_between(point1, point2, options = {}, *args)
-      if args.size > 0
-        warn "DEPRECATION WARNING: Instead of passing lat1/lon1/lat2/lon2 as separate arguments to the distance_between method, please pass two two-element arrays: [#{point1},#{point2}], [#{options}, #{args.first}]. The old argument format will not be supported in Geocoder v.1.0."
-        point1 = [point1, point2]
-        point2 = [options, args.shift]
-        options = args.shift || {}
-      end
+    def distance_between(point1, point2, options = {})
 
       # set default options
       options[:units] ||= :mi
@@ -95,14 +89,9 @@ module Geocoder
     #
     # Based on: http://www.movable-type.co.uk/scripts/latlong.html
     #
-    def bearing_between(point1, point2, options = {}, *args)
-      if args.size > 0
-        warn "DEPRECATION WARNING: Instead of passing lat1/lon1/lat2/lon2 as separate arguments to the bearing_between method, please pass two two-element arrays: [#{point1},#{point2}], [#{options}, #{args.first}]. The old argument format will not be supported in Geocoder v.1.0."
-        point1 = [point1, point2]
-        point2 = [options, args.shift]
-        options = args.shift || {}
-      end
+    def bearing_between(point1, point2, options = {})
 
+      # set default options
       options[:method] = :linear unless options[:method] == :spherical
 
       # convert to coordinate arrays
@@ -190,13 +179,7 @@ module Geocoder
     #
     # * <tt>:units</tt> - <tt>:mi</tt> (default) or <tt>:km</tt>
     #
-    def bounding_box(point, radius, options = {}, *args)
-      if point.is_a?(Numeric)
-        warn "DEPRECATION WARNING: Instead of passing latitude/longitude as separate arguments to the bounding_box method, please pass an array [#{point},#{radius}], a geocoded object, or a geocodable address (string). The old argument format will not be supported in Geocoder v.1.0."
-        point   = [point, radius]
-        radius  = options
-        options = args.first || {}
-      end
+    def bounding_box(point, radius, options = {})
       lat,lon = extract_coordinates(point)
       radius  = radius.to_f
       units   = options[:units] || :mi

data/lib/geocoder/cli.rb

@@ -0,0 +1,111 @@
+require 'geocoder'
+require 'optparse'
+
+module Geocoder
+  class Cli
+
+    def self.run(args, out = STDOUT)
+      show_url  = false
+      show_json = false
+
+      OptionParser.new{ |opts|
+        opts.banner = "Usage:\n    geocode [options] <location>"
+        opts.separator "\nOptions: "
+
+        opts.on("-k <key>", "--key <key>",
+          "Key for geocoding API (optional for most)") do |key|
+          Geocoder::Configuration.api_key = key
+        end
+
+        opts.on("-l <language>", "--language <language>",
+          "Language of output (see API docs for valid choices)") do |language|
+          Geocoder::Configuration.language = language
+        end
+
+        opts.on("-p <proxy>", "--proxy <proxy>",
+          "HTTP proxy server to use (user:pass@host:port)") do |proxy|
+          Geocoder::Configuration.http_proxy = proxy
+        end
+
+        opts.on("-s <service>", Geocoder.street_lookups, "--service <service>",
+          "Geocoding service: #{Geocoder.street_lookups * ', '}") do |service|
+          Geocoder::Configuration.lookup = service.to_sym
+        end
+
+        opts.on("-t <seconds>", "--timeout <seconds>",
+          "Maximum number of seconds to wait for API response") do |timeout|
+          Geocoder::Configuration.timeout = timeout.to_i
+        end
+
+        opts.on("-j", "--json", "Print API's raw JSON response") do
+          show_json = true
+        end
+
+        opts.on("-u", "--url", "Print URL for API query instead of result") do
+          show_url = true
+        end
+
+        opts.on_tail("-v", "--version", "Print version number") do
+          require "geocoder/version"
+          out << "Geocoder #{Geocoder::VERSION}\n"
+          exit
+        end
+
+        opts.on_tail("-h", "--help", "Print this help") do
+          out << "Look up geographic information about a location.\n\n"
+          out << opts
+          out << "\nCreated and maintained by Alex Reisner, available under the MIT License.\n"
+          out << "Report bugs and contribute at http://github.com/alexreisner/geocoder\n"
+          exit
+        end
+      }.parse!(args)
+
+      query = args.join(" ")
+
+      if query == ""
+        out << "Please specify a location (run `geocode -h` for more info).\n"
+        exit 1
+      end
+
+      if show_url and show_json
+        out << "You can only specify one of -j and -u.\n"
+        exit 2
+      end
+
+      if show_url
+        lookup = Geocoder.send(:lookup, query)
+        reverse = lookup.send(:coordinates?, query)
+        out << lookup.send(:query_url, query, reverse) + "\n"
+        exit 0
+      end
+
+      if show_json
+        lookup = Geocoder.send(:lookup, query)
+        reverse = lookup.send(:coordinates?, query)
+        out << lookup.send(:fetch_raw_data, query, reverse) + "\n"
+        exit 0
+      end
+
+      if (result = Geocoder.search(query).first)
+        lookup = Geocoder.send(:get_lookup, :google)
+        lines = [
+          ["Latitude",       result.latitude],
+          ["Longitude",      result.longitude],
+          ["Full address",   result.address],
+          ["City",           result.city],
+          ["State/province", result.state],
+          ["Postal code",    result.postal_code],
+          ["Country",        result.country],
+          ["Google map",     lookup.map_link_url(result.coordinates)],
+        ]
+        lines.each do |line|
+          out << (line[0] + ": ").ljust(18) + line[1].to_s + "\n"
+        end
+        exit 0
+      else
+        out << "Location '#{query}' not found.\n"
+        exit 1
+      end
+    end
+  end
+end