dusty-geocoder 0.0.2

data/README.txt

@@ -0,0 +1,36 @@
+== DESCRIPTION:
+
+Used to interact with Googles Geocoding API
+
+
+== REQUIREMENTS:
+
+patron
+json
+
+
+== INSTALL:
+
+$ gem build geocoder.gemspec
+$ sudo gem install geocoder-x.x.x.gem
+
+
+== USAGE:
+
+Geocoder.search('123 My St, MyCity, NY')
+ # returns an array of addresses or throws an exception
+ 
+Geocoder.first('123 My St, MyCity, NY')
+ # returns a single address or throws an exception
+ 
+See Geocoder::Response.check_status for errors thrown depending on the results
+Errors in the HTTP call throw a Geocoder::ConnectionError
+
+Your google API key is required.  You may set this in one of two ways.
+
+1. Set the class variable with Geocoder::Client.key = 'xxxxxx'
+ $ Geocoder.search('My Address') # uses default key
+ 
+2. Send the key with your searches
+ $ Geocoder.search('My Address', key) # uses defined key
+ 

data/lib/geocoder/client.rb

@@ -0,0 +1,81 @@
+module Geocoder
+  
+  class Client
+    
+    ##
+    # Returns the default key
+    def self.key
+      @key ||= raise(MapKeyError, 'Missing Key: Geocoder::Client.key=(key)')
+    end
+  
+    ##
+    # Sets the default key
+    def self.key=(key)
+      @key = key
+    end
+  
+    ##
+    # Initialize the Client
+    # 
+    # If the key is passed it will be used in place of the default key
+    def initialize(key=nil)
+      @key ||= self.class.key
+      @http = Patron::Session.new
+      @http.base_url = 'http://maps.google.com/maps/geo'
+    end
+  
+    ##
+    # Search for addresses that match a string
+    #
+    # @param [String] Address required for search
+    # @return [Array<Address>] An array of addresses
+    # @raise [StandardError] on errors
+    def search(address)
+      begin
+        response = @http.get(hash_to_string(:q => address))
+      rescue StandardError => e
+        raise(ConnectionError, e.message)
+      end
+      unless response.status == 200
+        raise(ConnectionError, "Response Code: #{response.status}")
+      end
+      Response.new(response.body).addresses
+    end
+    
+    ##
+    # Search for the first address that matches a string
+    #
+    # @see Geocoder::Client#search
+    # @param [String] Address required for search
+    # @return [Address] An address object
+    # @raise [StandardError] on errors
+    def first(address)
+      search.first
+    end
+  
+    private
+  
+    ##
+    # Set the default parameters to use in searches
+    def default_params
+      {:key => @key, :gl => 'US', :output => 'json'}
+    end
+
+    ##
+    # Convert a hash into a query parameter
+    #
+    # Example:
+    # {:q => 'my address', :output => 'json'}
+    # ?q=my%20address&output=json
+    #
+    # @return [String]
+    def hash_to_string(hash)
+      output = default_params.update(hash).map do |key, value|
+        "#{key}=#{@http.escape(value.to_s)}"
+      end.join("&")
+      "?#{output}"
+    end
+  
+  end
+  
+end    

data/lib/geocoder/response.rb

@@ -0,0 +1,170 @@
+module Geocoder
+  
+  class Response
+    attr_reader :json
+    
+    ##
+    # Initialize the response and check for errors in the Status code
+    #
+    # @see check_status
+    # @raise [StandardError]
+    def initialize(json)
+      @json = json
+      @hash = JSON.parse(json)
+      check_status
+    end
+
+    ##
+    # Return an array of addresses that matched the search
+    #
+    # @return [Array<Address>]
+    def addresses
+      @addresses ||= @hash["Placemark"].map {|place| Address.new(place)}
+    end
+    
+    ##
+    # Check the status returned by Google and throw exception on
+    # results that are not 200
+    #
+    # @raise [StandardError]
+    def check_status
+      case @hash["Status"]["code"]
+      when 200 then
+        true
+      when 500
+        raise ServerError, "Unknown server error"
+      when 601
+        raise MissingAddressError, "Missing address"
+      when 602
+        raise UnknownAddressError, "Unknown address"
+      when 603
+        raise UnavailableAddressError, "Unavailable address"
+      when 610
+        raise InvalidMapKeyError, "Invalid map key"
+      when 620
+        raise TooManyQueriesError, "Too many queries for map key"
+      else
+        raise UnknownError, "Unknown error: #{@hash['code']}"
+      end
+    end
+
+  end
+  
+  class Address
+    ##
+    # Initialize class
+    #
+    # set @hash to the json parsed hash
+    def initialize(hash)
+      @hash = hash
+    end
+    
+    ##
+    # Address
+    #
+    # @return [String] address
+    def address
+      @address ||= @hash["address"]
+    end
+    
+    ##
+    # Street
+    #
+    # @return [String] street
+    def street
+      @street ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+                       ["Locality"]["Thoroughfare"]["ThoroughfareName"]
+    end
+    
+    ##
+    # City
+    #
+    # @return [String] city
+    def city
+     @city ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+                    ["Locality"]["LocalityName"]
+    end
+    
+    ##
+    # State
+    #
+    # @return [String] state
+    def state
+      @state ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+                      ["AdministrativeAreaName"]
+    end
+    
+    ##
+    # Zipcode
+    #
+    # @return [String] zipcode
+    def zipcode
+      @zipcode ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+                        ["Locality"]["PostalCode"]["PostalCodeNumber"]
+    end
+    
+    ##
+    # Country
+    #
+    # @return [String] country
+    def country
+      @country ||= @hash["AddressDetails"]["Country"]["CountryNameCode"]
+    end
+    
+    ##
+    # Accuracy
+    #
+    # Convert Googles Accuracy integer into a word describing how accurate
+    # the match is
+    #
+    # @see accuracy_map
+    # @return [String] accuracy
+    def accuracy
+      @accuracy ||= accuracy_map[@hash["AddressDetails"]["Accuracy"].to_i]
+    end
+    
+    ##
+    # Coordinates
+    #
+    # An array of coordinates in the form of [lat, lng, elevation]
+    #
+    # @return [<Array>] lat, lng, elevation
+    def coordinates
+      @coordinates ||= [lat, lng, elevation]
+    end
+    
+    ##
+    # Lat
+    #
+    # @return [Float] latitude
+    def lat
+      @lat ||= @hash["Point"]["coordinates"][0].to_f
+    end
+    
+    ##
+    # Lng
+    #
+    # @return [Float] longitude
+    def lng
+      @lng ||= @hash["Point"]["coordinates"][1].to_f
+    end
+    
+    ##
+    # Elevation
+    #
+    # @return [Float] elevation
+    def elevation
+      @elevation ||= @hash["Point"]["coordinates"][2].to_f
+    end
+    
+    private
+    
+    ##
+    # Map Googles code to a user friendly word
+    #
+    # @return [String]
+    def accuracy_map
+      %w{ unknown country state county city zip zip+4 street address }
+    end
+  end
+end

data/lib/geocoder.rb

@@ -0,0 +1,46 @@
+require 'patron'
+require 'json'
+module Geocoder
+  
+  class Error < StandardError; end
+  class ServerError  < Error; end
+  class AddressError < Error; end
+  class MissingAddressError     < AddressError; end
+  class UnknownAddressError     < AddressError; end
+  class UnavailableAddressError < AddressError; end
+  class MapKeyError < Error; end
+  class InvalidMapKeyError  < MapKeyError; end
+  class TooManyQueriesError < MapKeyError; end
+  class UnknownError < Error; end
+  class ConnectionError < Error; end
+  
+  ##
+  # The current version of the application
+  def self.version
+    "0.0.2"
+  end
+  
+  ##
+  # Search for addresses that match a string
+  #
+  # @see Geocoder::Client#search
+  def self.search(address,key=nil)
+    Client.new(key).search(address)
+  end
+  
+  ##
+  # Search for the first address that matches a string
+  #
+  # @see Geocoder::Client#first
+  def self.first(address,key=nil)
+    search(address,key).first
+  end
+  
+end
+
+require File.join(
+  File.expand_path(File.dirname(__FILE__)), 'geocoder', 'client'
+)
+require File.join(
+  File.expand_path(File.dirname(__FILE__)), 'geocoder', 'response'
+)

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: dusty-geocoder
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Dusty Doris
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-16 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: patron
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: github@dusty.name
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.txt
+files: 
+- README.txt
+- lib/geocoder.rb
+- lib/geocoder/client.rb
+- lib/geocoder/response.rb
+has_rdoc: true
+homepage: http://code.dusty.name
+licenses: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: none
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Interface to Google's Geocoder API
+test_files: []
+