rubillow 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+pkg/*
+coverage
+doc
+.yardoc

data/.rspec

@@ -0,0 +1,2 @@
+--format progress
+--color

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+lib/**/*.rb
+-
+LICENSE

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    rubillow (0.0.1)
+      activesupport (~> 3.0.10)
+      i18n (~> 0.6.0)
+      nokogiri (~> 1.5.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.10)
+    bluecloth (2.1.0)
+    bourne (1.0)
+      mocha (= 0.9.8)
+    diff-lcs (1.1.2)
+    i18n (0.6.0)
+    mocha (0.9.8)
+      rake
+    nokogiri (1.5.0)
+    rake (0.9.2)
+    rcov (0.9.10)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    yard (0.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (>= 2.1.0)
+  bourne (~> 1.0)
+  mocha (~> 0.9.8)
+  rcov (~> 0.9.10)
+  rspec (~> 2.6)
+  rubillow!
+  yard (>= 0.6.8)

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Matthew Vince
+
+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,64 @@
+# Rubillow
+
+Rubillow is a ruby library to access the [Zillow API](http://www.zillow.com/howto/api/APIOverview.htm).
+
+Supports all of the API methods, with real ruby classes returned for each call.
+
+### [Home Valuation API](http://www.zillow.com/howto/api/HomeValuationAPIOverview.htm)
+* [GetSearchResults](http://www.zillow.com/howto/api/GetSearchResults.htm)
+* [GetZestimate](http://www.zillow.com/howto/api/GetZestimate.htm)
+* [GetChart](http://www.zillow.com/howto/api/GetChart.htm)
+* [GetComps](http://www.zillow.com/howto/api/GetComps.htm)
+
+### [Neighborhood Data](http://www.zillow.com/webtools/neighborhood-data/)
+* [GetDemographics](http://www.zillow.com/howto/api/GetDemographics.htm)
+* [GetRegionChildren](http://www.zillow.com/howto/api/GetRegionChildren.htm)
+* [GetRegionChart](http://www.zillow.com/howto/api/GetRegionChart.htm)
+
+### [Mortgage API](http://www.zillow.com/howto/api/MortgageAPIOverview.htm)
+* [GetRateSummary](http://www.zillow.com/howto/api/GetRateSummary.htm)
+* [GetMonthlyPayments](http://www.zillow.com/howto/api/GetMonthlyPayments.htm)
+
+### [Property Details API](http://www.zillow.com/howto/api/PropertyDetailsAPIOverview.htm)
+* [GetDeepSearchResults](http://www.zillow.com/howto/api/GetDeepSearchResults.htm)
+* [GetDeepComps](http://www.zillow.com/howto/api/GetDeepComps.htm)
+* [GetUpdatedPropertyDetails](http://www.zillow.com/howto/api/GetUpdatedPropertyDetails.htm)
+
+### [Postings API](http://www.zillow.com/howto/api/GetRegionPostings.htm)
+* [GetRegionPostings](http://www.zillow.com/howto/api/GetRegionPostings.htm)
+
+# Installing
+
+    gem install rubillow
+
+or add the following to your Gemfile:
+
+    gem "rubillow"
+
+# Examples
+
+Adding setup into an initializer:
+
+    Rubillow.configure do |configuration|
+      configuration.zwsid = "abcd1234"
+    end
+
+Getting property Zestimate:
+
+    property = Rubillow::HomeValuation.zestimate({ :zpid => '48749425' })
+    if property.success?
+      puts property.price
+    end
+
+# Documentation
+
+You should find the documentation for your version of Rubillow on [Rubygems](http://rubygems.org/gems/rubillow).
+
+# More Information
+
+* [Rubygems](http://rubygems.org/gems/rubillow)
+* [Issues](http://github.com/synewaves/rubillow/issues)
+
+# License
+
+Rubillow uses the MIT license. See LICENSE for more details.

data/Rakefile

@@ -0,0 +1,38 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+# require 'rcov/rcovtask'
+require "yard"
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end
+
+desc "Run specs with coverage"
+RSpec::Core::RakeTask.new("spec_rcov") do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.rcov = true
+  t.rcov_opts = %w{--exclude spec,gems}
+  t.rcov_opts << %[-o "coverage"]
+end
+
+# RSpec::Rake::SpecTask.new("rcov_spec") do |t|
+#   t.spec_files = FileList['spec/**/*_spec.rb']
+#   t.spec_opts = ['--color']
+#   t.rcov = true
+#   t.rcov_opts = ['--exclude', '^spec,/gems/']
+# end
+
+# desc 'Performs code coverage.'
+# Rcov::RcovTask.new do |t|
+#   t.test_files = FileList['spec/*_spec.rb']
+#   t.verbose = true
+# end
+
+# desc "Clean files generated by rake tasks"
+# task :clobber => [:clobber_rcov]
+
+YARD::Rake::YardocTask.new do |t|
+end
+
+task :default => :spec

data/lib/rubillow.rb

@@ -0,0 +1,29 @@
+require "rubillow/version"
+require "rubillow/configuration"
+require "rubillow/request"
+require "rubillow/home_valuation"
+require "rubillow/mortgage"
+require "rubillow/postings"
+require "rubillow/property_details"
+require "rubillow/neighborhood"
+require "rubillow/models"
+
+# Top-level interface to Rubillow
+module Rubillow
+  # Call this method to modify defaults in your initializers.
+  #
+  # @example
+  #   Rubillow.configure do |configuration|
+  #     configuration.zwsid = "abcd1234"
+  #   end
+  #
+  # @yield [Configuration] The current configuration.
+  def self.configure
+    yield(configuration)
+  end
+  
+  # @return [Configuration] Current configuration.
+  def self.configuration
+    @@configuration ||= Configuration.new
+  end
+end

data/lib/rubillow/configuration.rb

@@ -0,0 +1,31 @@
+module Rubillow
+  # Configuration options
+  class Configuration
+    # @return [String] HTTP host (defaults to +www.zillow.com+)
+    attr_accessor :host
+    
+    # @return [Integer] HTTP port (defaults to +80+)
+    attr_accessor :port
+    
+    # @return [String] relative service path (defaults to +webservice/+)
+    attr_accessor :path
+    
+    # @return [String] Zillow API key. See {http://www.zillow.com/howto/api/APIOverview.htm}.
+    attr_accessor :zwsid
+    
+    # @return [Integer] HTTP connection timeout seconds (defaults to +2+)
+    attr_accessor :http_open_timeout
+    
+    # @return [Integer] HTTP read timeout seconds (defaults to +2+)
+    attr_accessor :http_read_timeout
+    
+    # @private
+    def initialize
+      self.host              = "www.zillow.com"
+      self.port              = 80
+      self.path              = "webservice/"
+      self.http_open_timeout = 2
+      self.http_read_timeout = 2
+    end
+  end
+end

data/lib/rubillow/home_valuation.rb

@@ -0,0 +1,141 @@
+module Rubillow
+  # Interface for the Home Valuation API.
+  # 
+  # Read the more about this API at: {http://www.zillow.com/howto/api/HomeValuationAPIOverview.htm}
+  class HomeValuation
+    # Retrieve a property by the specified address.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetSearchResults.htm}.
+    # 
+    # @example
+    #   data = Rubillow::HomeValuation.search_results({ :address => '2114 Bigelow Ave', :citystatezip => 'Seattle, WA' })
+    #   
+    #   if data.success?
+    #     puts data.zpid    # "48749425" 
+    #     puts data.price   # "1032000"
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [String] :address       The address of the property to search. (required)
+    # @option options [String] :citystatezip  The city+state combination and/or ZIP code for which to search. Note that giving both city and state is required. Using just one will not work. (required)
+    # @return [Models::SearchResult] Property information.
+    def self.search_results(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :address => nil,
+        :citystatezip => nil,
+      }.merge!(options)
+    
+      if options[:address].nil?
+        raise ArgumentError, "The address option is required"
+      end
+      if options[:citystatezip].nil?
+        raise ArgumentError, "The citystatezip option is required"
+      end
+    
+      Models::SearchResult.new(Rubillow::Request.get("GetSearchResults", options))
+    end
+    
+    # Retrieve a zestimate for the specified property.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetZestimate.htm}.
+    # 
+    # @example
+    #   data = Rubillow::HomeValuation.zestimate({ :zpid => '48749425' })
+    #   
+    #   if data.success?
+    #     puts data.zpid          # "48749425" 
+    #     puts data.price         # "1032000"
+    #     puts data.value_change  # "5900"
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [Integer] :zpid   The Zillow Property ID of the property. (required)
+    # @return [Models::SearchResult] Property pricing information.
+    def self.zestimate(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :zpid => nil,
+      }.merge!(options)
+      
+      if options[:zpid].nil?
+        raise ArgumentError, "The zpid option is required"
+      end
+      
+      Models::SearchResult.new(Rubillow::Request.get("GetZestimate", options))
+    end
+
+    # Retrieve a chart for the specified property.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetChart.htm}.
+    # 
+    # @example
+    #   chart = Rubillow::HomeValuation.chart({ :zpid => '48749425', :height => '300', :width => '150' })
+    #   
+    #   if chart.success?
+    #     puts chart.to_html
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [Integer] :zpid           The Zillow Property ID of the property. (required)
+    # @option options [String]  :unit-type      Show the percent change ("percent"), or dollar change ("dollar"). (required)
+    # @option options [Integer] :width          The width of the image; between 200 and 600, inclusive.
+    # @option options [Integer] :height         The height of the image; between 100 and 300, inclusive.
+    # @option options [Integer] :chartDuration  The duration of past data to show. Valid values are "1year", "5years" and "10years". If unspecified, the value defaults to "1year".
+    # @return [Models::PropertyChart] Property chart.
+    def self.chart(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :zpid => nil,
+        :unit_type => nil,
+        :width => nil,
+        :height => nil,
+        :chartDuration => nil,
+      }.merge!(options)
+    
+      if options[:zpid].nil?
+        raise ArgumentError, "The zpid option is required"
+      end
+      if options[:unit_type].nil?
+        raise ArgumentError, "The unit_type option is required"
+      end
+      
+      Models::PropertyChart.new(Rubillow::Request.get("GetChart", options))
+    end
+
+    # Retrieve a list of comps for the specified property.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetComps.htm}.
+    # 
+    # @example
+    #   data = Rubillow::HomeValuation.comps({ :zpid => '48749425', :count => 5 })
+    #   
+    #   if data.success?
+    #     puts data.principal.price  # "1032000"
+    #     data.comparables.each do |comp|
+    #       puts comparables.price
+    #     end
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [Integer] :zpid   The Zillow Property ID of the property. (required)
+    # @option options [Integer] :count  The number of comps to return, between 1 and 25 inclusive. (required)
+    # @return [Models::Comps] Comps Property information and comps list.
+    def self.comps(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :zpid => nil,
+        :count => nil,
+      }.merge!(options)
+    
+      if options[:zpid].nil?
+        raise ArgumentError, "The zpid option is required"
+      end
+      if options[:count].nil?
+        raise ArgumentError, "The count option is required"
+      end
+      
+      Models::Comps.new(Rubillow::Request.get("GetComps", options))
+    end
+  end
+end

data/lib/rubillow/models.rb

@@ -0,0 +1,83 @@
+require "nokogiri"
+require "active_support/core_ext/string"
+require "active_support/inflector"
+
+module Rubillow
+  # Sub module for returned and parsed web service data
+  module Models
+    # Base class for data models
+    class Base
+      # @return [String] the raw XML content from the service
+      attr_accessor :xml
+      
+      # @private
+      # @return [Nokogiri::XML::Reader] xml parser
+      attr_accessor :parser
+      
+      # @return [String] response message
+      attr_accessor :message
+      
+      # @return [Integer] response code
+      attr_accessor :code
+      
+      # @return [Boolean] nearing API's daily request limit
+      attr_accessor :near_limit
+    
+      # @private
+      # Initialize the model
+      #
+      # @param [String] xml the raw XML from the service
+      def initialize(xml)
+        if !xml.blank?
+          @xml = xml
+          @parser = Nokogiri::XML(xml) { |cfg| cfg.noblanks }
+          parse
+        else
+          @code = -1
+          @message = 'Error connecting to remote service.'
+        end
+      end
+    
+      # Was the request successful?
+      # @return [Boolean] +true+ on successful request
+      def success?
+        @code.to_i == 0
+      end
+    
+      protected
+      
+      # @private
+      # Parses the xml content
+      def parse
+        @message = @parser.xpath('//message/text').text
+        @code = @parser.xpath('//message/code').text.to_i
+        
+        limit = @parser.xpath('//message/limit-warning')
+        @near_limit = !limit.empty? && limit.text.downcase == "true"
+      end
+    end
+  end
+end
+
+require "rubillow/models/zpidable"
+require "rubillow/models/linkable"
+require "rubillow/models/addressable"
+require "rubillow/models/zestimateable"
+require "rubillow/models/property_basics"
+require "rubillow/models/images"
+require "rubillow/models/search_result"
+require "rubillow/models/chart"
+require "rubillow/models/property_chart"
+require "rubillow/models/comps"
+require "rubillow/models/rate_summary"
+require "rubillow/models/monthly_payments"
+require "rubillow/models/postings"
+require "rubillow/models/posting"
+require "rubillow/models/deep_search_result"
+require "rubillow/models/deep_comps"
+require "rubillow/models/updated_property_details"
+require "rubillow/models/demographics"
+require "rubillow/models/demographic_value"
+require "rubillow/models/region_children"
+require "rubillow/models/region_chart"
+require "rubillow/models/region"