1. Overview
Background & Genesis
Finding a ranch-style home with a basement on any major real estate platform — Zillow, Redfin, Realtor.com — is an exercise in frustration. These platforms are built for broad search and visual browsing. Their filtering systems cannot reliably isolate ranch-style architecture. The word "ranch" is inconsistently tagged, mislabeled, or omitted entirely by listing agents. Searching for ranches on these sites returns two-story colonials, split-levels, and cape cods. There is no filter for "has basement." There is no way to combine both criteria reliably.
Ranch Finder solves this by going directly to the data. It queries Redfin and Zillow through a professional real estate API, validates each listing against both structured property fields and natural language description text, and eliminates everything that doesn't meet the criteria. What remains is a curated, verified list of ranch-style homes with basements — updated weekly, delivered to a private web page.
What It Does
- Searches Redfin and Zillow across three NJ target areas: Bridgewater, Somerset, and Cranford — each with a 10-mile radius
- Filters to single-family ranch homes with basements, minimum 3 beds / 2 baths, maximum $1,000,000
- Enriches each listing with road classification, highway proximity (within ¼ mile), garage info, and Google Maps links
- Deduplicates across sources — the same address from Redfin and Zillow appears only once
- Presents results in a private web page with tabs, photos, and real-time filters
- Saves review decisions (Favorite, Maybe, Delete) instantly — no account required
The Christine Workflow
Ranch Finder is designed for asynchronous collaboration.
John reviews the full queue and marks homes he likes as ❤️ Favorite. Christine then reviews only the Favorites tab and adds her own vote — ❤️ interested or 👎 not interested. Homes where both said yes appear in the 💑 Both tab — the short list for scheduling viewings. No phone calls, no forwarded links, no "did you see the one on Cambridge Lane?"
2. Using the App
Accessing the App
URL: ranches.johnzur.com — open in any browser on desktop or mobile. No login required. The page loads live data on every visit.
Navigation Tabs
| Tab | What It Shows |
|---|---|
| 🆕 This Week | Listings first seen in the past 7 days. Start here after a new scrape run. |
| 📋 Queue | All unreviewed listings grouped by scrape date. Your main working area. |
| ⭐ Favorites | Homes John has marked as Favorite. Christine works from this tab. |
| 💑 Both | Homes where both John and Christine said yes. The viewing short list. |
| 🤔 Maybe | Homes flagged for a second look. Not deleted, not favorited yet. |
| 🗑️ Deleted | Dismissed listings. Always shown unfiltered. Restorable via the Restore button. |
Action Buttons
| Button | What It Does |
|---|---|
| ❤️ Favorite | Marks the home as John's favorite. Makes it visible to Christine in the Favorites tab. |
| 🤔 Maybe | Parks the listing for a second look without committing either way. |
| 🗑️ Delete | Dismisses the listing. One-way from the main tabs — use Restore to undo. |
| ↩️ Restore | Available in Deleted tab only. Returns the listing to the Queue. |
| ❤️ Christine | Christine's yes vote. Only available after John has favorited the listing. |
| 👎 Not Interested | Christine's no vote. Mutually exclusive with ❤️ Christine. |
All actions save instantly. A "Saved ✓" toast confirms each write. Tapping an active button again (e.g. tapping ❤️ Favorite on an already-favorited card) returns the listing to unreviewed.
3. Listing Cards
Card Fields
| Field | Description |
|---|---|
| Photo | Thumbnail from the listing. Tap to open full-size photo in a lightbox. |
| Address | Full street address. Tapping the address opens the listing on Redfin or Zillow. |
| Price | Listed asking price in dollars. |
| Beds / Baths | Bedroom and bathroom count from the listing data. |
| Lot size | Displayed as square feet and acres, e.g. "32,234 sqft (0.74 ac)". |
| Source badge | Redfin or Zillow — which platform the listing came from. |
| Basement badge |
✅ Basement Confirmed via structured API field. ⚠️ Basement? Found only in description text — verify before visiting. ❌ No Basement Not found in either source. |
| Garage | Garage type and car count if available, e.g. "🚗 2-car garage (Attached Garage)". |
| Road type | Classification of the street the property sits on (see Road Types below). |
| 🛣️ Near Highway | Only shown when a highway is within ¼ mile. Shows the highway name and exact distance in miles. |
| 📷 Street View | Opens Google Street View for the address in a new tab. |
| 🛰️ Satellite | Opens Google Maps satellite view for the address in a new tab. |
Road Type Labels
| Label | What It Means |
|---|---|
| 🏘️ Residential Street | A local neighborhood road with low through-traffic. The ideal situation. |
| 🟡 Minor Through-Road | Carries some through-traffic but primarily serves local areas. Generally acceptable. |
| 🟠 Secondary Road | A collector or county road with moderate traffic volume. Worth checking on Street View. |
| 🔴 Primary Arterial | A major road with high traffic. Expect noise and volume — factor this in carefully. |
Tip: Near Highway vs. Road Type
These are two separate things. Road Type describes the street the house sits on. Near Highway flags a major highway (interstate, parkway, turnpike) within ¼ mile — even if the house itself is on a quiet residential street. Both matter independently.
4. Filters
Tap 🔍 Filter in the nav bar to open the filter panel. Filters apply across all tabs simultaneously (except Deleted). When filters are active, the 🔍 button turns green and a count shows how many listings are visible vs. total.
Filters are AND logic. Every active filter must be satisfied. Selecting multiple criteria narrows results — it doesn't expand them.
Filter Reference
| Filter | How to Use |
|---|---|
| Town | Check one or more town names. Only listings from checked towns appear. The town list is populated dynamically from your actual data — every town present in the current listings is shown. |
| Price |
Format: whole dollars, no $ sign, no commas. Example: enter 400000 for $400,000 minimum, 800000 for $800,000 maximum.Leave Min blank for no lower limit. Leave Max blank for no upper limit. |
| Lot (acres) |
Format: decimal acres. Examples: 0.25 = quarter acre | 0.5 = half acre | 1.0 = one acre | 2.0 = two acresThe app stores lot size in square feet internally and converts to acres for comparison. Leave either blank for no limit. |
| Basement | Check one or more: ✅ Confirmed, ⚠️ Unconfirmed, ❌ None. To see only high-confidence basements, check ✅ Confirmed only. |
| Garage | Check Has Garage, No Garage, or both (= no filter on garage). |
| Road Type | Check any combination of the four road classifications. Only listings on a checked road type appear. Checking all four is the same as no filter. |
| Near Highway |
Dropdown with three options: Any (default) — no highway filter applied. 🛣️ Near Highway — show only listings within ¼ mile of a highway. ✅ Not Near Highway — exclude any listing within ¼ mile of a highway. This is a strict binary — a listing is either within ¼ mile or it isn't. |
Tap Reset to clear all filters at once.
5. Architecture
Ranch Finder is a serverless, zero-cost system. There is no application server, no database, no hosting bill. All state lives in a single JSON file in a GitHub repository.
Data Flow — Scrape Run
GitHub Actions
→
scrape.py
→
RealtyAPI
(Redfin + Zillow search & details calls)
scrape.py
→
Google Maps API
(geocode, road classification, highway proximity)
scrape.py
→
state.json + index.html
→
GitHub repo (git push)
Data Flow — Browser Session
Browser
→
GitHub Pages
(loads index.html from ranches.johnzur.com)
Browser
GET →
Cloudflare Worker
→
GitHub API
(reads state.json, returns listings)
User taps button
POST →
Cloudflare Worker
→
GitHub API
(patches one field on one listing)
Files
| File | Location | Purpose |
|---|---|---|
| scrape.py | GitHub repo root | Main Python script. Queries APIs, filters, enriches, deduplicates, writes output. |
| worker.js | Cloudflare Workers | CORS proxy between browser and GitHub API. Handles read (GET) and single-field delta writes (POST). |
| docs/index.html | GitHub Pages | Shell HTML page served at ranches.johnzur.com. All rendering is client-side. |
| docs/state.json | GitHub repo | Single source of truth. All listings, all statuses, all enrichment data. |
| weekly-scrape.yml | .github/workflows/ | GitHub Actions workflow. Currently manual-trigger only. |
Filtering Logic (scrape.py)
| Pass | What Gets Dropped |
|---|---|
| Pass 1 — Hard data | Beds < 3, Baths < 2, Price > $1,000,000, Lot = 0 |
| Pass 2 — Ranch validation | No "ranch", "one story", "single floor", "rambler" (etc.) in structured fields or description |
| Pass 2 — Basement validation | No "basement", "finished basement", "walk-out basement" (etc.) found anywhere in the listing data |
| Deduplication | Same normalized address from multiple sources — keep one, drop the rest |
6. FAQ & Troubleshooting
Q: Why do I see listings from Edison, Clark, and Spotswood?
Redfin searches by coordinates with a 10-mile radius centered on each target town. That radius overlaps towns outside the original scope. These are real ranch/basement matches — whether to include or exclude specific towns is a configuration decision.
Q: Why are there so many more Redfin listings than Zillow?
Redfin's radius search casts a wide geographic net. Zillow searches by city name, so it returns only listings explicitly listed under that municipality. The gap is expected — it's not a bug. Both sources are 100% accurate on keyword=ranch filtering.
Q: What does ⚠️ Basement mean vs. ✅?
✅ means the basement was confirmed via a structured API field (basementYN = true or equivalent). ⚠️ means the structured fields were absent or ambiguous, but the word "basement" was found in the description text. ⚠️ listings are worth a quick check of the full listing before scheduling a viewing.
Q: How do I enter price in the filter?
Whole dollars, no $ sign, no commas. To filter for homes under $700,000, enter
700000 in the Max field and leave Min blank.Q: How do I enter lot size in the filter?
Decimal acres. Examples:
0.25 = quarter acre, 0.5 = half acre, 1.0 = one acre. The app converts internally from square feet — you always enter acres.Q: My save says "Save failed — please retry." What do I do?
Tap the button again. The system has automatic retry logic for simultaneous save conflicts. If it fails repeatedly, try refreshing the page.
Q: The page says "New listings available — tap to refresh." What does that mean?
A new scrape run completed after you loaded the page. Tapping refreshes to the latest data.
Q: The 💑 Both tab is empty even though I've favorited things. Why?
The 💑 Both tab only shows listings where Christine has also tapped ❤️ Christine. It requires both votes — John's Favorite and Christine's heart — to appear there.
Q: The page isn't loading — just shows "Loading listings…"
This usually means a JavaScript error in the page. Try a hard refresh (Ctrl+Shift+R on desktop, hold-reload on mobile). If it persists, the page may need a code fix — report to John.
Q: Can I undo a Delete?
Yes. Go to the 🗑️ Deleted tab, find the listing, and tap ↩️ Restore. It returns to the Queue.