Developer's Guide

The ForeclosureListings.com APIs let you get the latest 10 Foreclosure Homes in any zipcode, city, county or state and also know if a property in a given address is a foreclosure. All you need to do is register your domain then follow the instructions bellow.

For example, the following url:

http://api.foreclosurelistings.com/foreclosure?domain=example.com&key=yourkeyhere&state=FL&county=miami-dade

Should return an xml file like this:

<foreclosures>
<information>10 properties have been found</information>
<listing>
<address>NW 168TH ST</address>
<city>HIALEAH</city>
<county>MIAMI-DADE</county>
<state>FL</state>
<zipcode>33018</zipcode>
<price>289000</price>
<bedrooms>4</bedrooms>
<bathrooms>2</bathrooms>
<latitude>25.9448316</latitude>
<longitude>-80.2213694</longitude>
<url>http://www.foreclosurelistings.com/foreclosure-listing-HIALEAH-FL-24704275.htm</url>
</listing>
<listing>
<address>NW 179TH ST</address>
<city>HIALEAH</city>
<county>MIAMI-DADE</county>
<state>FL</state>
<zipcode>33015</zipcode>
<price>57500</price>
<bedrooms>2</bedrooms>
<bathrooms>2</bathrooms>
<latitude>25.9362710</latitude>
<longitude>-80.3193340</longitude>
<url>http://www.foreclosurelistings.com/foreclosure-listing-HIALEAH-FL-24702212.htm</url>
</listing>
...
</foreclosures>

Alternatively, the following url:

http://api.foreclosurelistings.com/foreclosure?domain=example.com&key=yourkeyhere&state=FL&county=miami-dade&format=json

Should return an JSON object like this:

{
"information" : "10 properties have been found",
"listing": [
{
"address" : "NW 168TH ST",
"city" : "HIALEAH",
"county" : "MIAMI-DADE",
"state" : "FL",
"zipcode" : "33018",
"price" : "289000",
"bedrooms" : "4",
"bathrooms" : "2",
"latitude" : "25.9448316",
"longitude" : "-80.2213694",
"url" : "http://www.foreclosurelistings.com/foreclosure-listing-HIALEAH-FL-24704275.htm"
},
{
"address" : "NW 179TH ST",
"city" : "HIALEAH",
"county" : "MIAMI-DADE",
"state" : "FL",
"zipcode" : "33015",
"price" : "57500",
"bedrooms" : "2",
"bathrooms" : "2",
"latitude" : "25.9362710",
"longitude" : "-80.3193340",
"url" : "http://www.foreclosurelistings.com/foreclosure-listing-HIALEAH-FL-24702212.htm"
},
...
]
}

Also, the following url:

http://api.foreclosurelistings.com/isforeclosure?domain=example.com&key=yourkeyhere&address=1010 Example St&city=Brooklyn&state=ny

Should return an xml file like this:

<foreclosures>
<listing>
<information>It's a foreclosure</information>
<ID>20102010</ID>
<address>1010 Example St</address>
<city>BROOKLYN</city>
<state>NY</state>
<url>http://www.foreclosurelistings.com/foreclosure-listing-BROOKLYN-NY-20102010.htm</url>
</listing>
</foreclosures>

Again, the following url:

http://api.foreclosurelistings.com/isforeclosure?domain=example.com&key=yourkeyhere&address=1010 Example St&city=Brooklyn&state=ny&format=json

Should return an JSON object like this:

{
"information" : "It's a foreclosure",
"listing":
{
"ID" : "20102010",
"address" : "NW 168TH ST",
"city" : "HIALEAH",
"state" : "FL",
"url" : "http://www.foreclosurelistings.com/foreclosure-listing-HIALEAH-FL-24704275.htm"
}
}

Usage

To use the ForeclosureListings.com APIs, you must first register your domain. Once you do, you will be given an API key to use along with your domain in the API request.

All ForeclosureListings.com APIs now support JSON. All you need to do is pass an additional parameter, &format=json, and the answer will be a JSON object, instead of an xml file, which is the default.

Recent Foreclosure Homes API: this API returns the latest foreclosure homes in any zipcode, state, county or city.

This API URL must be in the following format:

http://api.foreclosurelistings.com/foreclosure?domain=<domain>&key=<key>&<parameters>

Where <domain> is the domain you registered, <key> is the API key associated to that domain and <parameters> can be any and more than one of the following:

  • &state=<state> (e.g. &state=NY)
  • &county=<county> (e.g. &county=New York)
  • &city=<city> (e.g. &city=New York)
  • &zipcode=<zipcode> (e.g. &zipcode=10033)

Note: If you specify a zipcode, this will be used, and other parameters will be ignored. Otherwise, we'll try to find properties in the city, county and/or state you provide.

Is Foreclosure API: this API answers if a property is in foreclosure given its address.

This API URL must be in the following format:

http://api.foreclosurelistings.com/isforeclosure?domain=<domain>&key=<key>&address<address>&city=<city>&state=<state>

Where <domain> is the domain you registered, <key> is the API key associated to that domain and <address>, <city> and <state> inform the location of the property.

Error Messages

When doing an API request, you might want to read first the tag information:

<information>A message here.</information>

Besides giving you information on how many properties were found or if a property is a foreclosure or not, this will tell you if an error has occurred, and which error was that. The following messages may be received:

  • Invalid login: this occurs when you domain and API key don't match, or when you try to access from a IP different from the domain's IP.
  • Your daily access reached the end: this occurs when you reach the maximum number of access in a single day.
  • Please enter city, state, county or zipcode: this occurs when no parameters are provided to the foreclosure API.
  • Empty address, city or state: this occurs when at least one of the location parameters is not provided to the isforeclosure API.
  • Invalid address entered!: this occurs when any errors are found when trying to validate an address provided to the isforeclosure API.

Usage Policy

There's a limit to the number of calls per day you can make to the ForclosureListings.com's APIs. To avoid access problems, we limit the access to 1,000 calls per day. If you think you will make more than 1,000 API calls per day, please contact us.

Available Widgets

Available APIs