geocode 0.1.0 → 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,15 @@
+= Version 0.2.0 - 2009-11-25
+* Added --viewport (map extents)
+* Added --accuracy
+* Changed dump to YAML (MUCH more readable!)
+* Added field labels
+* Added --quiet to turn off said labels
+
+
+
+= Version 0.1.0 - 2009-11-17 
+* Initial release
+* geocode --latlng to get lat,lng
+* geocode --reverse to get address
+* google service only
+

data/README.rdoc

@@ -3,6 +3,7 @@
 Yet another geoding library. Initial version geocodes using Google
 only but I plan to extend it to use Yahoo and possibly Tiger/Line.
 
+
 = Examples
 
 == Command-Line
@@ -30,10 +31,67 @@ result1 and result2 are hashes with the following extension functions added in:
   result.latlng # array of 2 floats, [latitude, longitude], returned by geocode.
   result.address # string containing the address returned by reverse_geocode.
 
+
+= Options
+
+== --help, -h
+Get the most up to date help.
+
+== --service, -s
+Which service to use. Can be configured in geocode.yml. Currently only
+google is supported.
+
+== --google-api-key, -g
+Your google API key. Can be configured in geocode.yml.
+
+==  --latlng, -l
+Displays the lat/lng of the given address.
+
+Default information to display, on by default if no other display mode
+is selected.
+
+== --viewport, -v
+Displays the map viewport extends (bounding box) of the given address.
+
+== --accuracy, -a
+Displays the geocoding accuracy.
+
+== --reverse, -r
+Reverse geocodes a lat/lng to an address. Not compatible with
+--latlng, --viewport or --accuracy; if any of those options are also
+set they will be disabled.
+
+Note: If you input a negative latitude from the command line, Trollop
+tries to interpret this as an argument to the program. You should move
+to the Northern Hemisphere. As a temporary workaround, however, you
+can use '--' to tell Trollop to stop processing arguments, e.g.
+
+  $ geocode -r -- -23.548943,-46.638818
+  Address: Av. Vinte e Tr�s de Maio, 149-165 - Rep�blica, S�o Paulo - SP, 01316-060, Brazil
+
+== --dump, -d
+Geocodes (or reverse geocodes) the address and then dumps the returned
+object. Use this to noodle around in the geocode result object for
+other data.
+
+== --quiet, -q
+Turns off label printing. Useful when geocode is part of an external
+toolchain, e.g.
+
+  $ echo The President lives at $(geocode -q 1600 Pennsylvania Ave, Charleston, WV 25302)
+
+For example, I produced that full address with:
+
+  $ geocode -r $(geocode -q 1600 Pennsylvania Ave)
+
 = Installation
 
   gem install geocode
 
+Ideally, then create ~/.geocode and in it, write a geocode.yml file
+containing your google API key. See Configuration below for details.
+
+
 = Configuration (Command-Line)
 
 You can create a configuration file in ~/.geocode called geocode.yml.
@@ -53,10 +111,56 @@ bound by their Terms of Service. Most notably, this says that you MAY
 NOT "use or display the Content without a corresponding Google map".
 There are specific exceptions to this rule but be aware.
 
+
 = Authors
 
 * David Brady <github@shinybit.com>
 
+
 = License
 
-MIT.
+MIT. See MIT-LICENSE file for details.
+
+
+= TODO
+
+== Caching
+Google STRONGLY recommends caching geocoded data. For now, caching is
+the responsibility of the client using the geocode library. Eventually
+I'd like to just include a caching strategy and/or caching object to
+Geocode.new_geocoder(). This hides the caching strategy from the
+geocoding client.
+
+Possible implementations might include defining internal strategies
+(give me a sqlite3 file, or an ActiveRecord connection, or the address
+of a memcached server, etc) or creating a cache object API and passing
+that in.
+
+UPDATE: As a command-line introspection/visualizing tool, caching is
+pretty much useless. I'm burying this for now until and unless
+somebody decides they want to use this as part of a toolchain or as a
+library.
+
+== Helpful Creation of geocode.yml
+It is not unreasonable to expect a new geocode user to do this:
+
+  $ sudo gem install geocode
+  $ geocode 123 Some Address
+
+This will fail because there's no Google API configured. It would be
+nice to throw up an error message telling the user to create the
+geocode.yml file. Optionally it should even offer to create ~/.geocode
+and write the file there with a default API key.
+
+== Better error handling
+Remember the user from the step above? So he runs it and it creates
+the default settings file with a sample API key. So he runs it again
+without editing the file. The app should make it clear that the sample
+API key needs to be edited. Or at the very least it should report
+whatever error Google returns when an invalid API key is used.
+
+== Open A Map 
+As I use geocode as a debugging and introspection tool, I keep wanting
+to jump to a map to visualize the results. Consider emitting the uri
+to a map using the Google static map API.
+

data/bin/geocode

@@ -7,26 +7,68 @@ config_file = ["./geocode.yml", "~/.geocode/geocode.yml"].map {|p| File.expand_p
 config = config_file ? YAML::load_file(config_file) : {}
 config.each { |k,v| config[k.to_sym] = v}
 
+
+# Notes:
+# - If you specify --reverse, all of the following will be turned off: --latlng --viewport --accuracy
+# - If you specify none of --reverse, --latlng, --viewport, or --accuracy, --latlng will be assumed.
 opts = Trollop.options do
   opt :google_api_key, "API KEY to use", :default => nil
   opt :service, "Geocoding Service to use", :default => nil
   opt :reverse, "Reverse geocode", :type => :boolean, :default => false
-  opt :latlng, "Geocode to lat,lng (default)", :type => :boolean, :default => true
+  opt :latlng, "Geocode to lat,lng (default)", :type => :boolean, :default => false
+  opt :viewport, "Show viewport (map extents) of location", :type => :boolean, :default => false
+  opt :accuracy, "Show accuracy level of geocoded location", :type => :boolean, :default => false
+  opt :dump, "Dump the geocoded results", :type => :boolean, :default => false
+  opt :quiet, "Don't show labels", :type => :boolean, :default => false
 end
 
 opts[:google_api_key] ||= config[:google_api_key] || ""
 opts[:service] ||= config[:service] || "google"
 opts[:service] = opts[:service].to_sym
 
-# reverse geocoding is not compatible with latlng
+
+# reverse geocoding is not compatible with latlng / viewport / accuracy.
 if opts[:reverse] && opts[:latlng]
   opts[:latlng] = false
+  opts[:viewport] = false
+  opts[:accuracy] = false
 end
 
+# Default latlng to true if no other options have been given
+opts[:latlng] = true unless [:reverse, :viewport, :accuracy].any? { |option| opts[option] }
+
+
 # geocode the address or lat/lng given
 g = Geocode.new_geocoder(opts[:service], opts)
+
+geo = if opts[:reverse]
+        g.reverse_geocode(ARGV * ' ')
+      else
+        g.geocode(ARGV * ' ')
+      end
+
 if opts[:latlng]
-  puts g.geocode(ARGV * ' ').latlng * ','
-else opts[:reverse]
-  puts g.reverse_geocode(ARGV * ' ').address
+  print 'Location: ' unless opts[:quiet]
+  puts "%f,%f" % geo.latlng
+end
+
+if opts[:viewport]
+  print 'Viewport: ' unless opts[:quiet]
+  vp = geo.viewport
+  puts "%f,%f %f,%f" % vp
+end
+  
+if opts[:accuracy]
+  print 'Accuracy: ' unless opts[:quiet]
+  puts geo.accuracy
+end
+  
+if opts[:reverse]
+  print 'Address: ' unless opts[:quiet]
+  puts geo.address
+end
+
+if opts[:dump]
+  puts 'Dump: ' unless opts[:quiet]
+  puts geo.dump
 end

data/lib/google_geocode.rb

@@ -1,5 +1,6 @@
 require 'net/http'
 require 'json'
+require 'yaml'
 
 class GoogleGeocode
   attr_reader :api_key
@@ -23,7 +24,7 @@ class GoogleGeocode
       end
       
       def dump
-        inspect
+        self.to_yaml
       end
       
       def latlng
@@ -33,6 +34,15 @@ class GoogleGeocode
       def address
         self["Placemark"][0]["address"]
       end
+
+      def accuracy
+        self["Placemark"][0]["AddressDetails"]["Accuracy"]
+      end
+      
+      # returns viewport in tlbr format
+      def viewport
+        vp = [:north, :west, :south, :east].map {|dir| self["Placemark"][0]["ExtendedData"]["LatLonBox"][dir.to_s] }
+      end
     end
     result
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: geocode
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - David Brady
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-17 00:00:00 -07:00
+date: 2009-11-25 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,12 +41,14 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 - MIT-LICENSE
+- CHANGELOG.rdoc
 files: 
+- CHANGELOG.rdoc
+- MIT-LICENSE
+- README.rdoc
 - bin/geocode
 - lib/geocode.rb
 - lib/google_geocode.rb
-- README.rdoc
-- MIT-LICENSE
 has_rdoc: true
 homepage: http://github.com/dbrady/geocode/
 licenses: []