{
  "openapi": "3.0.1",
  "info": {
    "title": "Zillow Search Scraper: Investment Analyzer",
    "description": "Pull Zillow search listings in bulk using advanced filters for location, price, beds, baths, and home type. Get property details, estimates, photos, and agent info. Designed for real estate teams, analysts, and automation pipelines needing clean, structured Zillow market data.",
    "version": "0.1",
    "x-build-id": "X2D8hWEXX6cGOat3T"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/simpleapi~zillow-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-simpleapi-zillow-search-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/simpleapi~zillow-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-simpleapi-zillow-search-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/simpleapi~zillow-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-simpleapi-zillow-search-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "searchTargets": {
            "title": "🏘️ Zillow Search URLs or Locations",
            "type": "array",
            "description": "📍 Add Zillow search URLs (best) or location keywords (e.g. `dallas-tx`, `new-york-ny`). Full URLs with `searchQueryState` give the most accurate results.\\n\\n(Also accepts the base actor's `searchUrls` key for backward compatibility.)",
            "items": {
              "type": "string"
            }
          },
          "listingFetchMode": {
            "title": "🛰️ Listing Fetch Method",
            "enum": [
              "PAGINATION_WITH_DYNAMIC_ZOOM_INCREASE",
              "PAGINATION_WITHOUT_ZOOMING_IN",
              "MAP_MARKERS"
            ],
            "type": "string",
            "description": "🧠 How listings are collected from Zillow.\\n\\n🔍 Dynamic zoom splits map areas into smaller zones to collect more results (best for large datasets).\\n📄 Pagination without zooming uses HTML pages (helpful when the API is blocked).\\n📌 Map markers is simpler but capped at ~500 listings per search URL.\\n\\n(Also accepts the base actor's `extractionMethod` key.)"
          },
          "maxListings": {
            "title": "🎯 Max Listings to Analyze",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "📈 Maximum number of property listings to scrape and run investment analytics on per run (1-10000).\\n\\n(Also accepts the base actor's `maxItems` key.)"
          },
          "calculateInvestmentMetrics": {
            "title": "💰 Calculate Cap Rate, Rental Yield & Cash Flow",
            "type": "boolean",
            "description": "🧮 When ON, computes gross rental yield, cap rate, estimated monthly mortgage payment, monthly/annual cash flow, and cash-on-cash return for every listing using Zillow's own `rentZestimate` and `taxAssessedValue` (already fetched, zero extra requests) combined with the financing assumptions below. When OFF, these fields are returned as `null` (never faked) and only price-per-sqft + deal-signal flags are computed.",
            "default": true
          },
          "downPaymentPercent": {
            "title": "🏦 Down Payment (%)",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "💵 Percentage of the purchase price paid up front. Used to size the mortgage loan amount and the cash-on-cash return denominator. Default 20%.",
            "default": 20
          },
          "interestRatePercent": {
            "title": "📈 Mortgage Interest Rate (% APR)",
            "minimum": 0,
            "maximum": 25,
            "type": "number",
            "description": "🏠 Annual mortgage interest rate used for the amortizing monthly payment calculation. Default 7%.",
            "default": 7
          },
          "loanTermYears": {
            "title": "📆 Loan Term (Years)",
            "minimum": 1,
            "maximum": 40,
            "type": "integer",
            "description": "⏳ Mortgage amortization period in years. Default 30.",
            "default": 30
          },
          "propertyTaxRatePercentAnnual": {
            "title": "🧾 Annual Property Tax Rate (% of Assessed Value)",
            "minimum": 0,
            "maximum": 10,
            "type": "number",
            "description": "🏛️ Applied to the listing's `taxAssessedValue` (falls back to price if unavailable) to estimate annual property tax. Default 1.2% (US national average).",
            "default": 1.2
          },
          "insuranceRatePercentAnnual": {
            "title": "🛡️ Annual Insurance Rate (% of Price)",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "☔ Estimated annual homeowner/landlord insurance cost as a percentage of purchase price. Default 0.35%.",
            "default": 0.35
          },
          "maintenancePercentOfRent": {
            "title": "🔧 Maintenance Reserve (% of Rent)",
            "minimum": 0,
            "maximum": 50,
            "type": "number",
            "description": "🛠️ Reserve for repairs/maintenance as a percentage of gross rent, subtracted in the cash-flow calculation. Default 5%.",
            "default": 5
          },
          "vacancyPercentOfRent": {
            "title": "🛋️ Vacancy Reserve (% of Rent)",
            "minimum": 0,
            "maximum": 50,
            "type": "number",
            "description": "📉 Reserve for vacancy periods as a percentage of gross rent, subtracted in the cash-flow calculation. Default 5%.",
            "default": 5
          },
          "minPriceReductions": {
            "title": "🔻 Minimum Price-Reduction Count (Deal Signal Filter)",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "🚩 Only keep listings with at least this many detected price reductions — a motivated-seller \\\"deal signal\\\". 0 = no filtering (default, keeps every listing). Every kept row also gets a `dealSignal` label combining price-reduction and days-on-Zillow (stale-listing) status.",
            "default": 0
          },
          "proxySetup": {
            "title": "🛡️ Proxy Configuration",
            "type": "object",
            "description": "🌐 Control proxy behavior for reliability.\\n\\n🟢 Default: no proxy\\n🔁 Auto-fallback if blocked: Datacenter → Residential (with 3 retries)\\n\\n(Also accepts the base actor's `proxyConfiguration` key.)"
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}