rubillow 0.0.1

data/lib/rubillow/models/zpidable.rb

@@ -0,0 +1,25 @@
+module Rubillow
+  module Models
+    # Common data for responses containing zpid's
+    module Zpidable
+      # @return [String] ZPID of property
+      attr_accessor :zpid
+      
+      protected
+      
+      # @private
+      def extract_zpid(xml)
+        # TODO: clean up this logic
+        if !xml.xpath('//response/zpid').empty?
+          selector = '//response/zpid'
+        elsif !xml.xpath('//result/zpid').empty?
+          selector = '//result/zpid'
+        else
+          selector = '//zpid'
+        end
+        
+        @zpid = xml.xpath(selector).text
+      end
+    end
+  end
+end

data/lib/rubillow/mortgage.rb

@@ -0,0 +1,75 @@
+module Rubillow
+  # Interface for the Mortgage API.
+  # 
+  # Read the more about this API at: {http://www.zillow.com/howto/api/MortgageAPIOverview.htm}
+  class Mortgage
+    # Retrieve the current rates for today and one week ago for each loan type.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetRateSummary.htm}.
+    # 
+    # @example
+    #   data = Rubillow::Mortgage.rate_summary
+    #   
+    #   if data.success?
+    #     puts data.today[:thirty_year_fixed]        # "4.01"
+    #     puts data.today[:five_one_arm]             # "2.73"
+    #     puts data.last_week[:fifteen_year_fixed]   # "3.27"
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [String] :state   The state to limit rates.
+    # @return [Models::RateSummary] Mortgage rate summary.
+    def self.rate_summary(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :state => nil,
+      }.merge!(options)
+      options[:output] = 'xml'
+    
+      Models::RateSummary.new(Rubillow::Request.get("GetRateSummary", options))
+    end
+    
+    # Retrieve the current monthly payment information for a given loan amount
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetMonthlyPayments.htm}.
+    # 
+    # \* Either the down or dollars down options are required.
+    #
+    # @example
+    #   data = Rubillow::Mortgage.monthly_payments({ :price => "300000", :down => "15", :zip => "98104" })
+    #   
+    #   if data.success?
+    #     puts data.thirty_year_fixed[:rate]                # "4.01"
+    #     puts data.thirty_year_fixed[:mortgage_insurance]  # "93"
+    #
+    #     puts data.down_payment                            # "45000"
+    #     puts data.monthly_property_taxes                  # "193"
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [Float] :price        The loan amount. (required)
+    # @option options [Float] :down         The percentage of the price as a down payment. Defaults to 20%. If less than 20%, private mortgage insurance is returned. (required *)
+    # @option options [Float] :dollarsdown  The dollar amount as down payment. Used if down option is omitted. If less than 20% of total price, private mortgage insurance is returned. (required *)
+    # @option options [String] :zip         The ZIP code for the property. If provided, property tax and hazard insurance will be returned.
+    # @return [Models::MonthlyPayments] Monthly mortage information.
+    def self.monthly_payments(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :price => nil,
+        :down => nil,
+        :dollarsdown => nil,
+        :zip => nil,
+      }.merge!(options)
+      options[:output] = 'xml'
+      
+      if options[:price].nil?
+        raise ArgumentError, "The price option is required"
+      end
+      if options[:down].nil? && options[:dollarsdown].nil?
+        raise ArgumentError, "Either the down or dollarsdown option is required"
+      end
+    
+      Models::MonthlyPayments.new(Rubillow::Request.get("GetMonthlyPayments", options))
+    end
+  end
+end

data/lib/rubillow/neighborhood.rb

@@ -0,0 +1,129 @@
+module Rubillow
+  # Interface for the Neighborhood API.
+  # 
+  # Read the more about this API at: {http://www.zillow.com/webtools/neighborhood-data/}
+  class Neighborhood
+    # Retrieve demographic data for a given region.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetDemographics.htm}.
+    #
+    # \* At least regionid or state/city, city/neighborhood, or zip options are required.
+    # 
+    # @example
+    #   data = Rubillow::Neighborhood.demographics({ :state => 'WA', :city => 'Seattle', :neighborhood => 'Ballard' })
+    #   
+    #   if data.success?
+    #     puts data.charts['Median Condo Value']
+    #     puts data.affordability_data['Zillow Home Value Index'][:neighborhood]
+    #     data.characteristics.each do |stat|
+    #       stat
+    #     end
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [String] :regionid      The id of the region (required *)
+    # @option options [String] :state         The state of the region (required *)
+    # @option options [String] :city          The city of the region (required *)
+    # @option options [String] :neighborhood  The neighborhood of the region (required *)
+    # @option options [String] :zip           The zopcode of the region (required *)
+    # @return [Models::Demographics] Region demographics data.
+    def self.demographics(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :regionid => nil,
+        :state => nil,
+        :city => nil,
+        :neighborhood => nil,
+        :zip => nil,
+      }.merge!(options)
+    
+      if options[:regionid].nil? && options[:zip].nil? && (options[:state].nil? || options[:city].nil?) && (options[:city].nil? || options[:neighborhood].nil?)
+        raise ArgumentError, "The regionid, state and city, city and neighborhood or zip option is required"
+      end 
+    
+      Models::Demographics.new(Rubillow::Request.get("GetDemographics", options))
+    end
+    
+    # Retrieve sub-regions for a region
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetRegionChildren.htm}.
+    #
+    # \* At least regionid or state options are required.
+    # 
+    # @example
+    #   data = Rubillow::Neighborhood.region_children({ :state => 'WA', :city => 'Seattle', :childtype => 'neighborhood' })
+    #   
+    #   if data.success?
+    #     puts data.region.id        # "16037"
+    #     puts data.region.latitude  # "47.559364"
+    #     data.regions.each do |region|
+    #       puts region.id
+    #     end
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [String] :regionid   The id of the region (required *)
+    # @option options [String] :state      The state of the region (required *)
+    # @option options [String] :county     The county of the region
+    # @option options [String] :city       The city of the region
+    # @option options [String] :childType  The type of regions to retrieve (available types: +state+, +county+, +city+, +zipcode+, and +neighborhood+)
+    # @return [Models::RegionChildren] Region children list.
+    def self.region_children(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :regionid => nil,
+        :state => nil,
+        :county => nil,
+        :city => nil,
+        :childtype => nil,
+      }.merge!(options)
+    
+      if options[:regionid].nil? && options[:state].nil?
+        raise ArgumentError, "The regionid or state option is required"
+      end 
+    
+      Models::RegionChildren.new(Rubillow::Request.get("GetRegionChildren", options))
+    end
+    
+    # Retrieve a chart for the specified region.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetRegionChart.htm}.
+    # 
+    # @example
+    #   chart = Rubillow::Neighborhood.chart({ :city => 'Seattle', :state => 'WA', :unit_type => 'percent', :width => 300, :height => 150 })
+    #   
+    #   if chart.success?
+    #     puts chart.to_html
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [String]  :city           The city of the region
+    # @option options [String]  :state          The state of the region
+    # @option options [String]  :neighborhood   The county of the region
+    # @option options [String]  :zip            The zipcode of the region
+    # @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+. Defaults to +1year+.
+    # @return [Models::RegionChart] Region chart.
+    def self.region_chart(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :city => nil,
+        :state => nil,
+        :neighborhood => nil,
+        :zip => nil,
+        :unit_type => nil,
+        :width => nil,
+        :height => nil,
+        :chartDuration => nil,
+      }.merge!(options)
+    
+      if options[:unit_type].nil?
+        raise ArgumentError, "The unit_type option is required"
+      end 
+    
+      Models::RegionChart.new(Rubillow::Request.get("GetRegionChart", options))
+    end
+  end
+end

data/lib/rubillow/postings.rb

@@ -0,0 +1,46 @@
+module Rubillow
+  # Interface for the Postings API.
+  # 
+  # Read the more about this API at: {http://www.zillow.com/howto/api/GetRegionPostings.htm}
+  class Postings
+    # Retrieve postings for a given region.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetRegionPostings.htm}.
+    #
+    # \* Either the zipcode or citystatezip option is required.
+    #
+    # @example
+    #   data = Rubillow::Postings.region_postings({ :zipcode => "98102", :rental => true })
+    #   
+    #   if data.success?
+    #     puts data.region_id  # "99562"
+    #     data.make_me_move.each do |posting|
+    #       puts posting.price
+    #       puts posting.address[:street]
+    #     end
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [String]  :zipcode       The zipcode of the region (required *).
+    # @option options [String]  :citystatezip  The city+state combination and/or ZIP code in which to search. Note that giving both city and state is required. Using just one will not work. (required *).
+    # @option options [Boolean] :rental        Return rental properties (defaults to +false+).
+    # @option options [String]  :postingType   The type of for sale listings to return. The default is +all+. To return only for sale by owner, set +fsbo+. To return only for sale by agent, set +fsba+. To return only Make Me Move, set +mmm+. Set +none+ and the rental parameter to +true+ to return only rentals.
+    # @return [Models::Postings] Region postings list.
+    def self.region_postings(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :zipcode => nil,
+        :citystatezip => nil,
+        :rental => false,
+        :postingType => 'all',
+      }.merge!(options)
+      options[:output] = 'xml'
+      
+      if options[:zipcode].nil? && options[:citystatezip].nil?
+        raise ArgumentError, "Either the zipcode or citystatezip option is required"
+      end
+    
+      Models::Postings.new(Rubillow::Request.get("GetRegionPostings", options))
+    end
+  end
+end

data/lib/rubillow/property_details.rb

@@ -0,0 +1,107 @@
+module Rubillow
+  # Interface for the Property Details API.
+  # 
+  # Read the more about this API at: {http://www.zillow.com/howto/api/PropertyDetailsAPIOverview.htm}
+  class PropertyDetails
+    # Retrieve extended details for a property.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetDeepSearchResults.htm}.
+    #
+    # @example
+    #   data = Rubillow::PropertyDetails.deep_search_results({ :address => '2114 Bigelow Ave', :citystatezip => 'Seattle, WA' })
+    #   
+    #   if data.success?
+    #     puts data.tax_assessment_year  # "2010"
+    #     puts data.last_sold_price      # "1025000"
+    #     puts data.address[:latitude]   # "47.637933"
+    #   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::DeepSearchResult] Extended property details.
+    def self.deep_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::DeepSearchResult.new(Rubillow::Request.get("GetDeepSearchResults", options))
+    end
+    
+    # Retrieve extended details for property and its comps.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetDeepComps.htm}.
+    #
+    # @example
+    #   data = Rubillow::PropertyDetails.deep_comps({ :zpid => '48749425', :count => 5 })
+    #   
+    #   if data.success?
+    #     puts data.principal.price  # "1032000"
+    #     data.comparables.each |comp|
+    #       puts comp.price
+    #       puts comp.address[:street]
+    #     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::DeepComps] Extended property and comp details.
+    def self.deep_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::DeepComps.new(Rubillow::Request.get("GetDeepComps", options))
+    end
+    
+    # Retrieve updated property facts for a given property.
+    #
+    # Read more at: {http://www.zillow.com/howto/api/GetUpdatedPropertyDetails.htm}.
+    #
+    # @example
+    #   data = Rubillow::PropertyDetails.updated_property_details({ :zpid => '48749425' })
+    #   
+    #   if data.success?
+    #     puts data.posting[:status]  # "1032000"
+    #     puts data.posting[:type]    # "For sale by agent"
+    #     data.edited_facts.each |fact|
+    #       puts fact
+    #     end
+    #   end
+    #
+    # @param [Hash] options The options for the API request.
+    # @option options [Integer] :zpid   The Zillow Property ID of the property. (required)
+    # @return [Models::UpdatedPropertyDetails] Updated property information.
+    def self.updated_property_details(options = {})
+      options = {
+        :zws_id => Rubillow.configuration.zwsid,
+        :zpid => nil,
+      }.merge!(options)
+    
+      if options[:zpid].nil?
+        raise ArgumentError, "The zpid option is required"
+      end
+    
+      Models::UpdatedPropertyDetails.new(Rubillow::Request.get("GetUpdatePropertyDetails", options))
+    end
+  end
+end

data/lib/rubillow/request.rb

@@ -0,0 +1,67 @@
+require 'cgi'
+require 'net/http'
+require 'uri'
+
+module Rubillow
+  # @private
+  # HTTP request manager
+  class Request
+    # Makes the request to the web service.
+    #
+    # @param [String] path     Web service name.
+    # @param [Hash]   options  Request options.
+    # @return [String, Boolean] XML on success, false if not.
+    def self.get(path, options = {})
+      zwsid = Rubillow.configuration.zwsid
+
+      unless zwsid.nil?
+        options[:zws_id] ||= zwsid
+      end
+
+      response = request.get(uri(path, options))
+
+      case response.code.to_i
+      when 200
+        response.body
+      else
+        false
+      end
+    end
+    
+    # gets the request object.
+    #
+    # @return [Net::HTTP] HTTP object.
+    def self.request
+      http = Net::HTTP.new(Rubillow.configuration.host, Rubillow.configuration.port)
+      
+      http.open_timeout = Rubillow.configuration.http_open_timeout
+      http.read_timeout = Rubillow.configuration.http_read_timeout
+      http
+    end
+    
+    # Generate the url for the request.
+    # 
+    # @param [String] path     Web service name.
+    # @param [Hash]   options  Request options.
+    def self.uri(path, options = {})
+      path = Rubillow.configuration.path + path
+      "/#{path}.htm?#{hash_to_query_string(options)}"
+    end
+
+    # Turns request options into query string.
+    #
+    # @param [Hash] hash Request options.
+    # @return [String] Formatted query string.
+    def self.hash_to_query_string(hash)
+      hash = hash.sort_by { |key, value|
+        key.to_s
+      }.delete_if { |key, value|
+        value.to_s.empty?
+      }.collect { |key, value|
+        "#{CGI.escape(key.to_s).gsub(/\_/, '-')}=#{CGI.escape(value.to_s)}"
+      }
+      
+      hash.join("&")
+    end
+  end
+end