Search US homes for rent or for sale in a city.

curl -s https://wield.run/api/v1/recipes/zillow.com/search-homes | shasum -a 256
# 34d46b0a08da197cf3e2fe6cfc5d67af224b959cc8eb7b491dbe2c15e3a973cf

{
  "description": "Searches Zillow listings in a US city like the site's own map list: apartment buildings with their price range per unit type, single homes and apartments with price, beds, baths and square feet, status, coordinates and link. Paid showcase and builder placements are dropped by default.",
  "effect": "read",
  "id": "zillow.com/search-homes",
  "keywords": [
    "zillow",
    "apartments for rent",
    "homes for sale",
    "real estate",
    "rental",
    "house hunting",
    "usa",
    "immobilien usa",
    "wohnung mieten usa"
  ],
  "output": {
    "schema": {
      "properties": {
        "city": {
          "type": "string"
        },
        "currency": {
          "const": "USD"
        },
        "homes": {
          "items": {
            "properties": {
              "address": {
                "type": "string"
              },
              "area_sqft": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "baths": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "beds": {
                "description": "Number for homes; unit bed counts for buildings",
                "type": [
                  "number",
                  "string",
                  "null"
                ]
              },
              "id": {
                "type": "string"
              },
              "kind": {
                "enum": [
                  "building",
                  "home"
                ]
              },
              "latitude": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "longitude": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "paid": {
                "type": "boolean"
              },
              "price_from": {
                "description": "Lowest price (per month for rentals); for buildings the cheapest unit",
                "type": [
                  "number",
                  "null"
                ]
              },
              "price_text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "url": {
                "format": "uri",
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "listing_type": {
          "type": "string"
        },
        "total": {
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "city",
        "homes"
      ],
      "type": "object"
    },
    "value": "let $max = params.max_price, $paid = params.include_paid in {city: params.city, listing_type: params.listing_type, total: steps.search[0].total, currency: 'USD', homes: steps.search[0].homes[?($paid || !paid) && (!$max || price_from == `null` || price_from <= $max)]}"
  },
  "params": {
    "additionalProperties": false,
    "properties": {
      "city": {
        "description": "US city and state, e.g. 'Austin, TX', 'Brooklyn, NY'",
        "maxLength": 60,
        "minLength": 2,
        "type": "string"
      },
      "include_paid": {
        "default": false,
        "type": "boolean"
      },
      "listing_type": {
        "default": "rent",
        "enum": [
          "rent",
          "buy"
        ],
        "type": "string"
      },
      "max_price": {
        "description": "USD (per month for rent); filters the returned page",
        "minimum": 1,
        "type": "integer"
      },
      "page": {
        "default": 1,
        "maximum": 20,
        "minimum": 1,
        "type": "integer"
      }
    },
    "required": [
      "city"
    ],
    "type": "object"
  },
  "provenance": {
    "method": "browser-inspect",
    "notes": "spikes/zillow.md. Next.js SSR: __NEXT_DATA__ props.pageProps.searchPageState.cat1 (searchResults.listResults ~40 per page, searchList.totalResultCount). Rentals are mostly buildings (isBuilding) with units[{price '$1,833+', beds}]; single listings have unformattedPrice, beds, baths, area. isFeaturedListing was true on all 41 (not a paid signal); isShowcaseListing / isPaidBuilderNewConstruction are. Zillow runs PerimeterX/HUMAN bot defence that challenges non-browser traffic; run from the user's own browser only.",
    "recorded_at": "2026-11-07T12:56:00+01:00",
    "recorded_by": "C4"
  },
  "requires_login": false,
  "schema": "https://wield.run/schema/recipe/v1.json",
  "site": {
    "country": "US",
    "id": "zillow.com",
    "language": "en",
    "login_url": "https://www.zillow.com/user/acct/login/",
    "name": "Zillow",
    "origin": "https://www.zillow.com",
    "origins": [
      "https://www.zillow.com"
    ]
  },
  "steps": [
    {
      "description": "Next.js page; script#__NEXT_DATA__ → searchPageState.cat1.searchResults.listResults. The one-item foreach builds the city slug ('Austin, TX' → austin-tx) and the rentals path.",
      "expect": {
        "content_type": "html",
        "status": [
          200
        ]
      },
      "extract": {
        "embedded_json": {
          "selector": "script#__NEXT_DATA__",
          "vars": {
            "homes": "props.pageProps.searchPageState.cat1.searchResults.listResults[].{id: to_string(zpid || id), name: buildingName || `null`, kind: isBuilding == `true` && 'building' || 'home', address: address, price_from: (isBuilding == `true` && min(map(&to_number(replace(replace(replace(price || '0', '$', ''), ',', ''), '+', '')), units || `[]`))) || unformattedPrice || `null`, price_text: price || join(' / ', units[].price || `[]`), beds: beds || (units && join(', ', units[].beds)) || `null`, baths: baths || `null`, area_sqft: area || `null`, status: statusText || `null`, paid: isShowcaseListing == `true` || isPaidBuilderNewConstruction == `true`, latitude: latLong.latitude || `null`, longitude: latLong.longitude || `null`, url: starts_with(detailUrl || '', 'http') && detailUrl || join('', ['https://www.zillow.com', detailUrl || ''])}",
            "total": "props.pageProps.searchPageState.cat1.searchList.totalResultCount"
          }
        }
      },
      "foreach": {
        "as": "q",
        "in": "[{slug: lower(replace(replace(trim(params.city), ', ', '-'), ' ', '-')), kind: params.listing_type == 'rent' && 'rentals/' || '', pg: params.page > `1` && join('', [to_string(params.page), '_p/']) || ''}]",
        "max": 1
      },
      "id": "search",
      "parse": "html",
      "request": {
        "headers": {
          "Accept": "text/html"
        },
        "method": "GET",
        "url": "/{{q.slug}}/{{q.kind}}{{q.pg}}"
      }
    }
  ],
  "task": "Search US homes for rent or for sale in a city",
  "tos": {
    "notes": "Zillow's terms prohibit automated queries and scraping. One user-initiated search page at a time from the user's own browser (1 request).",
    "reviewed": false
  },
  "verify": {
    "checks": [
      "length(output.homes) > `5`",
      "output.total > `100`",
      "length(output.homes[?price_from > `2500`]) == `0`",
      "starts_with(output.homes[0].url, 'https://www.zillow.com/')"
    ],
    "example_params": {
      "city": "Austin, TX",
      "listing_type": "rent",
      "max_price": 2500
    },
    "max_ms": 6000
  },
  "version": 1
}