zillow4r 0.1.0

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+gem "nokogiri"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "mocha"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.1"
+  gem "rcov", ">= 0"
+end
+
+group :test do
+  gem "mocha"
+end

data/Gemfile.lock

@@ -0,0 +1,23 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.1)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    mocha (0.9.10)
+      rake
+    nokogiri (1.4.4)
+    rake (0.8.7)
+    rcov (0.9.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.1)
+  mocha
+  nokogiri
+  rcov

data/README.md

@@ -0,0 +1,69 @@
+Zillow4r
+--------
+
+Simple ruby interface for the [Zillow API](http://www.zillow.com/howto/api/APIOverview.htm).
+
+### Documentation & Requirements
+* Nokogiri
+
+### Supported API Calls
+
+As of version 0.1.0, we support the following API calls:
+
+* [GetZestimate](http://www.zillow.com/howto/api/GetZestimate.htm)
+* [GetSearchResults](http://www.zillow.com/howto/api/GetSearchResults.htm)
+* [GetChart](http://www.zillow.com/howto/api/GetChart.htm)
+* [GetComps](http://www.zillow.com/howto/api/GetComps.htm)
+* [GetDeepComps](http://www.zillow.com/howto/api/GetDeepComps.htm)
+* [GetDeepSearchResults](http://www.zillow.com/howto/api/GetDeepSearchResults.htm)
+* [GetUpdatedPropertyDetails](http://www.zillow.com/howto/api/GetUpdatedPropertyDetails.htm)
+* [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.html)
+
+To make these calls, you call the module method `Zillow4r.fetch_[name]` where name is the underscored
+api call name without the "Get".  For example, if you wanted to call the GetDeepSearchResults
+API, call `Zillow4r.fetch_deep_search_results` with the search parameters specified by the API.
+
+Note: Zillow4r will automatically add your ZWSID to the API request.
+
+### Examples
+
+Basic usage:
+
+    require 'rubygems'
+    require 'zillow4r'
+
+    Zillow4r.zws_id = 'YOUR_API_KEY'
+
+    response = Zillow4r.fetch_updated_property_details(:zpid => 123456)
+    response.class
+    =>  Zillow4r::Api::UpdatedPropertyDetails
+
+    response = Zillow4r.fetch_search_results(:address => "2114 Bigelow Ave", :citystatezip => "Seattle, WA")
+    response.class
+    =>  Zillow4r::Api::SearchResults
+    response.results.class
+    =>  Array
+    response.results.first.class
+    =>  Zillow4r::Property
+
+### Models
+
+Zillow4r uses several intermediate data models which represent repeated data structures contained within
+Zillow's xml.  These include:
+
+* Zillow4r::Address
+* Zillow4r::Links
+* Zillow4r::Images
+* Zillow4r::Region
+* Zillow4r::Property
+* Zillow4r::Posting
+* Zillow4r::Zestimate
+* Zillow4r::ComparableProperty
+
+These models define the data that they contain through their position within the xml data.
+
+### Testing
+
+Test cases are mocked using the sample API output provided for each API call in the documentation from Zillow.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "zillow4r"
+  gem.homepage = "http://github.com/chingor13/zillow4r"
+  gem.license = "MIT"
+  gem.summary = %Q{Simple ruby interface for the Zillow API}
+  gem.description = %Q{Simple ruby interface for the Zillow API. See http://www.zillow.com/howto/api/APIOverview.htm}
+  gem.email = "ching.jeff@gmail.com"
+  gem.authors = ["Jeff Ching"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+require 'rcov/rcovtask'
+Rcov::RcovTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "zillow4r #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/zillow4r.rb

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'open-uri'
+require 'nokogiri'
+require 'cgi'
+module Zillow4r
+
+  HTTP_USER_AGENT = "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.1) Gecko/20060111 Firefox/1.5.0.1"
+  HTTP_ACCEPT = "text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5"
+  WEB_API_HOST = "www.zillow.com"
+  WEB_API_PORT = 80
+
+  class << self
+    attr_accessor :zws_id
+
+    def method_missing(a, *args)
+      if match = a.to_s.match(/^fetch_(.*)$/)
+        self.fetch(match[1], args[0])
+      else
+        super(a, *args)
+      end
+    end
+
+    def fetch(type, params = {})
+      klass = get_class(type)
+      path = build_path(klass, params)
+      url = "http://" + WEB_API_HOST + path
+      klass.new(open(url).read)
+    end
+
+    def build_path(klass, params)
+      p = ["zws-id=#{Zillow4r.zws_id}"]
+      params.each do |key,value|
+        p << "#{key}=#{CGI.escape(value.to_s)}"
+      end
+      "#{klass.path}?#{p.join('&')}"
+    end
+
+    private
+
+    def get_class(type)
+      class_name = type.split("_").map{|word| word[0..0].upcase + word[1..word.length]}.join("")
+      Zillow4r::Api.const_get(class_name)
+    end
+  end
+
+end
+
+require 'zillow4r/models.rb'
+require 'zillow4r/api.rb'

data/lib/zillow4r/api.rb

@@ -0,0 +1,25 @@
+module Zillow4r
+  module Api
+    class Base < Zillow4r::Base
+      def self.path
+        raise "Need to set path for child class"
+      end
+
+      int_point "response_code", "message code", "data"
+      text_point "response_message", "message text", "data"
+
+      def data_error?
+        response_code.nil? || response_code > 500
+      end
+
+      def error?
+        response_code.nil? || response_code > 0
+      end
+    end
+  end
+end
+
+Dir.glob(File.dirname(__FILE__) + "/api/*.rb").each do |file|
+  require file
+end
+

data/lib/zillow4r/api/base.rb

@@ -0,0 +1,5 @@
+require 'nokogiri'
+module Zillow4r
+  module Api
+  end
+end

data/lib/zillow4r/api/chart.rb

@@ -0,0 +1,12 @@
+module Zillow4r
+  module Api
+    class Chart < Zillow4r::Api::Base
+      text_point :chart_url, "response url", :data
+
+      def self.path
+        "/webservice/GetChart.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/comps.rb

@@ -0,0 +1,13 @@
+module Zillow4r
+  module Api
+    class Comps < Zillow4r::Api::Base
+      object_point :principal, "response properties principal", :data, Zillow4r::Property
+      array_point :comparables, "response/properties/comparables", :data, Zillow4r::ComparableProperty
+
+      def self.path
+        "/webservice/GetComps.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/deep_comps.rb

@@ -0,0 +1,13 @@
+module Zillow4r
+  module Api
+    class DeepComps < Zillow4r::Api::Base
+      object_point :principal, "response properties principal", :data, Zillow4r::Property
+      array_point :comparables, "response/properties/comparables", :data, Zillow4r::ComparableProperty
+
+      def self.path
+        "/webservice/GetDeepComps.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/deep_search_results.rb

@@ -0,0 +1,12 @@
+module Zillow4r
+  module Api
+    class DeepSearchResults < Zillow4r::Api::Base
+      array_point :results, "response/results", :data, Zillow4r::Property
+
+      def self.path
+        "/webservice/GetDeepSearchResults.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/demographics.rb

@@ -0,0 +1,38 @@
+module Zillow4r
+  module Api
+    class Demographics < Zillow4r::Api::Base
+      object_point :region, "response region", :data, Zillow4r::Region
+      object_point :links, "response links", :data, Zillow4r::Links
+
+      # intermediate points
+      data_point :people_data_node, ["response pages", {"name" => "People"}, "tables", {"name" => "People Data"}, "data"], :data
+      data_point :owners_data_node, ["response pages", {"name" => "Homes & Real Estate"}, "tables", {"name" => "Census Summary-Occupancy"}, "data"], "data"
+
+      # city demographic values
+      float_point :city_median_age, [{"name" => "Median Age"}, "values city value"], :people_data_node
+      float_point :city_median_household_income, [{"name" => "Median Household Income"}, "values city value"], :people_data_node
+      float_point :city_average_household_size, [{"name" => "Average Household Size"}, "values city value"], :people_data_node
+      float_point :city_percent_of_homes_with_kids, [{"name" => "Homes With Kids"}, "values city value"], :people_data_node
+
+      # neighborhood demographic values
+      float_point :neighborhood_median_age, [{"name" => "Median Age"}, "values neighborhood value"], :people_data_node
+      float_point :neighborhood_median_household_income, [{"name" => "Median Household Income"}, "values neighborhood value"], :people_data_node
+      float_point :neighborhood_average_household_size, [{"name" => "Average Household Size"}, "values neighborhood value"], :people_data_node
+      float_point :neighborhood_percent_of_homes_with_kids, [{"name" => "Homes With Kids"}, "values neighborhood value"], :people_data_node
+
+      # nation demographic values
+      float_point :nation_median_age, [{"name" => "Median Age"}, "values nation value"], :people_data_node
+      float_point :nation_median_household_income, [{"name" => "Median Household Income"}, "values nation value"], :people_data_node
+      float_point :nation_average_household_size, [{"name" => "Average Household Size"}, "values nation value"], :people_data_node
+      float_point :nation_percent_of_homes_with_kids, [{"name" => "Homes With Kids"}, "values nation value"], :people_data_node
+
+      float_point :percent_owners, [{"name" => "Own"}, "value"], :owners_data_node
+      float_point :percent_renters, [{"name" => "Rent"}, "value"], :owners_data_node
+
+      def self.path
+        "/webservice/GetDemographics.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/region_chart.rb

@@ -0,0 +1,12 @@
+module Zillow4r
+  module Api
+    class RegionChart < Zillow4r::Api::Base
+      text_point :chart_url, "response url", :data
+
+      def self.path
+        "/webservice/GetRegionChart.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/region_children.rb

@@ -0,0 +1,14 @@
+module Zillow4r
+  module Api
+    class RegionChildren < Zillow4r::Api::Base
+      object_point :region, "response/region", :data, Zillow4r::Region
+      text_point :subregion_type, "response subregiontype", :data
+      array_point :children, "response/list", :data, Zillow4r::Region
+
+      def self.path
+        "/webservice/GetRegionChildren.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/search_results.rb

@@ -0,0 +1,12 @@
+module Zillow4r
+  module Api
+    class SearchResults < Zillow4r::Api::Base
+      array_point :results, "response/results", :data, Zillow4r::Property
+
+      def self.path
+        "/webservice/GetSearchResults.htm"
+      end
+
+    end
+  end
+end

data/lib/zillow4r/api/updated_property_details.rb

@@ -0,0 +1,52 @@
+module Zillow4r
+  module Api
+    class UpdatedPropertyDetails < Zillow4r::Api::Base
+      int_point :zpid, "response zpid", :data
+
+      # page views
+      int_point :page_view_count_month, "response pageviewcount currentmonth", :data
+      int_point :page_view_count_total, "response pageviewcount total", :data
+
+      object_point :address, "response address", :data, Zillow4r::Address
+      object_point :posting, "response posting", :data, Zillow4r::Posting
+
+      # price
+      int_point :price, "response price", :data
+      attribute_point :price_currency, "response price", :data, "currency"
+
+      object_point :links, "response links", :data, Zillow4r::Links
+      object_point :images, "response images image", :data, Zillow4r::Images
+
+      # facts
+      data_point :facts_data_node, "response editedfacts", :data
+      text_point :use_code, "usecode", :facts_data_node
+      int_point :bedrooms, "bedrooms", :facts_data_node
+      float_point :bathrooms, "bathrooms", :facts_data_node
+      int_point :finished_sq_ft, "finishedsqft", :facts_data_node
+      int_point :lot_sq_ft, "lotsizesqft", :facts_data_node
+      int_point :year_built, "yearbuilt", :facts_data_node
+      int_point :year_updated, "yearupdated", :facts_data_node
+      int_point :floors, "numfloors", :facts_data_node
+      text_point :basement, "basement", :facts_data_node
+      text_point :roof, "roof", :facts_data_node
+      text_point :view, "view", :facts_data_node
+      text_point :parking_type, "parkingtype", :facts_data_node
+      text_point :heating_sources, "heatingsources", :facts_data_node
+      text_point :heating_system, "heatingsystem", :facts_data_node
+      text_point :appliances, "appliances", :facts_data_node
+      text_point :floor_covering, "floorcovering", :facts_data_node
+      text_point :rooms, "rooms", :facts_data_node
+
+      # general info
+      text_point :home_description, "response homedescription", :data
+      text_point :neighborhood, "response neighborhood", :data
+      text_point :school_district, "response schooldistrict", :data
+      text_point :elementary_school, "response elementaryschool", :data
+      text_point :middle_school, "response middleschool", :data
+
+      def self.path
+        "/webservice/GetUpdatedPropertyDetails.htm"
+      end
+    end
+  end
+end