comp-package

Comp Package Builder

Build a complete boundary-filtered comp package for a single subject property: sold comps + actives pulled live from the Zillow data API, condition bucketing, a dual-track ARV, 4-tier rehab scenarios, wholesale MAO math, and buyer targeting, delivered as one Excel workbook.

Use this skill when someone says "run comps on this property", "what's the ARV", "build a comp package", or shares a map with a drawn boundary and an address.

Requirements

• Python 3.10+ with requests and openpyxl
• An OpenWeb Ninja "Real-Time Zillow Data" API key in the OPENWEBNINJA_API_KEY environment variable (free tier available at openwebninja.com)

Workflow

Step 1: Establish subject truth from the county, not aggregators

Pull the county assessor card first (beds, baths, living sqft, year built, condition grade, sale history). Aggregator sites routinely report the wrong bedroom count (a Knox County card said 2/1 where aggregators said 5 bed). The county card also reveals the seller story: forced-sale deed types (Master's deed = tax sale, Trustee's deed = foreclosure), purchase price, and current tax delinquency are your negotiation leverage.

Step 2: Map the drawn boundary

Convert the user's drawn boundary into two machine filters:

1. A lat/lon bounding box (read corner coordinates off the map's landmarks)
2. A street-name whitelist regex (every street visibly inside the loop)

Apply BOTH: the bbox catches street-name misses, the street list catches bbox bleed across a highway or interstate edge. When a comp sits near the line, verify it against the map before keeping it.

Step 3: Pull sold + active comps via the API

Run scripts/zillow_market_pull.py (see references/api_contract.md for the endpoint contract and its traps). Key trap: a single sold search returns at most 41 rows (about 5 weeks in an active zip), so the script partitions by min_price/max_price bands and recursively splits any saturated band. Pull 12-24 months.

The API only sees MLS activity. Auction, wholesale, and off-market transfers will NOT appear; pull those from county records when they matter.