Foreclosure API quickstart with curl and JavaScript

Get a key and choose a search

Open Foreclosure Finder on RapidAPI, select Pricing and choose BASIC to start with 300 requests per month at $0. Review the displayed quotas and overage terms before subscribing. Then open an endpoint and copy your application key. BASIC supports the search examples below; 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 RapidAPI gateway response and your usage; respect Retry-After when provided. A provider 503 with SOURCE_CAPACITY_EXCEEDED means the shared Redfin detail budget is exhausted; wait or use another source. Upgrading does not bypass that shared limit.
• 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.

Upgrade when your integration needs more

First test your target locations on BASIC and confirm that the returned listings fit your application. PRO is $10/month for 10,000 requests and richer available fields, including coordinates, auction timing, valuations and rental estimates. Auction.com results can also include the deal block for spread, discount and gross yield. Field availability depends on the source and listing.

When you need those fields or more monthly requests, choose PRO on RapidAPI’s Pricing tab and review its terms. Keep the same endpoints and application key; RapidAPI sends your plan with each request. A paid plan does not guarantee listings in every location or bypass temporary upstream failures.