zoopla 0.2.0 → 0.2.2

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zoopla (0.2.0)
+    zoopla (0.2.2)
       curb (~> 0.7.12)
       hashie (~> 1.0.0)
       json (~> 1.4.3)

data/README.markdown

@@ -1,9 +1,13 @@
 # Zoopla API Wrapper
 
-Use this gem to access real estate data using zoopla.co.uk API from ruby code:
+Use this gem to access real estate data using zoopla.co.uk API from ruby code.
 
   * property listings with addresses, prices, agent details etc
-  * more to come
+  * request parameters are chained: `sales.in{:area => "Camden, London"}.for(200000..250000).each{|listing| puts listing.price}`
+  * transparent pagination: just pass a block to process listings
+  * error handling
+  * Zed-index
+  * integers, dates and lat/lon parameters are parsed
   
   **This gem is pre-alpha, therefore it's missing important features and it not production ready. Also, the interface may change considerably in the future**
 
@@ -38,6 +42,73 @@ To search for rentals, do a similar query:
 
 The input and output parameters for property listings are described in the [Zoopla documentation](http://developer.zoopla.com/docs/read/Property_listings)
 
+### Disambiguation
+
+If an ambiguous area is specified, a `Zoopla::DisambiguationError` will be raised
+
+    begin
+      zoopla.sales.in({:area => "Whitechapel"}).each{|listing| puts l.price}
+    rescue Zoopla::DisambiguationError => e
+      puts "Which of the following did you mean?"
+      e.areas.each{|area| puts area} # areas is an Array of Strings
+    end
+
+The output will be
+
+    Which of the following did you mean?
+    Whitechapel, Devon
+    Whitechapel, Lancashire
+    Whitechapel, London
+
+### Unknown locations
+
+If an unknown location is specified, a `Zoopla::UnknownLocationError` will be raised. If the API can provide a spelling suggestion,
+it will be available in `e.suggestion`
+
+    begin
+      zoopla.sales.in({:area => "Stok, Devon"}).each{|listing| puts l.price}
+    rescue Zoopla::UnknownLocationError => e
+      puts "Did you mean #{e.suggestion}" if e.suggestion
+    end
+
+The output will be
+
+    Did you mean stoke, Devon
+    
+### Zed-index
+
+To find out the [Zed-index](http://www.zoopla.co.uk/property/estimate/about/) of a place do
+
+    $ index_set = zoopla.zed_index.in({:area => 'London', :output_type => "town"})
+    $ puts index_set.latest # 427646
+    $ puts index_set.zed_index # 427646
+    $ puts index_set.zed_index_3month # 430923
+
+The full list of possible fields can be found in the [documentation](http://developer.zoopla.com/docs/read/Zed_Index_API)
+
+### Area value graphs
+
+To get the list of graphs do
+
+    $ graphs = zoopla.area_value_graphs.in({:postcode => "SW1A"})
+    $ puts graphs.average_values_graph_url # http://www.zoopla.co.uk/dynimgs/graph/average_prices/SW1A?width=400&height=212
+    
+To specify the size, chain the methods
+
+    $ graphs = zoopla.area_value_graphs.large.in({:postcode => "SW1A"})
+    $ puts graphs.average_values_graph_url # http://www.zoopla.co.uk/dynimgs/graph/average_prices/SW1A?width=600&height=318
+
+The full list of possible fields can be found in the [documentation](http://developer.zoopla.com/docs/read/Area_Value_Graphs)
+
+### Property rich list
+
+In line with all other methods
+
+    $ list = zoopla.rich_list.in({:area => 'NW1', :output_type => :outcode, :area_type => :streets })
+    $ list.url # "http://www.zoopla.co.uk/property/richlist/london/NW1/camden-town-regents-park-marylebone-north"
+    $ list.lowest.first.name # "Wrotham Road, London NW1"
+    
+Valid combinations of `output_type`/`area_type` are described in the [documentation](http://developer.zoopla.com/docs/read/Property_Rich_List)    
 
 ## Contributing to zoopla
  

data/lib/zoopla.rb

@@ -4,8 +4,12 @@ require 'cgi'
 require 'hashie'
 
 require File.expand_path('../zoopla/version', __FILE__)
+require File.expand_path('../zoopla/errors', __FILE__)
 require File.expand_path('../zoopla/api', __FILE__)
 require File.expand_path('../zoopla/listings', __FILE__)
+require File.expand_path('../zoopla/zed_index', __FILE__)
+require File.expand_path('../zoopla/area_value_graphs', __FILE__)
+require File.expand_path('../zoopla/property_rich_list', __FILE__)
 
 class Zoopla
   
@@ -25,4 +29,23 @@ class Zoopla
     Sales.new(@api_key)
   end
   
+  # Delegates to the ZedIndex class
+  # @return [ZedIndex]
+  def zed_index
+    ZedIndex.new(@api_key)
+  end
+  
+  # Delegates to the AreaValueGraphs class
+  # @return [AreaValueGraphs]
+  def area_value_graphs
+    AreaValueGraphs.new(@api_key)
+  end
+  
+  # Delegates to the PropertyRichList class
+  # @return [PropertyRichList]
+  def property_rich_list
+    PropertyRichList.new(@api_key)
+  end
+  alias_method :rich_list, :property_rich_list
+  
 end

data/lib/zoopla/api.rb

@@ -1,43 +1,82 @@
 class Zoopla
   
-  # Raised when Zoopla returns the HTTP status code 400
-  class BadRequestError < StandardError; end
-  
-  # Raised when Zoopla returns the HTTP status code 401
-  class UnauthorizedRequestError < StandardError; end
-  
-  # Raised when Zoopla returns the HTTP status code 403
-  class ForbiddenError < StandardError; end
-  
-  # Raised when Zoopla returns the HTTP status code 404
-  class NotFoundError < StandardError; end
-  
-  # Raised when Zoopla returns the HTTP status code 405
-  class MethodNotAllowedError < StandardError; end
-  
-  # Raised when Zoopla returns the HTTP status code 500
-  class InternalServerError < StandardError; end
-  
-  class API # abstract        
+  # Abstract class that understands how to talk to the API
+  class API
     
     def initialize(api_key)
       @key = api_key
+      reset!      
+    end
+    
+    # Resets all parameters except the API key
+    # @return [Rentals, Sales]
+    def reset!
+      @request = default_parameters
+      @actual_location = nil
+      self
+    end
+    
+    # Holds standard output parameters for the call to the server, if any
+    def actual_location
+      return @actual_location if @actual_location
+      fetch_data(@request)
     end
     
     private
     
+    def valid_output_types
+      %w(postcode street town outcode area county country)
+    end    
+    
+    def check_output_type(location)
+      raise InvalidOutputTypeError.new("Invalid output type: #{location[:output_type]}") unless valid_output_types.include? location[:output_type].to_s or location[:output_type].nil?
+    end    
+    
+    def extract_actual_location(reply)
+      @actual_location = Hashie::Mash.new
+      %w(area_name street town postcode county country).each {|field|
+        @actual_location[field] = reply[field]
+      }
+      @actual_location.bounding_box = parse_values_if_possible(reply.bounding_box)
+    end
+    
+    def raise_error_if_necessary(code, body)
+      case code
+      when 400 then raise BadRequestError.new "Not enough parameters to produce a valid response."
+      when 401 then raise UnauthorizedRequestError.new "The API key could not be recognised and the request is not authorized."
+      when 403 then raise ForbiddenError.new "The requested method is not available for the API key specified (the API key is invalid?)."
+      when 404 then raise NotFoundError.new "A method was requested that is not available in the API version specified."
+      when 405 then raise MethodNotAllowedError.new "The HTTP request that was made requested an API method that can not process the HTTP method used."
+      when 500 then raise InternalServerError.new "Internal Server Error"
+      else
+        raise_api_specific_error_if_necessary(body)
+      end
+    end
+    
+    def raise_api_specific_error_if_necessary(body)
+      return unless body && body.error_code
+      case body.error_code.to_i
+      when -1 then raise DisambiguationError.new(body.disambiguation)
+      when 1  then raise InsufficientArgumentsError.new(body.error_string)
+      when 5  then raise InvalidRequestedDataError.new(body.error_string)
+      when 7  then raise UnknownLocationError.new(body.suggestion)
+      end
+    end
+        
     def fetch_data(params)
       response_code, body = call(url(params))       
-      return preprocess(body) if response_code == 200
-      raise case response_code
-      when 400 then BadRequestError.new "Not enough parameters to produce a valid response."
-      when 401 then UnauthorizedRequestError.new "The API key could not be recognised and the request is not authorized."
-      when 403 then ForbiddenError.new "The requested method is not available for the API key specified (the API key is invalid?)."
-      when 404 then NotFoundError.new "A method was requested that is not available in the API version specified."
-      when 405 then MethodNotAllowedError.new "The HTTP request that was made requested an API method that can not process the HTTP method used."
-      when 500 then InternalServerError.new "Internal Server Error"
-      else          StandardError.new "Unexpected HTTP error"
-      end
+      body = parse body if body
+      raise_error_if_necessary response_code, body
+      extract_actual_location(body)
+      preprocess body
+    end
+    
+    def preprocess(reply)
+      reply
+    end      
+    
+    def default_parameters
+      {}
     end
     
     def call(url)
@@ -53,7 +92,11 @@ class Zoopla
     end
     
     def tryParsingInteger(field, value)
-      (value.to_i rescue 0) if %w(price listing_id num_bathrooms num_bedrooms num_floors num_recepts).include? field
+      (value.to_i rescue 0) if %w(zed_index price listing_id num_bathrooms num_bedrooms num_floors num_recepts).include? field
+    end
+    
+    def tryParsingFloat(field, value)
+      (value.to_f rescue 0.0) if %w(longitude_min longitude_max latitude_min latitude_max).include? field
     end
     
     def tryParsingDate(field, value)
@@ -69,10 +112,15 @@ class Zoopla
     end
     
     def parse_values_if_possible(reply)
-      return reply if reply.is_a? String
+      return reply unless reply.is_a? Hash
       reply.each_pair do |field, value|                
-        reply[field] = tryParsingHash(field, value) || tryParsingArray(field, value) || tryParsingInteger(field, value) || tryParsingDate(field, value) || value
+        reply[field] = tryParsingHash(field, value) || tryParsingArray(field, value) || tryParsingInteger(field, value) ||tryParsingFloat(field, value) || tryParsingDate(field, value) || value
       end
+      reply
+    end
+    
+    def parse(reply)
+      Hashie::Mash.new.deep_update(parse_values_if_possible(JSON.parse reply))
     end
         
   end

data/lib/zoopla/area_value_graphs.rb

@@ -0,0 +1,57 @@
+class Zoopla
+  
+  class AreaValueGraphs < API
+    
+    # Defines the search area. All possible params are described at http://developer.zoopla.com/docs/
+    # @param [Hash] Location hash
+    # @return [AreaValueGraphs]
+    def in(location)
+      check_output_type location
+      @request.merge! location
+      reply = fetch_data(@request)
+      fields = %w(area_values_url home_values_graph_url value_trend_graph_url value_ranges_graph_url average_values_graph_url)
+      filtered = fields.inject({}) do |result, field|
+        result[field] = reply[field]
+        result
+      end
+      Hashie::Mash.new.update filtered
+    end
+    
+    # Sets the size of the returned images to small
+    # @return AreaValueGraphs
+    def small
+      @request[:size] = 'small'
+      self
+    end
+
+    # Sets the size of the returned images to medium
+    # @return AreaValueGraphs
+    def medium
+      @request[:size] = 'medium'
+      self
+    end
+
+    # Sets the size of the returned images to large
+    # @return AreaValueGraphs
+    def large
+      @request[:size] = 'large'
+      self
+    end
+
+  private
+
+    def api_call
+      'area_value_graphs'
+    end      
+
+    def default_parameters
+      {:output_type => 'outcode'}
+    end
+
+    def valid_output_types
+      %w(outcode)
+    end
+
+  end
+  
+end

data/lib/zoopla/errors.rb

@@ -0,0 +1,54 @@
+class Zoopla
+  
+  # Raised when Zoopla returns the HTTP status code 400
+  class BadRequestError < StandardError; end
+  
+  # Raised when Zoopla returns the HTTP status code 401
+  class UnauthorizedRequestError < StandardError; end
+  
+  # Raised when Zoopla returns the HTTP status code 403
+  class ForbiddenError < StandardError; end
+  
+  # Raised when Zoopla returns the HTTP status code 404
+  class NotFoundError < StandardError; end
+  
+  # Raised when Zoopla returns the HTTP status code 405
+  class MethodNotAllowedError < StandardError; end
+  
+  # Raised when Zoopla returns the HTTP status code 500
+  class InternalServerError < StandardError; end
+  
+  # Raised when there are insufficient arguments for the API to return a result
+  class InsufficientArgumentsError < StandardError; end
+  
+  # Raised under mysterious circumstances 
+  class InvalidRequestedDataError < StandardError; end
+  
+  # Raised when an invalid output type is specified
+  class InvalidOutputTypeError < StandardError; end
+  
+  # Raised when an ambiguous area name is given, e.g. Whitechapel (is it in London? Devon? Lancashire?)
+  class DisambiguationError < StandardError
+    
+    # Array of possible locations (Strings)
+    attr_reader :areas
+    
+    def initialize(areas)
+      @areas = areas
+    end
+
+  end
+  
+  # Raised when an unknown location is searched for, e.g. Stok
+  class UnknownLocationError < StandardError
+    
+    # String, a spelling suggestion, may be nil
+    attr_reader :suggestion
+    
+    def initialize(suggestion)
+      @suggestion = suggestion
+    end
+    
+  end
+  
+end

data/lib/zoopla/listings/listing.rb

@@ -7,6 +7,7 @@ class Zoopla
     # @param [Hash] Location hash
     # @return [Sales, Rentals]
     def in(location)
+      check_output_type location
       @request.merge! location
       self
     end
@@ -130,6 +131,7 @@ class Zoopla
     
     # Iterates over the results. Possible fields are described at http://developer.zoopla.com/docs/read/Property_listings
     # @yield [Hashie::Mash] a listing with data, e.g. sales.each{|listing| puts listing.price }
+    # @raise Zoopla::DisambiguationError if an ambiguous area is specified. Always expect this exception
     def each
       fetched_so_far, number_of_results = 0, 0
       @request[:page_number] = 1
@@ -142,14 +144,7 @@ class Zoopla
         end
       end while fetched_so_far < number_of_results 
     end
-    
-    # Resets all parameters except the API key
-    # @return [Rentals, Sales]
-    def reset!
-      @request = default_parameters
-      self
-    end      
-    
+        
     private
     
     def set_limiting_value(limit, attribute, value)
@@ -173,13 +168,8 @@ class Zoopla
     end
     
     def preprocess(reply)
-      reply = JSON.parse reply
-      number_of_results = reply["result_count"] || 0
-      listings = reply["listing"].inject([]) do |memo, listing|
-        parse_values_if_possible(listing)
-        memo << Hashie::Mash.new.update(listing)
-      end
-      [number_of_results, listings]        
+      number_of_results = reply.result_count || 0
+      [number_of_results, reply.listing]
     end
     
     def api_call

data/lib/zoopla/listings/rentals.rb

@@ -4,12 +4,7 @@ class Zoopla
   class Rentals < API
     
     include Zoopla::Listing
-    
-    def initialize(*args)
-      super(*args)
-      reset!
-    end                         
-    
+        
     # Include property listings that are already rented in the results
     # @return [Rentals]
     def include_rented

data/lib/zoopla/listings/sales.rb

@@ -5,11 +5,6 @@ class Zoopla
     
     include Zoopla::Listing
     
-    def initialize(*args)
-      super(*args)
-      reset!
-    end      
-    
     # Whether to include property listings that are already sold in the results
     # @return [Sales]
     def include_sold

data/lib/zoopla/property_rich_list.rb

@@ -0,0 +1,37 @@
+class Zoopla
+  
+  class PropertyRichList < API
+    
+    # Defines the search area. All possible params are described at http://developer.zoopla.com/docs/
+    # @param [Hash] Location hash
+    # @return [PropertyRichList]
+    def in(location)
+      check_output_type location
+      # check_area_type location
+      @request.merge! location
+      reply = fetch_data(@request)
+      result = Hashie::Mash.new
+      result.richlist_url = result.url = reply.richlist_url
+      result.highest = reply.highest
+      result.lowest = reply.lowest
+      result
+    end
+    
+    private
+        
+    def api_call
+      'richlist'
+    end      
+
+    def default_parameters
+      {:output_type => 'outcode'}
+    end
+
+    def valid_output_types
+      %w(outcode area town county country)
+    end
+    
+    
+  end
+  
+end

data/lib/zoopla/version.rb

@@ -3,7 +3,7 @@ class Zoopla
   module Version
     MAJOR = 0
     MINOR = 2
-    PATCH = 0
+    PATCH = 2
 
     STRING = [MAJOR, MINOR, PATCH].compact.join('.')
   end

data/lib/zoopla/zed_index.rb

@@ -0,0 +1,37 @@
+class Zoopla
+  
+  class ZedIndex < API
+    
+    # Defines the search area. All possible params are described at http://developer.zoopla.com/docs/
+    # @param [Hash] Location hash
+    # @return [ZedIndex]
+    def in(location)
+      check_output_type location
+      @request.merge! location
+      reply = fetch_data(@request)
+      fields = %w(area_url zed_index zed_index_3month zed_index_6month zed_index_1year zed_index_2year zed_index_3year zed_index_4year zed_index_5year)
+      filtered = fields.inject({:latest => reply["zed_index"].to_i}) do |result, field|
+        reply[field] = reply[field].to_i if field =~ /zed_index/ && reply[field]
+        result[field] = reply[field]
+        result
+      end
+      Hashie::Mash.new.update filtered
+    end
+    
+  private
+    
+    def api_call
+      'zed_index'
+    end      
+    
+    def default_parameters
+      {:output_type => 'outcode'}
+    end
+    
+    def valid_output_types
+      %w(town outcode county country)
+    end
+        
+  end
+  
+end

data/test/api_replies/area_value_graphs.js

@@ -0,0 +1 @@
+{"country":"England","area_name":null,"longitude":-0.146927,"street":null,"town":"","average_values_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/average_prices/NW1?width=400&height=212","latitude":51.5330895,"value_ranges_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/price_bands/NW1?width=400&height=212","value_trend_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/local_type_trends/NW1?width=400&height=212","county":"London","bounding_box":{"latitude_min":"51.518085","longitude_min":"-0.170917","longitude_max":"-0.122937","latitude_max":"51.548094"},"area_values_url":"http://www.zoopla.co.uk/home-values/london/NW1/camden-town-regents-park-marylebone-north","postcode":"NW1","home_values_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/home_value/oc/NW1?width=400&height=212"}

data/test/api_replies/area_value_graphs_large.js

@@ -0,0 +1 @@
+{"country":"England","area_name":null,"longitude":-0.146927,"street":null,"town":"","average_values_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/average_prices/NW1?width=600&height=318","latitude":51.5330895,"value_ranges_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/price_bands/NW1?width=600&height=318","value_trend_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/local_type_trends/NW1?width=600&height=318","county":"London","bounding_box":{"latitude_min":"51.518085","longitude_min":"-0.170917","longitude_max":"-0.122937","latitude_max":"51.548094"},"area_values_url":"http://www.zoopla.co.uk/home-values/london/NW1/camden-town-regents-park-marylebone-north","postcode":"NW1","home_values_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/home_value/oc/NW1?width=600&height=318"}

data/test/api_replies/area_value_graphs_small.js

@@ -0,0 +1 @@
+{"country":"England","area_name":null,"longitude":-0.146927,"street":null,"town":"","average_values_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/average_prices/NW1?width=200&height=106","latitude":51.5330895,"value_ranges_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/price_bands/NW1?width=200&height=106","value_trend_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/local_type_trends/NW1?width=200&height=106","county":"London","bounding_box":{"latitude_min":"51.518085","longitude_min":"-0.170917","longitude_max":"-0.122937","latitude_max":"51.548094"},"area_values_url":"http://www.zoopla.co.uk/home-values/london/NW1/camden-town-regents-park-marylebone-north","postcode":"NW1","home_values_graph_url":"http://www.zoopla.co.uk/dynimgs/graph/home_value/oc/NW1?width=200&height=106"}

data/test/api_replies/disambiguation.js

@@ -0,0 +1 @@
+{"disambiguation":["Whitechapel, Devon","Whitechapel, Lancashire","Whitechapel, London"],"error_string":"Disambiguation required.","error_code":-1}

data/test/api_replies/insufficient_arguments.js

@@ -0,0 +1 @@
+{"error_string":"Insufficient arguments","error_code":"1"}

data/test/api_replies/invalid_data.js

@@ -0,0 +1 @@
+{"error_string":"Requested data is invalid, please refer to documentation","error_code":"5"}

data/test/api_replies/no_suggestion.js

@@ -0,0 +1 @@
+{"error_string":"Unknown location entered.","error_code":"7"}

data/test/api_replies/richlist.js

@@ -0,0 +1 @@
+{"country":"England","area_name":null,"longitude":-0.146927,"highest":[{"zed_index":"5174714","name":"Park Square East, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/park-square-east"},{"zed_index":"3980577","name":"Cambridge Gate, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/cambridge-gate"},{"zed_index":"3909518","name":"Chester Terrace, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/chester-terrace"},{"zed_index":"2899292","name":"Gloucester Gate, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/gloucester-gate"},{"zed_index":"2719681","name":"Regents Park Terrace, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/regents-park-terrace"},{"zed_index":"2698449","name":"Kent Terrace, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/kent-terrace"},{"zed_index":"2463170","name":"Park Village West, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/park-village-west"},{"zed_index":"1917504","name":"Brunswick Place, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/brunswick-place-nw1"},{"zed_index":"1907749","name":"Chester Place, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/chester-place"},{"zed_index":"1881067","name":"York Terrace West, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/york-terrace-west"},{"zed_index":"1800075","name":"Chagford Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/chagford-street"},{"zed_index":"1779054","name":"York Terrace East, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/york-terrace-east"},{"zed_index":"1745053","name":"Cumberland Terrace, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/cumberland-terrace"},{"zed_index":"1737473","name":"Rothwell Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/rothwell-street"},{"zed_index":"1717895","name":"Prince Albert Road, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/prince-albert-road-nw1"},{"zed_index":"1668805","name":"St. Marks Crescent, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/st-marks-crescent"},{"zed_index":"1628394","name":"Chamberlain Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/chamberlain-street"},{"zed_index":"1622213","name":"Berkley Road, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/berkley-road"},{"zed_index":"1614178","name":"Chalcot Crescent, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/chalcot-crescent"},{"zed_index":"1396558","name":"Park Square Mews, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/park-square-mews"}],"street":null,"town":"","lowest":[{"zed_index":"200353","name":"Wrotham Road, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/wrotham-road-nw1"},{"zed_index":"209635","name":"Varndell Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/varndell-street"},{"zed_index":"217475","name":"Maiden Lane, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/maiden-lane-nw1"},{"zed_index":"226860","name":"Pancras Road, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/pancras-road"},{"zed_index":"231922","name":"Augustus Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/augustus-street"},{"zed_index":"236737","name":"Ferdinand Place, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/ferdinand-place"},{"zed_index":"237750","name":"Hampstead Road, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/hampstead-road"},{"zed_index":"239249","name":"Phoenix Road, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/phoenix-road-nw1"},{"zed_index":"240097","name":"George Mews, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/george-mews-nw1"},{"zed_index":"240484","name":"Penfold Place, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/penfold-place"},{"zed_index":"241605","name":"Werrington Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/werrington-street"},{"zed_index":"244254","name":"Purchese Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/purchese-street"},{"zed_index":"244336","name":"Harrington Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/harrington-street"},{"zed_index":"245213","name":"Stanhope Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/stanhope-street"},{"zed_index":"249274","name":"Bridgeway Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/bridgeway-street"},{"zed_index":"251384","name":"Ossulston Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/ossulston-street"},{"zed_index":"252863","name":"Mornington Place, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/mornington-place"},{"zed_index":"253139","name":"Osnaburgh Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/osnaburgh-street"},{"zed_index":"253787","name":"Barker Drive, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/barker-drive"},{"zed_index":"256284","name":"Farrier Street, London NW1","details_url":"http://www.zoopla.co.uk/home-values/london/farrier-street"}],"richlist_url":"http://www.zoopla.co.uk/property/richlist/london/NW1/camden-town-regents-park-marylebone-north","latitude":51.5330895,"county":"London","postcode":"NW1","bounding_box":{"latitude_min":"51.518085","longitude_min":"-0.170917","longitude_max":"-0.122937","latitude_max":"51.548094"}}

data/test/api_replies/suggestion.js

@@ -0,0 +1 @@
+{"suggestion":"stoke","error_string":"Unknown location entered.","error_code":"7"}

data/test/api_replies/zed_index.js

@@ -0,0 +1 @@
+{"area_url":"http://www.zoopla.co.uk/home-values/london","zed_index_1year":449379,"street":null,"zed_index":"427646","town":"","zed_index_2year":376536,"zed_index_3year":474942,"latitude":51.523591,"postcode":"","zed_index_6month":459057,"country":"England","area_name":null,"longitude":-0.105602,"zed_index_4year":463594,"zed_index_3month":430923,"county":"London","bounding_box":{"latitude_min":"51.363621","longitude_min":"-0.34844","longitude_max":"0.137236","latitude_max":"51.683561"},"zed_index_5year":416328}

data/test/test_api.rb

@@ -6,8 +6,104 @@ class TestAPI < Test::Unit::TestCase
     @rentals = Zoopla.new('my_api_key').rentals
   end
   
+  def test_invalid_output_type
+    assert_raise Zoopla::InvalidOutputTypeError do
+      @rentals.in({:output_type => :block})
+    end
+    assert_nothing_raised { @rentals.in({:output_type => "street"}) }
+    assert_nothing_raised { @rentals.in({:output_type => :street}) }
+    assert_nothing_raised { @rentals.in({:output_type => :postcode}) }
+    assert_nothing_raised { @rentals.in({:output_type => :outcode}) }
+    assert_nothing_raised { @rentals.in({:output_type => :town}) }
+    assert_nothing_raised { @rentals.in({:output_type => :county}) }
+    assert_nothing_raised { @rentals.in({:output_type => :country}) }
+    assert_nothing_raised { @rentals.in({:output_type => :area}) }
+  end
+  
+  def test_disambiguation
+    e = assert_raise Zoopla::DisambiguationError do
+      @rentals.send(:raise_error_if_necessary, 200, @rentals.send(:parse, api_reply('disambiguation')))
+    end
+    assert_equal ["Whitechapel, Devon", "Whitechapel, Lancashire", "Whitechapel, London"], e.areas
+  end
+  
+  def test_insufficient_argumetns
+    assert_raise Zoopla::InsufficientArgumentsError do
+      @rentals.send(:raise_error_if_necessary, 200, @rentals.send(:parse, api_reply('insufficient_arguments')))
+    end
+  end
+  
+  def test_unknown_location_with_suggestion
+    e = assert_raise Zoopla::UnknownLocationError do
+      @rentals.send(:raise_error_if_necessary, 200, @rentals.send(:parse, api_reply('suggestion')))
+    end
+    assert_equal 'stoke', e.suggestion
+  end
+  
+  def test_unknown_location_without_suggestion
+    e = assert_raise Zoopla::UnknownLocationError do
+      @rentals.send(:raise_error_if_necessary, 200, @rentals.send(:parse, api_reply('no_suggestion')))
+    end
+    assert_nil e.suggestion
+  end
+  
+  def test_actual_location
+    @rentals.send(:extract_actual_location, @rentals.send(:parse, api_reply('postcode')))
+    location = @rentals.actual_location
+    assert_equal 'London', location.county
+    assert_equal 'England', location.country
+    assert_equal 'E1W 3TJ', location.postcode
+    assert_equal 51.506390, location.bounding_box.latitude_min
+    assert_equal 51.506390, location.bounding_box.latitude_max
+    assert_equal -0.054738, location.bounding_box.longitude_max    
+    assert_equal -0.054738, location.bounding_box.longitude_min    
+  end
+  
+  def test_actual_location_fallback
+    @rentals.expects(:fetch_data)
+    @rentals.actual_location
+  end
+  
+  def test_actual_location_fallback
+    @rentals.send(:extract_actual_location, @rentals.send(:parse, api_reply('postcode')))
+    @rentals.expects(:fetch_data).never
+    @rentals.actual_location
+  end
+  
+  def test_deep_parsing_the_reply
+    reply = @rentals.send(:parse, api_reply('postcode'))
+    listing = reply.listing.first
+    assert_equal 11695072, listing.listing_id
+    assert_equal 'rent', listing.listing_status    
+    assert_equal 275, listing.price
+    assert_equal 'Atkinson Mcleod', listing.agent_name
+    assert_equal '135 Leman Street, Aldgate', listing.agent_address
+    assert_equal 'http://static.zoopla.co.uk/zoopla_static_agent_logo_(26302).gif', listing.agent_logo
+    assert_match(/^Charming one double bedroom apartment .+Our Ref: rpl\/iupload\/CTL070029$/m, listing.description)
+    assert_equal 'http://www.zoopla.co.uk/to-rent/details/11695072', listing.details_url
+    assert_equal 'Prospect Place, Wapping Wall, Wapping, London E1W', listing.displayable_address
+    assert_equal 'http://content.zoopla.co.uk/18d7d607146d3f0ea8cd46c48b5984084613a8ce.jpg', listing.floor_plan.first
+    assert_equal 'Picture No.05', listing.image_caption
+    assert_equal 'http://images.zoopla.co.uk/f03d30a35c97bf20825af1db8f9e52e1c936dd42_354_255.jpg', listing.image_url
+    assert_equal 51.50639, listing.latitude
+    assert_equal(-0.054738, listing.longitude)
+    assert_equal 0, listing.num_bathrooms
+    assert_equal 1, listing.num_bedrooms
+    assert_equal 0, listing.num_floors
+    assert_equal 0, listing.num_recepts
+    assert_equal 'E1W', listing.outcode
+    assert_equal 'London', listing.post_town
+    assert_equal 265, listing.price_change.first.price
+    assert_equal Date.parse('2010-07-23 19:12:46'), listing.price_change.first.date
+    assert_equal 275, listing.price_change.last.price
+    assert_equal Date.parse('2011-01-06 19:00:45'), listing.price_change.last.date
+    assert_equal 'Flat', listing.property_type
+    assert_equal 'Wapping Wall Wapping London', listing.street_name
+    assert_equal 'http://images.zoopla.co.uk/f03d30a35c97bf20825af1db8f9e52e1c936dd42_80_60.jpg', listing.thumbnail_url
+  end
+  
   def test_no_results_returned
-    number_of_results, reply = @rentals.send(:preprocess, api_reply('empty'))
+    number_of_results, reply = @rentals.send(:preprocess, @rentals.send(:parse, api_reply('empty')))
     assert_equal 0, number_of_results
     assert_equal [], reply
   end

data/test/test_area_value_graphs.rb

@@ -0,0 +1,41 @@
+require 'helper'
+
+class TestAreaValueGraphs < Test::Unit::TestCase
+  
+  def setup
+    @area_value_graphs = Zoopla.new('my_api_key').area_value_graphs
+  end
+  
+  def test_in
+    @area_value_graphs.stubs(:fetch_data).returns(@area_value_graphs.send(:parse, api_reply('area_value_graphs')))
+    index_set = @area_value_graphs.medium.in({:postcode => 'NW1'})
+    assert_equal 'http://www.zoopla.co.uk/home-values/london/NW1/camden-town-regents-park-marylebone-north', index_set.area_values_url
+    assert_equal 'http://www.zoopla.co.uk/dynimgs/graph/home_value/oc/NW1?width=400&height=212', index_set.home_values_graph_url
+    assert_equal 'http://www.zoopla.co.uk/dynimgs/graph/local_type_trends/NW1?width=400&height=212', index_set.value_trend_graph_url
+    assert_equal 'http://www.zoopla.co.uk/dynimgs/graph/price_bands/NW1?width=400&height=212', index_set.value_ranges_graph_url
+    assert_equal 'http://www.zoopla.co.uk/dynimgs/graph/average_prices/NW1?width=400&height=212', index_set.average_values_graph_url
+  end
+  
+  def test_small_size
+    @area_value_graphs.stubs(:fetch_data).returns(@area_value_graphs.send(:parse, api_reply('area_value_graphs_small')))
+    index_set = @area_value_graphs.small.in({:postcode => 'NW1'})
+    assert_equal 'http://www.zoopla.co.uk/dynimgs/graph/home_value/oc/NW1?width=200&height=106', index_set.home_values_graph_url
+  end
+  
+  def test_larse_size
+    @area_value_graphs.stubs(:fetch_data).returns(@area_value_graphs.send(:parse, api_reply('area_value_graphs_large')))
+    index_set = @area_value_graphs.large.in({:postcode => 'NW1'})
+    assert_equal 'http://www.zoopla.co.uk/dynimgs/graph/home_value/oc/NW1?width=600&height=318', index_set.home_values_graph_url
+  end
+  
+  def test_invalid_output_type    
+    assert_raise Zoopla::InvalidOutputTypeError do
+      @area_value_graphs.send(:check_output_type, {:output_type => :postcode})
+    end
+    assert_raise Zoopla::InvalidOutputTypeError do
+      @area_value_graphs.send(:check_output_type, {:output_type => :area})
+    end
+    assert_nothing_raised { @area_value_graphs.send(:check_output_type, {:output_type => :outcode}) }
+  end
+  
+end

data/test/{test_zoopla_listings.rb → test_listings.rb}

@@ -140,6 +140,7 @@ class TestZooplaListings < Test::Unit::TestCase
   end  
   
   def test_furnished
+    listing_parameter_test(:furnished, 'furnished', {:furnished => 'furnished'})
     listing_parameter_test(:furnished, 'furnished', {:furnished => 'furnished'})
     listing_parameter_test(:furnished, 'unfurnished', {:furnished => 'unfurnished'})
     listing_parameter_test(:furnished, 'part-furnished', {:furnished => 'part-furnished'})
@@ -216,46 +217,14 @@ class TestZooplaListings < Test::Unit::TestCase
   def test_requesting_multiple_results_pages_transparently
     mock = mock();
     mock.expects(:process_listing).times(12);
-    page1 = @rentals.send :preprocess, api_reply('big_request_page1')
-    page2 = @rentals.send :preprocess, api_reply('big_request_page2')
+    page1 = @rentals.send(:preprocess, @rentals.send(:parse, api_reply('big_request_page1')))
+    page2 = @rentals.send(:preprocess, @rentals.send(:parse, api_reply('big_request_page2')))
     @rentals.stubs(:fetch_data).returns(page1, page2)
     @rentals.in({:postcode => 'E1W 3TJ'}).within(0.1).price(300..400).each {|listing|
       mock.process_listing
     }    
   end
   
-  def test_deep_parsing_the_reply
-    _, reply = @rentals.send(:preprocess, api_reply('postcode'))
-    listing = reply.first
-    assert_equal 11695072, listing.listing_id
-    assert_equal 'rent', listing.listing_status    
-    assert_equal 275, listing.price
-    assert_equal 'Atkinson Mcleod', listing.agent_name
-    assert_equal '135 Leman Street, Aldgate', listing.agent_address
-    assert_equal 'http://static.zoopla.co.uk/zoopla_static_agent_logo_(26302).gif', listing.agent_logo
-    assert_match(/^Charming one double bedroom apartment .+Our Ref: rpl\/iupload\/CTL070029$/m, listing.description)
-    assert_equal 'http://www.zoopla.co.uk/to-rent/details/11695072', listing.details_url
-    assert_equal 'Prospect Place, Wapping Wall, Wapping, London E1W', listing.displayable_address
-    assert_equal 'http://content.zoopla.co.uk/18d7d607146d3f0ea8cd46c48b5984084613a8ce.jpg', listing.floor_plan.first
-    assert_equal 'Picture No.05', listing.image_caption
-    assert_equal 'http://images.zoopla.co.uk/f03d30a35c97bf20825af1db8f9e52e1c936dd42_354_255.jpg', listing.image_url
-    assert_equal 51.50639, listing.latitude
-    assert_equal(-0.054738, listing.longitude)
-    assert_equal 0, listing.num_bathrooms
-    assert_equal 1, listing.num_bedrooms
-    assert_equal 0, listing.num_floors
-    assert_equal 0, listing.num_recepts
-    assert_equal 'E1W', listing.outcode
-    assert_equal 'London', listing.post_town
-    assert_equal 265, listing.price_change.first.price
-    assert_equal Date.parse('2010-07-23 19:12:46'), listing.price_change.first.date
-    assert_equal 275, listing.price_change.last.price
-    assert_equal Date.parse('2011-01-06 19:00:45'), listing.price_change.last.date
-    assert_equal 'Flat', listing.property_type
-    assert_equal 'Wapping Wall Wapping London', listing.street_name
-    assert_equal 'http://images.zoopla.co.uk/f03d30a35c97bf20825af1db8f9e52e1c936dd42_80_60.jpg', listing.thumbnail_url
-  end
-  
   private
   
   def listing_parameter_test(param, value, result)

data/test/test_property_rich_list.rb

@@ -0,0 +1,26 @@
+require 'helper'
+
+class TestPropertyRichList < Test::Unit::TestCase
+  
+  def setup
+    @list = Zoopla.new('my_api_key').rich_list
+  end
+  
+  def test_list
+    @list.stubs(:fetch_data).returns(@list.send(:parse, api_reply('richlist')))
+    richlist = @list.in({:area => 'NW1', :output_type => :outcode, :area_type => :streets })
+    assert_equal 'http://www.zoopla.co.uk/property/richlist/london/NW1/camden-town-regents-park-marylebone-north', richlist.richlist_url
+    assert_equal 'http://www.zoopla.co.uk/property/richlist/london/NW1/camden-town-regents-park-marylebone-north', richlist.url
+    highest = richlist.highest
+    lowest = richlist.lowest
+    assert_equal 20, highest.length
+    assert_equal 'Park Square East, London NW1', highest.first.name
+    assert_equal 5174714, highest.first.zed_index
+    assert_equal 'http://www.zoopla.co.uk/home-values/london/park-square-east', highest.first.details_url
+    assert_equal 20, lowest.length
+    assert_equal 'Wrotham Road, London NW1', lowest.first.name
+    assert_equal 200353, lowest.first.zed_index
+    assert_equal 'http://www.zoopla.co.uk/home-values/london/wrotham-road-nw1', lowest.first.details_url
+  end
+
+end

data/test/test_zed_index.rb

@@ -0,0 +1,41 @@
+require 'helper'
+
+class TestZedIndex < Test::Unit::TestCase
+  
+  def setup
+    @zed_index = Zoopla.new('my_api_key').zed_index
+  end
+  
+  def test_in
+    @zed_index.stubs(:fetch_data).returns(@zed_index.send(:parse, api_reply('zed_index')))
+    index_set = @zed_index.in({:area => 'London', :output_type => "town"})
+    assert_equal 'http://www.zoopla.co.uk/home-values/london', index_set.area_url
+    assert_equal 427646, index_set.latest
+    assert_equal 427646, index_set.zed_index
+    assert_equal 430923, index_set.zed_index_3month
+    assert_equal 459057, index_set.zed_index_6month
+    assert_equal 449379, index_set.zed_index_1year
+    assert_equal 376536, index_set.zed_index_2year
+    assert_equal 474942, index_set.zed_index_3year
+    assert_equal 463594, index_set.zed_index_4year
+    assert_equal 416328, index_set.zed_index_5year
+  end
+  
+  def test_invalid_output_type    
+    assert_raise Zoopla::InvalidOutputTypeError do
+      @zed_index.send(:check_output_type, {:output_type => :street})
+    end
+    assert_raise Zoopla::InvalidOutputTypeError do
+      @zed_index.send(:check_output_type, {:output_type => :postcode})
+    end
+    assert_raise Zoopla::InvalidOutputTypeError do
+      @zed_index.send(:check_output_type, {:output_type => :area})
+    end
+    assert_nothing_raised { @zed_index.send(:check_output_type, {:output_type => :outcode}) }
+    assert_nothing_raised { @zed_index.send(:check_output_type, {:output_type => :town}) }
+    assert_nothing_raised { @zed_index.send(:check_output_type, {:output_type => :county}) }
+    assert_nothing_raised { @zed_index.send(:check_output_type, {:output_type => :country}) }
+  end
+  
+  
+end

metadata

@@ -2,7 +2,7 @@
 name: zoopla
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors: 
 - Evgeny Shadchnev
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-04 00:00:00 +00:00
+date: 2011-03-06 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -75,18 +75,35 @@ files:
 - Rakefile
 - lib/zoopla.rb
 - lib/zoopla/api.rb
+- lib/zoopla/area_value_graphs.rb
+- lib/zoopla/errors.rb
 - lib/zoopla/listings.rb
 - lib/zoopla/listings/listing.rb
 - lib/zoopla/listings/rentals.rb
 - lib/zoopla/listings/sales.rb
+- lib/zoopla/property_rich_list.rb
 - lib/zoopla/version.rb
+- lib/zoopla/zed_index.rb
+- test/api_replies/area_value_graphs.js
+- test/api_replies/area_value_graphs_large.js
+- test/api_replies/area_value_graphs_small.js
 - test/api_replies/big_request_page1.js
 - test/api_replies/big_request_page2.js
+- test/api_replies/disambiguation.js
 - test/api_replies/empty.js
+- test/api_replies/insufficient_arguments.js
+- test/api_replies/invalid_data.js
+- test/api_replies/no_suggestion.js
 - test/api_replies/postcode.js
+- test/api_replies/richlist.js
+- test/api_replies/suggestion.js
+- test/api_replies/zed_index.js
 - test/helper.rb
 - test/test_api.rb
-- test/test_zoopla_listings.rb
+- test/test_area_value_graphs.rb
+- test/test_listings.rb
+- test/test_property_rich_list.rb
+- test/test_zed_index.rb
 - zoopla.gemspec
 has_rdoc: true
 homepage: http://github.com/shadchnev/zoopla
@@ -117,10 +134,23 @@ signing_key:
 specification_version: 3
 summary: Access zoopla.co.uk API from ruby scripts
 test_files: 
+- test/api_replies/area_value_graphs.js
+- test/api_replies/area_value_graphs_large.js
+- test/api_replies/area_value_graphs_small.js
 - test/api_replies/big_request_page1.js
 - test/api_replies/big_request_page2.js
+- test/api_replies/disambiguation.js
 - test/api_replies/empty.js
+- test/api_replies/insufficient_arguments.js
+- test/api_replies/invalid_data.js
+- test/api_replies/no_suggestion.js
 - test/api_replies/postcode.js
+- test/api_replies/richlist.js
+- test/api_replies/suggestion.js
+- test/api_replies/zed_index.js
 - test/helper.rb
 - test/test_api.rb
-- test/test_zoopla_listings.rb
+- test/test_area_value_graphs.rb
+- test/test_listings.rb
+- test/test_property_rich_list.rb
+- test/test_zed_index.rb