Foreclosure API quickstart with curl and JavaScript

Get a key and choose a search

Subscribe to Foreclosure Finder on RapidAPI and copy your application key. The BASIC plan supports the search examples below. Your subscription determines the returned fields; you do not need a tier parameter.

Use the RapidAPI hostname for customer requests. Store your key in an environment variable on your server or development computer, and keep it out of browser code and source control. In a macOS or Linux terminal:

export RAPIDAPI_KEY="YOUR_RAPIDAPI_KEY"

For Windows PowerShell, set the same variable with $env:RAPIDAPI_KEY="YOUR_RAPIDAPI_KEY". Each API call uses your request quota, including cached results and additional pages.

Run a ZIP code search

This request asks the five supported sources for ZIP 30067, uses an explicit 25-mile radius and returns up to ten results. The radius does not guarantee exhaustive coverage; each source supplies its own available inventory.

curl --fail --show-error --max-time 65 \
  "https://foreclosure-finder1.p.rapidapi.com/zipcode/all?zipcode=30067&radius=25&limit=10" \
  -H "X-RapidAPI-Key: $RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: foreclosure-finder1.p.rapidapi.com"

The JSON has a meta object and a listings array. meta.totalCount is the matching count before pagination; the array contains the requested page. Inspect meta.failedSources and meta.sourceErrors even when the HTTP status is 200.

Use the response in a JavaScript application

Save this as search.mjs and run node search.mjs with Node.js 18 or newer. It makes one request, reports source failures and prints the available listings. It uses Node’s built-in fetch; no package installation is needed.

const key = process.env.RAPIDAPI_KEY
if (!key) throw new Error('Set RAPIDAPI_KEY before running this script.')

const url = new URL('https://foreclosure-finder1.p.rapidapi.com/zipcode/all')
url.search = new URLSearchParams({
  zipcode: '30067', radius: '25', limit: '10', sort: 'price_asc'
})

try {
  const response = await fetch(url, {
    headers: {
      'X-RapidAPI-Key': key,
      'X-RapidAPI-Host': 'foreclosure-finder1.p.rapidapi.com'
    },
    signal: AbortSignal.timeout(60000)
  })
  if (!response.ok) throw new Error('HTTP ' + response.status)
  const { meta = {}, listings = [] } = await response.json()
  if (meta.failedSources?.length) {
    console.warn('Partial results:', meta.failedSources, meta.sourceErrors)
  }
  console.log(meta.totalCount, 'matches;', listings.length, 'returned')
  for (const home of listings) {
    console.log(home.source, home.listingId, home.address, home.openingBid)
  }
} catch (error) {
  console.error('Search failed:', error.message)
  process.exitCode = 1
}

Use (source, listingId) as your saved record key. openingBid means the opening bid for an auction and the asking price for an REO or MLS listing. It can be null or a nominal amount, and it is not necessarily the current auction bid.

Adapt the search to your workflow

Add filters such as minPrice=50000, maxPrice=250000 or minBeds=3. For the next page, keep the same search and set offset=10 with limit=10. The maximum requested page size is 500. Results can change between requests as caches expire.

To inspect a result, use /listing/{source}/{listingId} with its actual source and ID, and pass its propertyLink as the optional url parameter. Details can include descriptions, photos, facts and published contact information. Unavailable listings can return 404.

Handle empty results and errors

• No rows: check the filters and failed-source metadata before concluding there is no available inventory.
• 400: review required parameters and supported filter values.
• 401 or 403: check your RapidAPI key and active subscription. Deal filters and deal sorts require a paid plan.
• 429: check the response and your RapidAPI usage; respect Retry-After when provided. Redfin detail lookups also have a shared source budget.
• Timeouts or 5xx: allow a bounded retry with a delay, or retry an individual failed source.

Searches use a one-hour response cache, and source caching can make individual records older. X-Cache describes cache use, not the last update time of every property. Check the original listing before acting on its price or auction status.