geocoda 0.0.1

data/README.txt

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

data/lib/geocoda/client.rb

@@ -0,0 +1,81 @@
+module Geocoda
+
+  class Client
+
+    ##
+    # Returns the default key
+    def self.key
+      @key ||= raise(MapKeyError, 'Missing Key: Geocoda::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 Geocoda::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/geocoda/response.rb

@@ -0,0 +1,173 @@
+module Geocoda
+  
+  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"] rescue nil
+    end
+    
+    ##
+    # City
+    #
+    # @return [String] city
+    def city
+     @city ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+               ["Locality"]["LocalityName"] rescue nil
+    end
+    
+    ##
+    # State
+    #
+    # @return [String] state
+    def state
+      @state ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+                 ["AdministrativeAreaName"] rescue nil
+    end
+    
+    ##
+    # Zipcode
+    #
+    # @return [String] zipcode
+    def zipcode
+      @zipcode ||= @hash["AddressDetails"]["Country"]["AdministrativeArea"]\
+                   ["Locality"]["PostalCode"]["PostalCodeNumber"] rescue nil
+    end
+    
+    ##
+    # Country
+    #
+    # @return [String] country
+    def country
+      @country ||= @hash["AddressDetails"]["Country"]["CountryNameCode"]\
+                   rescue nil
+    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]\
+                    rescue nil
+    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 rescue nil
+    end
+    
+    ##
+    # Lng
+    #
+    # @return [Float] longitude
+    def lng
+      @lng ||= @hash["Point"]["coordinates"][1].to_f rescue nil
+    end
+    
+    ##
+    # Elevation
+    #
+    # @return [Float] elevation
+    def elevation
+      @elevation ||= @hash["Point"]["coordinates"][2].to_f rescue nil
+    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/geocoda.rb

@@ -0,0 +1,46 @@
+require 'patron'
+require 'json'
+module Geocoda
+
+  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.3"
+  end
+
+  ##
+  # Search for addresses that match a string
+  #
+  # @see Geocoda::Client#search
+  def self.search(address,key=nil)
+    Client.new(key).search(address)
+  end
+
+  ##
+  # Search for the first address that matches a string
+  #
+  # @see Geocoda::Client#first
+  def self.first(address,key=nil)
+    search(address,key).first
+  end
+
+end
+
+require File.join(
+  File.expand_path(File.dirname(__FILE__)), 'geocoda', 'client'
+)
+require File.join(
+  File.expand_path(File.dirname(__FILE__)), 'geocoda', 'response'
+)

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: geocoda
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Dusty Doris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-19 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &70110201151060 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70110201151060
+- !ruby/object:Gem::Dependency
+  name: patron
+  requirement: &70110201150500 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70110201150500
+description: 
+email: github@dusty.name
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.txt
+files:
+- README.txt
+- lib/geocoda.rb
+- lib/geocoda/client.rb
+- lib/geocoda/response.rb
+homepage: https://github.com/dusty/geocoda
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: none
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Interface to Google's Geocoder API
+test_files: []