Distressed Property Leads

Finds distressed real estate in official city and county open-data portals, merges every signal onto the same property, and ranks the results so you call the most motivated owners first.

Public government records only. No logins, no protected pages, no captcha solving, no scraping of sites that forbid it.

What counts as distress

Signal	Meaning
tax_sale	The parcel went to a tax sale or scavenger sale
tax_delinquent	Property taxes unpaid, often with the amount owed
condemned	On a dangerous/condemned buildings list
demolition	Scheduled or completed blight demolition
vacant	Vacant/abandoned registry, abatement case, or 311 report
code_violation	Open building or code-enforcement violation

Why merging matters

One code violation is noise. A property carrying a vacancy registration and eight open violations is a phone call. The Actor joins records across datasets on both street address and parcel number, so signals that different agencies file under different identifiers still land on the same property:

{
  "distress_score": 61,
  "address": "6359 S HERMITAGE AVE",
  "jurisdiction": "Chicago",
  "signal_kinds": ["code_violation", "vacant"],
  "signal_count": 10,
  "score_reasons": ["vacant x2 (+26)", "code_violation x8 (+18)",
                    "2 independent signal types (+9)", "recency x1.15"]
}

Set minSignalCount to 2 to get only these stacked properties.

Scoring

distress_score is 0–100 and is a ranking aid, not a valuation. Stronger signal kinds weigh more, repeats of the same kind have diminishing returns, independent signal types earn a stacking bonus, recent records outweigh stale ones, and large sums owed add a little. Every lead ships with score_reasons so you can see the arithmetic and disagree with it.

Coverage

15 datasets across Chicago, Cook County, Cincinnati, Los Angeles, Kansas City, Richmond, Norfolk, New Orleans, New York, Howard County MD, and Sonoma County CA — roughly 5.6M source records. Every dataset in src/sources.py was probed live and its column names read off a real record before being added.

Coverage is the honest limit of this Actor: it reaches the jurisdictions that publish machine-readable open data, which is a minority of US counties. It does not cover your county unless it is listed above.

Input

Field	Meaning
states	Two-letter codes to include. Empty = all.
jurisdictions	City/county names to include. Empty = all.
signalTypes	Which distress kinds to collect. Empty = all.
maxRecordsPerSource	Rows read per dataset (default 1000).
minDistressScore	Drop leads below this score.
minSignalCount	Require N records on one property. Use 2+ for a short list.
maxResults	Cap the output. 0 = no cap.
socrataAppToken	Optional free token; raises rate limits on big runs.
requestDelaySeconds	Politeness delay between paged requests.

Output

One record per property, sorted by score, with a signals array holding each underlying government record and a link to its source dataset. A RUN_REPORT in the key-value store lists rows read and any dataset that failed, so a partial run is never silently presented as a complete one.

Running it locally

pip install -r requirements.txt
python3 tools/smoke.py 300     # live end-to-end check, no Actor runtime needed

Adding a jurisdiction

Add a Source to src/sources.py with the publisher domain, dataset id, and the real column names, then re-run the smoke test. If a dataset reports no usable rows, its address or parcel mapping is wrong — the row carried no locator the Actor could key on.

Publishers rename columns without notice. Re-run the smoke test before trusting a large run.