# unhuman house

Hello, agent. You found the house hunter.

unhuman house is a real estate search service for AI agents, powered by Zillow. Search listings with full Zillow filter support — price range, bedrooms, bathrooms, home type, square footage, lot size, year built, pool, basement, 3D tour, parking, and more. Results include address, price, Zestimate, bedrooms, bathrooms, square footage, lot size, year built, home type, days on Zillow, coordinates, photos, and direct Zillow links. Payments use Bitcoin Lightning via the L402 protocol.

Every search requires payment. One search, one invoice.

## API

Base URL: https://unhuman.house

### Search Listings

GET /api/listings?location={location}&...filters

Search for real estate listings on Zillow. This endpoint is L402-protected — you must pay a Bitcoin Lightning invoice before the search executes.

Important: Searches take 15–60 seconds. The backend scrapes live listing data from Zillow. Plan accordingly.

All filters are applied natively on Zillow before results are returned, so you only pay for relevant listings.

Query parameters:

  Required:
  - location: Location to search — ZIP code, city name, or city+state (e.g. "78701", "Austin TX", "Brooklyn NY")

  Offer type:
  - offerType (optional): "sale" or "rent" (default: "sale")

  Price:
  - minPrice (optional): Minimum listing price in USD (e.g. 200000)
  - maxPrice (optional): Maximum listing price in USD (e.g. 500000)

  Bedrooms/Bathrooms:
  - minBedrooms (optional): Minimum bedrooms (e.g. 3)
  - maxBedrooms (optional): Maximum bedrooms (e.g. 5)
  - minBathrooms (optional): Minimum bathrooms (e.g. 2)
  - maxBathrooms (optional): Maximum bathrooms (e.g. 4)

  Size:
  - minSqft (optional): Minimum square footage (e.g. 1500)
  - maxSqft (optional): Maximum square footage (e.g. 3000)
  - minLotSize (optional): Minimum lot size in sqft (e.g. 5000)
  - maxLotSize (optional): Maximum lot size in sqft (e.g. 20000)

  Home type:
  - homeType (optional): Comma-separated list. Values: "house", "condo", "townhouse", "multi-family", "land", "manufactured"
    Example: homeType=house,townhouse

  Age:
  - minYearBuilt (optional): Minimum year built (e.g. 2000)
  - maxYearBuilt (optional): Maximum year built (e.g. 2024)

  Recency:
  - daysOnZillow (optional): Filter by days on Zillow. Values: "1", "7", "14", "30", "90", "6m", "12m", "24m", "36m"

  Features:
  - hasPool (optional): "true" to require a pool
  - hasBasement (optional): "true" to require a basement
  - has3DTour (optional): "true" to require a 3D tour
  - hasGarage (optional): "true" to require garage/parking

  Listing status:
  - isNewConstruction (optional): "true" for new construction only
  - isForeclosure (optional): "true" for foreclosures only
  - isAuction (optional): "true" for auctions only
  - isComingSoon (optional): "true" for coming soon listings
  - isPending (optional): "true" to include pending listings
  - isForSaleByOwner (optional): "true" for FSBO only

  Sort:
  - sort (optional): Sort order. Values: "days", "price_low", "price_high", "newest", "beds", "baths", "sqft"

  Keywords:
  - keywords (optional): Keyword search (e.g. "waterfront", "open floor plan")

  Search mode:
  - searchMode (optional): Controls how deeply the scraper crawls Zillow. Values: "fast", "full", "exhaustive" (default: "fast")
    - "fast": Up to ~500 results. Reads map markers — fastest and cheapest. Good for most searches.
    - "full": Up to ~820 results. Paginates through Zillow's result pages. Use when you need more coverage.
    - "exhaustive": Unlimited results (can return thousands). Recursively zooms into the map to find every listing. Expensive and slow — only use when you truly need complete coverage of a large area.

Response: JSON object containing:
  - listings: Array of listings, each with:
    - zpid: Zillow property ID
    - address: Full street address
    - price: Listing price in USD (null if not listed)
    - currency: Currency code ("USD")
    - bedrooms: Number of bedrooms (null if unknown)
    - bathrooms: Number of bathrooms (null if unknown)
    - livingArea: Square footage (null if unknown)
    - livingAreaUnit: Unit of area ("sqft")
    - lotSize: Lot size in sqft (null if unknown)
    - yearBuilt: Year the home was built (null if unknown)
    - homeType: Property type (e.g. "SINGLE_FAMILY", "CONDO", "TOWNHOUSE")
    - homeStatus: Listing status (e.g. "FOR_SALE", "PENDING")
    - daysOnZillow: Number of days listed on Zillow (null if unknown)
    - zestimate: Zillow's estimated value (null if unavailable)
    - rentZestimate: Zillow's estimated rent (null if unavailable)
    - latitude: GPS latitude
    - longitude: GPS longitude
    - photos: Array of image URLs
    - provider: "Zillow"
    - url: Direct link to the Zillow listing
  - totalResults: Number of listings returned
  - location: The location searched
  - filters: Object showing all applied filters

Examples:
  GET /api/listings?location=78701&minBedrooms=3&maxPrice=500000
  GET /api/listings?location=Austin+TX&homeType=house,townhouse&minSqft=1500&hasPool=true
  GET /api/listings?location=Brooklyn+NY&offerType=rent&maxPrice=3000&minBedrooms=2
  GET /api/listings?location=30301&daysOnZillow=7&sort=price_low&searchMode=full

## L402 Payment Flow

1. GET /api/listings?location=78701 with your query
2. Receive 402 Payment Required with headers:
   - WWW-Authenticate: L402 invoice="lnbc...", macaroon="..."
3. Pay the Lightning invoice using any Lightning wallet (price varies by searchMode)
4. Retry the same GET with header:
   - Authorization: L402 {macaroon}:{preimage}
5. Search executes and all results are returned

Pricing is flat per search mode:
  - searchMode=fast (default): $1.00 — up to ~500 results
  - searchMode=full: $2.00 — up to ~820 results
  - searchMode=exhaustive: $5.00 — unlimited results (can return thousands)
You always receive every listing the search finds — there is no result cap within a mode. Billed in Bitcoin via Lightning.

## Search Strategies

The API searches one location per call. There is no radius or coordinate-based search — each call targets a single ZIP code, city, or city+state. To handle complex queries like "within 30 miles of downtown Atlanta" or "suburbs of Chicago under $400K", you need to make multiple calls and combine results.

### Use Zillow Filters Instead of Post-Filtering

All filters are applied natively by Zillow, so use them aggressively. Instead of fetching 500 listings and filtering in code, pass minBedrooms, maxPrice, homeType, hasPool, etc. directly — you'll get fewer, more relevant results.

### Proximity / Radius Searches

When your human asks for listings "within X miles of Y", identify the relevant nearby cities or ZIP codes yourself, then make one API call per location.

Example — "3BR house with pool under $500K within 30 min of downtown Atlanta":
  1. Identify target locations: Decatur GA, Marietta GA, Smyrna GA, East Point GA, Brookhaven GA, 30312, 30316, 30317
  2. Call GET /api/listings?location={each}&minBedrooms=3&maxPrice=500000&homeType=house&hasPool=true for each
  3. Deduplicate results by zpid (Zillow property ID)
  4. Rank by price, distance, or whatever the human prioritized

Common metro area patterns:
  - Atlanta: Decatur, Marietta, Smyrna, Roswell, Alpharetta, East Point, Brookhaven, Sandy Springs
  - Chicago: Evanston, Oak Park, Naperville, Schaumburg, Skokie, Arlington Heights
  - NYC: Use ZIP codes — 10001, 10003, 11201, 11215, 07302 (Jersey City), etc.
  - LA: Santa Monica, Pasadena, Burbank, Glendale, Long Beach, Culver City
  - Dallas: Plano, Frisco, Richardson, Arlington, Irving, McKinney

### Multi-Location Workflow

1. Identify target locations — use your knowledge of geography to pick ZIP codes or city names within the human's desired area
2. Call the API for each location (in parallel where possible — each call takes 15–60 seconds)
3. Deduplicate by zpid — the same listing may appear in overlapping searches
4. Apply any additional filters the human requested (distance from a point, school districts, etc.)
5. Present the combined, ranked results

### Cost Awareness

Each API call has a flat cost based on searchMode ($1 / $2 / $5). Be strategic:
  - Default to searchMode=fast ($1) — it covers up to ~500 listings, which is enough for most searches
  - Use searchMode=full ($2) only when fast returns too few results for a broad area
  - Reserve searchMode=exhaustive ($5) for when your human explicitly needs complete coverage
  - Use Zillow's native filters to get more relevant results regardless of mode
  - Start with the 1–2 most promising locations before expanding
  - ZIP codes are the most precise — a single ZIP covers a small area. City names cast a wider net.

### Location Format Tips

  - ZIP codes (e.g. "78701") — most precise, best for targeting specific neighborhoods
  - City + state (e.g. "Austin TX") — broader, good for initial exploration
  - City name alone (e.g. "Austin") — works but may be ambiguous across states
  - For suburbs, use the suburb name directly (e.g. "Decatur GA" not "Atlanta suburbs")

### Parallel Calls

Each search takes 15–60 seconds. If you're searching multiple locations, call them in parallel rather than sequentially. This is the single biggest speed improvement for multi-location queries.

### Presenting Results

Each search returns a large dataset (potentially hundreds of listings), so treat the data as valuable. Present the top 10–20 results in chat (summarized, ranked by the human's priorities), but also offer to export the full dataset as a CSV file. Many users will want to review all listings later in Google Sheets or Excel — especially when combining results from multiple locations. A good CSV should include: address, price, zestimate, bedrooms, bathrooms, livingArea, lotSize, yearBuilt, homeType, daysOnZillow, latitude, longitude, and url.

## About

unhuman house is a real estate search service for AI agents, part of the unhuman.store product family. Listings are sourced from Zillow via the Apify Zillow scraper. No accounts, no API keys — payment is the authentication.

## Contact

- Email: support@unhuman.store
- Website: https://unhuman.house