you_got_listed 0.2.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,25 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+Gemfile.lock
+*.gem
+spec/you_got_listed_api_key.yml
+spec/fixtures/vcr_cassettes/*.yml

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 tcocca
+
+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.rdoc

@@ -0,0 +1,226 @@
+= you_got_listed
+
+YouGotListed is a ruby gem that wraps the YouGotListings api.  YouGotListed is built on top of HTTParty and Rash (a Hashie::Mash extension).
+
+You must have access to the YouGotListings API via an api key.
+
+Currently the gem supports a subset of the full YouGotListings api and is READ-ONLY wrapper with the exception of creating Leads.
+
+YouGotListings API documentation can be found here: http://www.yougotlistings.com/wiki/index.php/Developers
+
+
+== Installation
+
+  gem install you_got_listed
+
+In a rails 2.3.x app
+
+  config.gem 'you_got_listed'
+
+
+== Usage
+
+Responses all come back as Hashie::Rash objects (see http://github.com/tcocca/rash).
+
+HTTParty parsed the xml into a Hash and Hashie::Rash will convert all keys to underscored names from camel case and then makes the keys accessible as methods.
+
+Responses by default do not raise exceptions if the API errors, but the success? method will return false.
+There are some methods that you can call that will trigger exceptions (typically the ! methods, see below).
+
+Timeout::Errors and other Exceptions are automatically rescued in the YouGotListed::Client class and will return a 
+fake response telling you that there was a timeout or an unknown error in the @response.error method, same as any actual YGL api error messages.
+
+
+=== Creating the YouGotListed Client
+
+A client object is necessary for each request type.  The client is the base class that performs all of the operations, it requires your api key.
+
+  @ygl = YouGotListed::Client.new('you_api_key')
+
+** For all operations the "key" required parameter is automatically passed so you never need to worry about this parameter as the client class includes it by default.
+
+=== Searching Accounts
+
+To find all of the accounts that your API key can access call #search off the Accounts class:
+
+  @accounts = YouGotListed::Accounts.new(@ygl)
+  @results = @accounts.search
+
+The search method takes an optional hash of options that can be found here:  http://www.yougotlistings.com/wiki/index.php/Account_API
+Pass the options in the following format:
+
+  @results = @accounts.search(:page_count => 25, :page_index => 2)
+
+The key names are the same as the param name.
+
+== Searching for Agents
+
+  @agents = YouGotListed::Agent.new(@ygl)
+
+The YouGotListed::Agent class has 3 methods:
+
+See the Documentation here: http://www.yougotlistings.com/wiki/index.php/Agents_API
+
+#find_all Will return all agents belonging to your accounts, there are not params required.
+
+  @result = @agents.find_all
+
+#find : YouGotListed::Agent#find takes 1 argument an agent_id.  The operation will raise an error if the api returns an error
+
+  @result = @agents.find(1)
+
+#find_by_id : YouGotListed::Agent#find_by_id is the same as #find however it will not raise an error.
+
+  @result = @agents.find_by_id(1)
+
+
+== Creating a Lead
+
+The YouGotListed::Lead class has 2 methods to create a lead in the YouGotListings system: http://www.yougotlistings.com/wiki/index.php/Leads_Insert_API
+
+#create will insert a lead and will NOT raise an error if the api returns one
+
+#create! is the exact same but will raise an error
+
+  @leads = YouGotListed::Lead.new(@ygl)
+  @leads.create(:first_name => 'Test', :last_name => 'Lead', :email => 'test@lead.com')
+
+
+== Searching for Complexes
+
+See the API documentation: http://www.yougotlistings.com/wiki/index.php/Complexes_Search_API
+
+  @complexes = YouGotListed::Complexes.new(@ygl)
+
+There are two methods in the Complexes class: #search and #find_by_id
+
+Fist off, searching:  The #search method takes an optional hash of params.  The keys/values directly correspond to the api documentation
+  
+  @results = @complexes.search
+  @results = @complexes.search(:cities => 'Boston')
+
+
+The results from complex methods return a custom YouGotListed::Complexes::SearchResponse which inherits from the standard YouGotListed::Response.  The YouGotListed::Complexes::SearchResponse provides a few helper methods:
+
+  @results.property_complexes # => Returns an array of YouGotListed::Complex objects (see below)
+  @results.paginator # => Returns a WillPaginate::Collection object for the response.  The collection is the #property_complexes array that is returned.
+
+
+The other methods to access complexes is #find_by_id
+
+  @complex = @complexes.find_by_id('BOS-001-001')
+
+#find_by_id returns either a single YouGotListed::Complex object or nil, there is no response object.
+
+
+== YouGotListed::Complex
+
+The YouGotListed::Complex takes a Hashie::Rash object and turns it into a first level object.  Each key in that hash is turned into an instance variable and a getter is defined for the key so that you can use the methods in others.  It also takes a second param, a YouGotListed::Client object. The class provides 3 helper methods:
+
+#properties - Returns an array of YouGotListed::Listing objects (see below)
+#pictures - Returns an array of photo urls for the complex
+#find_address - Takes an address_id for and returns the corresponding address object. Addresses are tied to the complex but properties for the complex just return an address_id, so this is how we tie the address information to the property
+
+
+== Searching for Listings
+
+  @listings = YouGotListed::Listings.new(@ygl)
+  
+There are a number of ways to search for / find listings, reference documentation here: http://www.yougotlistings.com/wiki/index.php/Listings_API
+
+#search - Takes an optional hash of parameters, keys and values correspond to the documentation above
+
+  @results = @listings.search(:city_neighborhood => 'Boston:Back Bay')
+
+#featured - Takes 2 params (both optional).  The first is a params hash (same as search), the second is the 'Featured Tag' in the system.  The default is "Featured Rentals"
+
+  @results = @listings.featured
+  @results = @listings.featured(:page_count => 30)
+  @results = @listings.featured({}, 'Featured Listings') # only changing the featured tag
+
+The reason that the featured tag is second is for pagination, you must pass the :page_index through and I did not want to have to pass the default tag first, so that is why the options hash is first (I would not be completely opposed to changing this however, if somebody has a better option).
+
+Both #search and #featured return a custom YouGotListed::Listings::SearchResponse class that inherits from YouGotListed::Response.  This class provides 3 additional methods:
+
+#properties - returns an array of YouGotListed::Listing objects (see below)
+#paginator - returns a WillPaginate::Collection object (the collection is the properties array)
+#mls_results? - returns true if any of the properties have a source of 'MLS'
+
+
+There are 3 other methods for accessing listings:
+
+#find_by_id - takes an id and returns either a YouGotListed::Listing or nil
+
+  @listings.find_by_id('CAM-001-002')
+
+#find_all - takes a params hash just like search but will iterate over all pages of the results and return a single array of YouGotListed::Listing objects
+
+#find_all_by_ids - works the sames as find_all but will find the listings by IDs.  Takes 2 params.  First is either an array or comma separated string of listing_ids.  The second (optional, defaults to true) is a boolean to return off market listings.
+
+  @listings.find_all_by_ids(['CAM-001-001', 'CAM-001-002'])
+
+Again, this method iterates over all the pages of results and returns a single array of YouGotListed::Listing objects.
+
+
+== YouGotListed::Listing
+
+The YouGotListed::Listing class is similar to YouGotListed::Complex, it takes a Hashie::Rash object for a listing and provides some additional methods.
+
+#town_neighborhood - returns a string of "#{city} - #{neighborhood}" useful for display purposes, if neighborhood is blank it will just return "#{city}"
+#city_neighborhood - return a string of ""#{city}:#{neighborhood}", if neighborhood is blank it will only return "#{city}".  This method is useful because to search for listings in a location you must pass the location in this format.
+#mls_listing? - returns true if the source is "MLS"
+#latitude - returns the latitude for the property except as a float instead of a string
+#longitude - returns the longitude for the property except as a float instead of a string
+#pictures - returns an array of photo urls for the property, if there are no photos it returns nil
+#main_picture - returns the first photo url or nil if there are none
+
+#similar_listings - This method performs a search and returns an array for YouGotListed::Listing objects based on the following criteria
+
+  :min_rent => self.price.to_i * 0.9,
+  :max_rent => self.price.to_i * 1.1,
+  :min_bed => ((self.bedrooms.to_i - 1) <= 0 ? 0 : (self.bedrooms.to_i - 1)),
+  :max_bed => self.bedrooms.to_i + 1,
+  :baths => [(self.baths.to_i - 1), self.baths, (self.baths.to_i - 1)].join(','),
+  :city_neighborhood => self.city_neighborhood
+
+You can also pass a limit to the similar_listings method, the default is 6 properties (max) returned.
+
+  @property.similar_listings(10)
+
+** The method actually search for limit + 1 listings and returns the first 6 (there is no way to exclude an ID from the search so we need to pull limit + 1 in case the listing that you are on is returned so we can filter that out and still provide the number of listings you requested).
+
+
+== Extending YouGotListed::Listing
+Another benefit to this YouGotListed::Listing class is that in your app you can open the class again and add more methods if you wish.  For example create a file:  RAILS_ROOT/lib/ygl_extensions.rb with the following:
+
+  module YouGotListed
+    class Listing
+      
+      def address
+        addr = ""
+        addr = "#{street_number} " unless street_number.blank?
+        addr += "#{street_name}" unless street_name.blank?
+        addr += ", Unit #{unit}" unless unit.blank? || unit == "NULL"
+        addr
+      end
+      
+    end
+  end
+
+and add require 'ygl_extensions' to your config/environment.rb file.
+
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+
+== Copyright
+
+Copyright (c) 2010-2011 Tom Cocca. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "you_got_listed #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/you_got_listed.rb

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'httparty'
+require 'hashie'
+require 'rash'
+require 'will_paginate'
+
+require 'you_got_listed/client'
+require 'you_got_listed/resource'
+require 'you_got_listed/response'
+require 'you_got_listed/error'
+require 'you_got_listed/accounts'
+require 'you_got_listed/agent'
+require 'you_got_listed/listings'
+require 'you_got_listed/listing'
+require 'you_got_listed/complexes'
+require 'you_got_listed/complex'
+require 'you_got_listed/lead'

data/lib/you_got_listed/accounts.rb

@@ -0,0 +1,9 @@
+module YouGotListed
+  class Accounts < Resource
+    
+    def search(optional_params = {})
+      process_get("/accounts/search.php", optional_params)
+    end
+    
+  end
+end

data/lib/you_got_listed/agent.rb

@@ -0,0 +1,24 @@
+module YouGotListed
+  class Agent < Resource
+    
+    def find_all
+      process_get("/agents/search.php")
+    end
+    
+    def find_by_id(agent_id)
+      get_agent(agent_id)
+    end
+    
+    def find(agent_id)
+      get_agent(agent_id, true)
+    end
+    
+    private
+    
+    def get_agent(agent_id, raise_error = false)
+      params = {:id => agent_id}
+      process_get("/agents/search.php", params, raise_error)
+    end
+    
+  end
+end

data/lib/you_got_listed/client.rb

@@ -0,0 +1,25 @@
+module YouGotListed
+  class Client
+    
+    include HTTParty
+    format :xml
+    base_uri "https://yougotlistings.com/api"
+    
+    attr_accessor :api_key
+    
+    def initialize(api_key)
+      self.class.default_params :key => api_key
+    end
+    
+    def perform_request(http_method, path, params = {})
+      begin
+        self.class.send(http_method, path, :query => params)
+      rescue Timeout::Error
+        {"YGLResponse" => {"responseCode" => "996", "Error" => "Timeout"}}
+      rescue Exception
+        {"YGLResponse" => {"responseCode" => "999", "Error" => "Unknown Error"}}
+      end
+    end
+    
+  end
+end

data/lib/you_got_listed/complex.rb

@@ -0,0 +1,42 @@
+module YouGotListed
+  class Complex
+    
+    attr_accessor :client
+    
+    def initialize(listing, client)
+      listing.each do |key, value|
+        self.instance_variable_set('@'+key, value)
+        self.class.send(:define_method, key, proc{self.instance_variable_get("@#{key}")})
+      end
+      self.client = client
+    end
+    
+    def properties
+      return [] if self.listings.blank?
+      props = []
+      if self.listings.listing.is_a?(Array)
+        self.listings.listing.each do |listing|
+          listing = listing.merge(find_address(listing.address_id))
+          props << YouGotListed::Listing.new(listing, self.client)
+        end
+      else
+        listing = self.listings.listing.merge(find_address(listing.address_id))
+        props << YouGotListed::Listing.new(listing, self.client)
+      end
+      props
+    end
+    
+    def pictures
+      self.photos.photo unless self.photos.blank? || self.photos.photo.blank?
+    end
+    
+    def find_address(address_id)
+      if addresses.address.is_a?(Array)
+        addresses.address.find{|address| address.id == address_id}
+      else
+        addresses.address
+      end
+    end
+    
+  end
+end

data/lib/you_got_listed/complexes.rb

@@ -0,0 +1,53 @@
+module YouGotListed
+  class Complexes < Resource
+    
+    def search(params = {})
+      params[:page_count] ||= 20
+      params[:page_index] ||= 1
+      params[:sort_name] ||= "Name"
+      params[:sort_dir] ||= "asc"
+      params[:detail_level] ||= 2
+      SearchResponse.new(self.client.perform_request(:get, '/complexes/search.php', params), self.client, params[:page_count])
+    end
+    
+    def find_by_id(complex_id)
+      response = SearchResponse.new(self.client.perform_request(:get, '/complexes/search.php', {:complex_id => complex_id}), self.client, 20)
+      (response.success? && response.property_complexes.size > 0) ? response.property_complexes.first : nil
+    end
+    
+    class SearchResponse < YouGotListed::Response
+      
+      attr_accessor :limit, :paginator_cache, :client
+      
+      def initialize(response, client, limit = 20, raise_error = false)
+        super(response, raise_error)
+        self.limit = limit
+        self.client = client
+      end
+      
+      def property_complexes
+        return [] if self.ygl_response.complexes.blank?
+        props = []
+        if self.ygl_response.complexes.complex.is_a?(Array)
+          self.ygl_response.complexes.complex.each do |complex|
+            props << YouGotListed::Complex.new(complex, self.client)
+          end
+        else
+          props << YouGotListed::Complex.new(self.ygl_response.complexes.complex, self.client)
+        end
+        props
+      end
+      
+      def paginator
+        paginator_cache if paginator_cache
+        self.paginator_cache = WillPaginate::Collection.create(
+          (self.ygl_response.page_index ? self.ygl_response.page_index : 1), 
+          self.limit, 
+          (self.ygl_response.total ? self.ygl_response.total : properties.size)) do |pager|
+          pager.replace property_complexes
+        end
+      end
+    end
+    
+  end
+end