gcoder 0.8.0

data/.gitignore

@@ -0,0 +1,3 @@
+coverage
+rdoc
+pkg

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gem 'hashie'

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2010 Carsten Nielsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,144 @@
+# GCoder
+
+GCoder geocodes stuff using the Google Geocoding API (V3) and caches the
+results somewhere, if you want. _(Need something more bulldozer-like? Check out
+[Geokit](http://github.com/andre/geokit-gem).)_
+
+    # Bon Usage
+
+    require 'gcoder'
+
+    G = GCoder.connect(:storage => :heap)
+
+    G['dundas and sorauren', :region => :ca] # ... it geocodes!
+    G[[41.87, -74.16]]                       # ... and reverse-geocodes!
+
+The returned value is the 'results' portion of the Google Geocoding API
+[response](http://code.google.com/apis/maps/documentation/geocoding/#JSON).
+
+## Configuration Options
+
+These can be applied globally by setting `GCoder.config` or on a per-connection
+basis by passing them to `GCoder.connect`.
+
+### `:append`
+
+Specifies a string to append to the end of all queries.
+
+### `:region`
+
+Tells the Geocoder to favour results in a specific region. More info
+[here](http://code.google.com/apis/maps/documentation/geocoding/#RegionCodes).
+
+### `:language`
+
+By default this is whatever Google thinks it is, you can set it to something
+if you'd like. More info
+[here](http://code.google.com/apis/maps/documentation/geocoding/#GeocodingRequests).
+
+### `:bounds`
+
+Specifies a bounding box in which to favour results from. Described as an array
+of two latitude / longitude pairs. The first describes the Northeast corner of
+the box and the second describes the Southwest corner of the box. Here is an
+example input:
+
+    [[50.09, -94.88], [41.87, -74.16]]
+
+More info [here](http://code.google.com/apis/maps/documentation/geocoding/#Viewports).
+
+### `:storage`
+
+Defines the storage adapter to use for caching results from the geocoder to
+limit unnecessary throughput. See "Storage Adapters" below for more information.
+
+### `:storage_config`
+
+Passed on to the selected adapter as configuration options. See
+"Storage Adapters" below for more information.
+
+## Storage Adapters
+
+GCoder comes with two adapters: `:heap`, and `:redis`. You can check out
+`lib/gcoder/storage.rb` for examples of how these are implemented. You can
+select either of these, or pass `nil` (or `false`) as the `:storage` option to
+disable caching of results.
+
+ * `:storage => nil` - Disable caching (default.)
+ * `:storage => :heap` - Saves cached values in an in-memory Hash.
+ * `:storage => :redis` - Saves cached values within Redis.
+
+### Adapter Configuration
+
+Some adapters have configuration settings that can be passed. The contents of
+`:storage_config` are passed to the adapter when it is instantiated.
+
+**HeapAdapter (:heap)**
+
+The Heap adapter has no options.
+
+**RedisAdapter (:redis)**
+
+The Redis adapter has the following options, none are required.
+
+ * `:connection` - Passed to `Redis.connect`.
+ * `:keyspace` - Prefixed to all keys generated by GCoder.
+ * `:key_ttl` - A time-to-live in seconds before cached results expire.
+
+### Roll Your Own Adapter
+
+Making your own adapter is pretty easy. Your adapter needs to respond to four
+instance methods: `connect`, `set`, `get`, and `clear`. Let's make an adapter
+for Sequel.
+
+    class SequelAdapter < GCoder::Storage::Adapter
+      def connect
+        @db = Sequel.connect(config[:connection])
+        @table_name = (config[:table_name] || :gcoder_results)
+      end
+
+      # The methods `nkey` and `nval` are used to "normalize" keys and values,
+      # respectively. You are encouraged to use them.
+      def set(key, value)
+        if get(key)
+          table.filter(:id => nkey(key)).update(:value => nval(value))
+        else
+          table.insert(:id => nkey(key), :value => nval(value))
+        end
+      end
+
+      def get(key)
+        if (row = table.filter(:id => nkey(key)).first)
+          row[:value]
+        else
+          nil
+        end
+      end
+
+      def clear
+        table.delete_all
+      end
+
+      private
+
+      def table
+        @db[@table_name]
+      end
+    end
+
+    GCoder::Storage.register(:sequel, SequelAdapter)
+
+Now we can use our adapter as a caching layer by specifying it like this:
+
+    G = GCoder.connect \
+      :storage => :sequel,
+      :storage_config => {
+        :connection => 'sqlite://geo.db',
+        :table_name => :locations
+      }
+
+## Notes
+
+Tested with Ruby 1.9.2 (MRI) and nothing else, fork it. See
+[LICENSE](http://github.com/heycarsten/gcoder/blob/master/LICENSE) for details
+about that jazz.

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems/specification' unless defined?(Gem::Specification)
+require 'rake/gempackagetask'
+require 'rake/testtask'
+
+def gemspec
+  @gemspec ||= begin
+    Gem::Specification.load(File.expand_path('gcoder.gemspec'))
+  end
+end
+
+task :default => :spec
+
+desc 'Start an irb console'
+task :console do
+  system 'irb -I lib -r gcoder'
+end
+
+desc 'Validates the gemspec'
+task :gemspec do
+  gemspec.validate
+end
+
+desc 'Displays the current version'
+task :version do
+  puts "Current version: #{gemspec.version}"
+end
+
+desc 'Installs the gem locally'
+task :install => :package do
+  sh "gem install pkg/#{gemspec.name}-#{gemspec.version}"
+end
+
+desc 'Release the gem'
+task :release => :package do
+  sh "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+Rake::GemPackageTask.new(gemspec) do |pkg|
+  pkg.gem_spec = gemspec
+end
+task :gem => :gemspec
+task :package => :gemspec
+
+Rake::TestTask.new(:spec) do |t|
+  t.libs += %w[gcoder spec]
+  t.test_files = FileList['spec/**/*.rb']
+  t.verbose = true
+end

data/gcoder.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+require File.expand_path("../lib/gcoder/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'gcoder'
+  s.version     = GCoder::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Carsten Nielsen']
+  s.email       = ['heycarsten@gmail.com']
+  s.homepage    = 'http://github.com/heycarsten/gcoder'
+  s.summary     = %q{A nice library for geocoding stuff with Google Geocoder API}
+  s.description = %q{Uses Google Geocoder API to geocode stuff and optionally caches the results somewhere}
+
+  s.required_rubygems_version = '>= 1.3.6'
+  s.rubyforge_project = 'gcoder'
+
+  s.add_dependency 'hashie'
+
+  s.files         = `git ls-files`.split(?\n)
+  s.test_files    = `git ls-files -- {test,spec}/*`.split(?\n)
+  s.require_paths = ['lib']
+end

data/lib/gcoder/geocoder.rb

@@ -0,0 +1,135 @@
+module GCoder
+  module Geocoder
+
+    HOST = 'maps.googleapis.com'
+    PATH = '/maps/api/geocode/json'
+
+    class Request
+      def self.u(string)
+        string.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
+          '%' + $1.unpack('H2' * $1.size).join('%').upcase
+        }.tr(' ', '+')
+      end
+
+      def self.to_query(params)
+        params.map { |key, val| "#{u key}=#{u val}" }.join('&')
+      end
+
+      def self.stubs
+        @stubs ||= {}
+      end
+
+      def self.stub(uri, body)
+        stubs[uri] = body
+      end
+
+      def initialize(query, opts = {})
+        @config = GCoder.config.merge(opts)
+        detect_and_set_query(query)
+      end
+
+      def params
+        p = { :sensor => 'false' }
+        p[:address]  = address            if @address
+        p[:latlng]   = latlng             if @latlng
+        p[:language] = @config[:language] if @config[:language]
+        p[:region]   = @config[:region]   if @config[:region]
+        p[:bounds]   = bounds             if @config[:bounds]
+        p
+      end
+
+      def path
+        "#{PATH}?#{self.class.to_query(params)}"
+      end
+
+      def uri
+        "http://#{HOST}#{path}"
+      end
+
+      def get
+        Timeout.timeout(@config[:timeout]) do
+          Response.new(uri, http_get)
+        end
+      rescue Timeout::Error
+        raise TimeoutError, "Query timeout after #{@config[:timeout]} second(s)"
+      end
+
+      private
+
+      def detect_and_set_query(query)
+        if query.is_a?(Array)
+          case
+          when query.size != 2
+            raise BadQueryError, "Unable to geocode lat/lng pair that is not " \
+            "two elements long: #{query.inspect}"
+          when query.any? { |q| '' == q.to_s.strip }
+            raise BadQueryError, "Unable to geocode lat/lng pair with blank " \
+            "elements: #{query.inspect}"
+          else
+            @latlng = query
+          end
+        else
+          if '' == query.to_s.strip
+            raise BadQueryError, "Unable to geocode a blank query: " \
+            "#{query.inspect}"
+          else
+            @address = query
+          end
+        end
+      end
+
+      def http_get
+        self.class.stubs[uri] || Net::HTTP.get(HOST, path)
+      end
+
+      def latlng
+        @latlng.join(',')
+      end
+
+      def bounds
+        @config[:bounds].map { |point| point.join(',') }.join('|')
+      end
+
+      def address
+        @config[:append] ? "#{@address} #{@config[:append]}" : @address
+      end
+    end
+
+
+    class Response
+      attr_reader :body, :uri
+
+      def initialize(uri, body)
+        @uri      = uri
+        @body     = body
+        @response = Hashie::Mash.new(JSON.parse(@body))
+        validate_status!
+      end
+
+      def as_mash
+        @response
+      end
+
+      private
+
+      def validate_status!
+        case @response.status
+        when 'OK'
+          # All is well!
+        when 'ZERO_RESULTS'
+          raise NoResultsError, "Geocoding API returned no results: (#{@uri})"
+        when 'OVER_QUERY_LIMIT'
+          raise OverLimitError, 'Rate limit for Geocoding API exceeded!'
+        when 'REQUEST_DENIED'
+          raise GeocoderError, "Request denied by the Geocoding API: (#{@uri})"
+        when 'INVALID_REQUEST'
+          raise GeocoderError, "An invalid request was made: (#{@uri})"
+        else
+          raise GeocoderError, 'No status in Geocoding API response: ' \
+          "(#{@uri})\n\n#{@body}"
+        end
+      end
+    end
+
+  end
+end

data/lib/gcoder/resolver.rb

@@ -0,0 +1,42 @@
+module GCoder
+  class Resolver
+
+    def initialize(opts = {})
+      @config = GCoder.config.merge(opts)
+      if (adapter_name = @config[:storage])
+        @conn = Storage[adapter_name].new(@config[:storage_config])
+      else
+        @conn = nil
+      end
+    end
+
+    def [](*args)
+      geocode *args
+    end
+
+    def geocode(query, opts = {})
+      fetch([query, opts].join) do
+        Geocoder::Request.new(query, opts).get.as_mash
+      end.results
+    end
+
+    def fetch(key)
+      raise ArgumentError, 'block required' unless block_given?
+      Hashie::Mash.new((val = get(key)) ? JSON.parse(val) : set(key, yield))
+    end
+
+    private
+
+    def get(query)
+      return nil unless @conn
+      @conn.get(query)
+    end
+
+    def set(key, value)
+      return value unless @conn
+      @conn.set(key, value.to_json)
+      value
+    end
+
+  end
+end

data/lib/gcoder/storage.rb

@@ -0,0 +1,107 @@
+module GCoder
+  module Storage
+
+    def self.adapters
+      @adapters ||= {}
+    end
+
+    def self.[](name)
+      adapters[name.to_sym]
+    end
+
+    def self.register(name, mod)
+      adapters[name.to_sym] = mod
+    end
+
+    class Adapter
+      def initialize(opts = {})
+        @config = (opts || {})
+        connect
+      end
+
+      def config
+        @config
+      end
+
+      def connect
+        raise NotImplementedError, 'This adapter needs to implement #connect'
+      end
+
+      def clear
+        raise NotImplementedError, 'This adapter needs to implement #clear'
+      end
+
+      def get(key)
+        raise NotImplementedError, 'This adapter needs to implement #get'
+      end
+
+      def set(key, val)
+        raise NotImplementedError, 'This adapter needs to implement #set'
+      end
+
+      protected
+
+      def nval(value)
+        value.to_s
+      end
+
+      def nkey(key)
+        Digest::SHA1.hexdigest(key.to_s.downcase)
+      end
+    end
+
+
+    class HeapAdapter < Adapter
+      def connect
+        @heap = {}
+      end
+
+      def clear
+        @heap = {}
+      end
+
+      def get(key)
+        @heap[nkey(key)]
+      end
+
+      def set(key, value)
+        @heap[nkey(key)] = nval(value)
+      end
+    end
+
+
+    class RedisAdapter < Adapter
+      def connect
+        require 'redis'
+        @rdb = Redis.connect(*[config[:connection]].compact)
+        @keyspace = "#{config[:keyspace] || 'gcoder'}:"
+      end
+
+      def clear
+        @rdb.keys(@keyspace + '*').each { |key| @rdb.del(key) }
+      end
+
+      def get(key)
+        @rdb.get(keyns(key))
+      end
+
+      def set(key, value)
+        if (ttl = config[:key_ttl])
+          @rdb.setex(keyns(key), ttl, nval(value))
+        else
+          @rdb.set(keyns(key), nval(value))
+        end
+      end
+
+      private
+
+      def keyns(key)
+        "#{@keyspace}#{nkey(key)}"
+      end
+    end
+
+    register :heap,  HeapAdapter
+    register :redis, RedisAdapter
+
+  end
+end

data/lib/gcoder/version.rb

@@ -0,0 +1,3 @@
+module GCoder
+  VERSION = '0.8.0'
+end

data/lib/gcoder.rb

@@ -0,0 +1,38 @@
+require 'json'
+require 'hashie'
+require 'net/http'
+require 'timeout'
+require 'digest/sha1'
+
+$:.unshift(File.dirname(__FILE__))
+
+require 'gcoder/version'
+require 'gcoder/geocoder'
+require 'gcoder/storage'
+require 'gcoder/resolver'
+
+module GCoder
+  class NoResultsError < StandardError; end
+  class OverLimitError < StandardError; end
+  class GeocoderError < StandardError; end
+  class BadQueryError < StandardError; end
+  class NotImplementedError < StandardError; end
+  class TimeoutError < StandardError; end
+
+  DEFAULT_CONFIG = {
+    :timeout        => 5,
+    :append         => nil,
+    :region         => nil,
+    :bounds         => nil,
+    :storage        => nil,
+    :storage_config => nil
+  }.freeze
+
+  def self.config
+    @config ||= DEFAULT_CONFIG.dup
+  end
+
+  def self.connect(options = {})
+    Resolver.new(options)
+  end
+end

data/spec/gcoder/geocoder_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe GCoder::Geocoder::Request do
+  it 'should raise an error when passed nil' do
+    -> {
+      GCoder::Geocoder::Request.new(nil)
+    }.must_raise GCoder::BadQueryError
+  end
+
+  it 'should raise an error when passed a blank string' do
+    -> {
+      GCoder::Geocoder::Request.new(' ')
+    }.must_raise GCoder::BadQueryError
+  end
+
+  it 'should raise an error when passed incorrect lat/lng pair' do
+    GCoder::Geocoder::Request.tap do |req|
+      -> { req.new([])           }.must_raise GCoder::BadQueryError
+      -> { req.new([43.64])      }.must_raise GCoder::BadQueryError
+      -> { req.new([43.64, nil]) }.must_raise GCoder::BadQueryError
+      -> { req.new(['', 43.64])  }.must_raise GCoder::BadQueryError
+    end
+  end
+
+  it 'should URI encode a string' do
+    GCoder::Geocoder::Request.u('hello world').must_equal 'hello+world'
+  end
+
+  it 'should create a query string' do
+    q = GCoder::Geocoder::Request.to_query(:q => 'hello world', :a => 'test')
+    q.must_equal 'q=hello+world&a=test'
+  end
+
+  it '(when passed a bounds option) should generate correct query params' do
+    GCoder::Geocoder::Request.new('q', :bounds => [[1,2], [3,4]]).tap do |req|
+      req.params[:bounds].must_equal '1,2|3,4'
+    end
+  end
+
+  it '(when passed a lat/lng pair) should generate correct query params' do
+    GCoder::Geocoder::Request.new([43.64, -79.39]).tap do |req|
+      req.params[:latlng].must_equal '43.64,-79.39'
+      req.params[:address].must_be_nil
+    end
+  end
+
+  it '(when passed a geocodable string) should generate correct query params' do
+    GCoder::Geocoder::Request.new('queen and spadina').tap do |req|
+      req.params[:latlng].must_be_nil
+      req.params[:address].must_equal 'queen and spadina'
+    end
+  end
+end

data/spec/gcoder/resolver_spec.rb

@@ -0,0 +1,47 @@
+require 'spec_helper'
+
+describe 'GCoder::Resolver (with caching)' do
+  before do
+    @g = GCoder.connect(:storage => :heap, :region => :us)
+  end
+
+  it 'should resolve geocodable queries' do
+    r = @g.geocode('queen and spadina', :region => :ca)
+    r.must_be_instance_of Array
+  end
+
+  it 'should resolve cached queries' do
+    r1 = @g.geocode('queen and spadina', :region => :ca)
+    r2 = @g.geocode('queen and spadina', :region => :ca)
+    [r1, r2].each { |r| r.must_be_instance_of Array }
+  end
+
+  it 'should resolve reverse-geocodeable queries' do
+    r = @g.geocode([43.6487606, -79.3962415], :region => nil)
+    r.must_be_instance_of Array
+  end
+
+  it 'should raise an error for queries with no results' do
+    -> { @g['noresults', :region => nil] }.must_raise GCoder::NoResultsError
+  end
+
+  it 'should raise an error for denied queries' do
+    -> { @g['denied', :region => nil] }.must_raise GCoder::GeocoderError
+  end
+
+  it 'should raise an error when the query limit is exceeded' do
+    -> { @g['overlimit', :region => nil] }.must_raise GCoder::OverLimitError
+  end
+
+  it 'should raise an error when the request is invalid' do
+    -> { @g['denied', :region => nil] }.must_raise GCoder::GeocoderError
+  end
+end
+
+describe 'GCoder::Resolver (without caching)' do
+  it 'should resolve queries' do
+    g = GCoder.connect(:storage => nil)
+    r = g['queen and spadina', :region => :ca]
+    r.must_be_instance_of Array
+  end
+end