Rubeclosures - Ruby API wrapper for the foreclosurelistings.com API

readme.md

@@ -0,0 +1,43 @@
+Rubeclosures - Ruby API wrapper for the foreclosurelistings.com API
+----------------------------------------------------------------------------------
+The Real Estate industry has some incredibly annoying technology habits, so imagine
+my surprise when I saw that foreclosurelistings.com had finally implemented an API!
+
+Rubeclosures is just a simple Ruby wrapper around their API. Nobody likes parsing XML
+(even in Ruby, admit it), so what Rubeclosures does is wrap their data into native
+Ruby objects for your convenience.
+
+
+Documentation
+----------------------------------------------------------------------------------
+Using Rubeclosures is pretty straightfoward. Just consider the following code...
+
+    require 'rubeclosures'
+    
+	# Pull down up to 10 of the most recent foreclosure listings in your area
+    
+	# Get your api_key at foreclosurelistings.com
+    lol = Foreclosures.new("domain", "api_key")
+    
+	# Pass in state/area/county, or zipcode (object-ified)
+    epic = lol.getRecent({:zipcode => "20910"})
+    
+    puts epic[0]["city"]
+
+You can also pass Rubeclosures an existing address to check if it is a foreclosure or not.
+
+    require 'rubeclosures'
+    
+    lol = Foreclosures.new("domain", "api_key")
+    
+	# Check if this is a foreclosure or not (address/city/state as straight up args, non-obj)
+    epic = lol.getRecent("12345 Sesame St", "everytown", "CA")
+    
+	# Same data-style is returned; if the API is working correctly, you may have a string message
+	# to check against.
+    puts epic[0]["city"]
+
+
+Questions, comments?
+----------------------------------------------------------------------------------
+Hit me up at (ryan [at] venodesigns [dot] net), or on Twitter - http://twitter.com/ryanmcgrath

rubeclosures.rb

@@ -0,0 +1,65 @@
+require 'rexml/document'
+require 'open-uri'
+include REXML
+
+# A simple wrapper for the foreclosurelistings.com API.
+# Pull down the 10 most recent foreclosures for a given area,
+# or check if a given address is actually in foreclosure or not.
+
+# Author: Ryan McGrath (ryan [at] venodesigns dot net) (@ryanmcgrath on Twitter)
+
+class Foreclosures
+	def initialize(domain, api_key)
+		@domain = domain
+		@api_key = api_key
+		@recent_url = "http://api.foreclosurelistings.com/foreclosure?domain=" + @domain + "&key=" + @api_key
+		@is_foreclosure_url = "http://api.foreclosurelistings.com/isforeclosure?domain=" + @domain + "&key=" + @api_key
+	end
+
+	def getRecent(options = {})
+		# Using blank defaults, because I'm not that concerned about it at the moment
+		areas = {
+			:state => nil,
+			:county => nil,
+			:city => nil,
+			:zipcode => nil
+		}.merge options
+
+        # Exactly what you think it is. ;D
+		call_url = @recent_url
+
+		areas.each { |key, value|
+			if !value.nil? 
+				call_url += "&#{key}=#{value}"
+			end
+		}
+
+        return createObjFromXML(call_url)
+    end
+
+    def check(address, city, state)
+        call_url = @is_foreclosure_url + "&address=#{address}&city=#{city}&state=#{state}"
+        return createObjFromXML(call_url)
+    end
+
+    def createObjFromXML(call_url)
+        return_results = Array.new
+
+        file = open(call_url).read()
+        doc = Document.new file
+
+        doc.elements.each("foreclosures/listing") do |element| 
+            listing_obj = { }
+
+            element.each do |prop|
+                if prop.class == REXML::Element
+                    listing_obj[prop.name] = prop.text
+                end
+            end
+
+            return_results << listing_obj
+        end
+
+        return return_results
+    end
+end