{ "openapi": "3.0.1", "info": { "title": "Zillow Search Scraper: Price History Tracking", "description": "Scrape Zillow search results at scale with precise filtering. Extract listings, prices, addresses, home details, photos, and agent data. Ideal for market research, lead generation, pricing analysis, and investment insights. Export clean structured data in JSON, CSV, or Excel.", "version": "0.1", "x-build-id": "oRofIoiBZIsXEWNPv" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scraper-engine~zillow-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scraper-engine-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/scraper-engine~zillow-search-scraper/runs": { "post": { "operationId": "runs-sync-scraper-engine-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/scraper-engine~zillow-search-scraper/run-sync": { "post": { "operationId": "run-sync-scraper-engine-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": { "priceHistorySearchUrls": { "title": "๐Ÿ”Ž Listings To Track (URL / ZIP / City)", "type": "array", "description": "๐Ÿ“ Add one or more Zillow search URLs, ZIP codes, city/location keywords, or full search URLs whose listings you want a price/tax history timeline for.\\n\\nโœ… Supports bulk input.\\nโœ… Full Zillow URLs with `searchQueryState` give the most accurate results.\\n\\n๐Ÿ’ก Examples: `dallas-tx`, `new-york-ny`, a full `zillow.com/...&searchQueryState=...` URL.\\n\\n(Accepts the base actor's `searchUrls` key too, for backward compatibility.)", "items": { "type": "string" } }, "listingScanMode": { "title": "โš™๏ธ Listing Scan Mode", "enum": [ "PAGINATION_WITH_DYNAMIC_ZOOM_INCREASE", "PAGINATION_WITHOUT_ZOOMING_IN", "MAP_MARKERS" ], "type": "string", "description": "๐Ÿง  Choose how the SEARCH results page is paginated (this is independent of the price/tax history fetch below).\\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 around 500 listings per search URL.\\n\\nDefault when left unset: Dynamic zoom. (Accepts the base actor's `extractionMethod` key too.)" }, "maxListingsToTrack": { "title": "๐ŸŽฏ Maximum Listings To Track", "minimum": 1, "maximum": 10000, "type": "integer", "description": "๐Ÿ“ˆ Maximum number of property listings to scrape per search target (1-10000).\\n\\nโš ๏ธ When any history option below is ON, this also caps how many EXTRA detail-page requests are made (1 extra request per kept listing) -- lower this for a quicker/cheaper test run.\\n\\nDefault when left unset: 10. (Accepts the base actor's `maxItems` key too.)" }, "includePriceHistory": { "title": "๐Ÿ’ฒ Include Price-History Timeline", "type": "boolean", "description": "๐Ÿ“Š When ON, fetches each listing's detail page and adds a `priceHistory[]` timeline: every recorded date/event (listed, sold, price change)/price/% change/source. Adds ONE extra request per listing.\\n\\nDefault: OFF (no extra requests, matches the base actor's speed).", "default": false }, "includeTaxHistory": { "title": "๐Ÿงพ Include Tax-Assessment History", "type": "boolean", "description": "๐Ÿ›๏ธ When ON, fetches each listing's detail page and adds a `taxHistory[]` timeline: every recorded assessment year, tax paid, assessed value, and year-over-year value-change %. Adds ONE extra request per listing (shared with the price-history fetch when both are ON -- still just 1 request).\\n\\nDefault: OFF.", "default": false }, "minPriceReductionEvents": { "title": "๐Ÿ“‰ Minimum Price-Drop Events (Motivated-Seller Filter)", "minimum": 0, "type": "integer", "description": "๐ŸŽฏ Keep only listings whose price-history timeline shows AT LEAST this many real price-DROP events (a negative price-change % between two history entries) -- a classic motivated-seller / negotiation-room signal.\\n\\n0 = no filtering (default). Setting this above 0 automatically triggers the detail-page fetch even if 'Include Price-History Timeline' above is left OFF, since the filter needs that same data to evaluate.\\n\\n๐Ÿ’ก Example: minPriceReductionEvents=2 keeps only listings that have been discounted twice or more.", "default": 0 }, "proxyConfiguration": { "title": "๐Ÿ›ก๏ธ Proxy Configuration", "type": "object", "description": "๐ŸŒ Control proxy behavior for reliability.\\n\\n๐ŸŸข Default: no proxy\\n๐Ÿ” Auto-fallback if blocked: Datacenter โ†’ Residential (with retries)\\n\\nโœ… Recommended for larger runs, stricter regions, or when the price/tax history options above are enabled (the detail page carries heavier anti-bot coverage than the search API)." } } }, "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 } } } } } } } } } }