{ "openapi": "3.0.1", "info": { "title": "Zillow API | US Real Estate Listings for Sale, Rent & Sold", "description": "A Zillow API for US real estate. Search homes for sale, for rent, and sold by plain city, ZIP, county, or neighborhood, with no region id or search URL to build. Filter for price cuts, sweep a whole metro past the 820-result cap, and get clean JSON. MCP-ready for Claude and AI agents.", "version": "0.0", "x-build-id": "UsCMHkziyxao0mUpP" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~zillow-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-zillow-api", "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/johnvc~zillow-api/runs": { "post": { "operationId": "runs-sync-johnvc-zillow-api", "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/johnvc~zillow-api/run-sync": { "post": { "operationId": "run-sync-johnvc-zillow-api", "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", "required": [ "statusType" ], "properties": { "locations": { "title": "Locations", "maxItems": 25, "type": "array", "description": "Places to search, as plain names. Accepts a city (Austin, TX), a ZIP code (78704), a county (Travis County, TX), a neighborhood (Upper West Side, New York, NY), or a state (TX). A ZIP is resolved to the right place automatically, so you never paste a region id. Add a state to disambiguate common names. Up to 25 locations per run.", "items": { "type": "string" } }, "ambiguityPolicy": { "title": "When a place name is ambiguous", "enum": [ "largest", "error", "all" ], "type": "string", "description": "How to handle a name that matches more than one place, such as 'Springfield'.", "default": "largest" }, "regionId": { "title": "Region ID (advanced)", "type": "string", "description": "Zillow's internal numeric region id, NOT a ZIP code. Pasting a ZIP here silently returns a different city's listings. Use the Locations field instead unless you already hold a verified region id." }, "mapBounds": { "title": "Map bounds (advanced)", "type": "string", "description": "A geographic box as north,east,south,west, for example 30.51,-97.56,30.14,-98.05. Works on its own, or with a region id to restrict a region to part of the map." }, "statusType": { "title": "Listing status", "enum": [ "sale", "rent", "sold" ], "type": "string", "description": "Which market to search.", "default": "sale" }, "homeType": { "title": "Home types", "type": "array", "description": "Property types to include. For sale/sold: house, townhome, multi_family, condo, lot_land, apartment, manufactured. For rent: house, apartment_condo, townhome. Leave empty for all types.", "items": { "type": "string", "enum": [ "house", "townhome", "multi_family", "condo", "lot_land", "apartment", "manufactured", "apartment_condo" ], "enumTitles": [ "House", "Townhome", "Multi-family", "Condo/Co-op", "Lot/Land", "Apartment", "Manufactured", "Apartment/Condo (rent)" ] }, "default": [] }, "listingType": { "title": "Listing type (for sale only)", "type": "array", "description": "Restrict for-sale results by who is selling. Note: foreclosure and pre-foreclosure inventory on the source is very thin.", "items": { "type": "string", "enum": [ "owner", "agent", "new_construction", "foreclosure", "auction", "foreclosed", "pre_foreclosure" ], "enumTitles": [ "By owner (FSBO)", "By agent", "New construction", "Foreclosures", "Auctions", "Foreclosed", "Pre-foreclosures" ] }, "default": [] }, "listingStatus": { "title": "Listing state (for sale only)", "type": "array", "description": "Restrict by listing state.", "items": { "type": "string", "enum": [ "active", "coming_soon", "zillow_preview", "accepting_backup_offers", "pending" ], "enumTitles": [ "Active", "Coming soon", "Zillow preview", "Accepting backup offers", "Pending / under contract" ] }, "default": [] }, "priceMin": { "title": "Price: minimum", "minimum": 0, "type": "integer", "description": "Lowest price (list price for sale/sold, monthly rent for rent)." }, "priceMax": { "title": "Price: maximum", "minimum": 0, "type": "integer", "description": "Highest price." }, "bedsMin": { "title": "Bedrooms: minimum", "minimum": 0, "type": "integer", "description": "Fewest bedrooms." }, "bedsMax": { "title": "Bedrooms: maximum", "minimum": 0, "type": "integer", "description": "Most bedrooms." }, "bathsMin": { "title": "Bathrooms: minimum", "minimum": 0, "type": "integer", "description": "Fewest bathrooms." }, "bathsMax": { "title": "Bathrooms: maximum", "minimum": 0, "type": "integer", "description": "Most bathrooms." }, "sqftMin": { "title": "Square feet: minimum", "minimum": 0, "type": "integer", "description": "Smallest interior area." }, "sqftMax": { "title": "Square feet: maximum", "minimum": 0, "type": "integer", "description": "Largest interior area." }, "yearBuiltMin": { "title": "Year built: from", "minimum": 1800, "type": "integer", "description": "Earliest year built." }, "yearBuiltMax": { "title": "Year built: to", "minimum": 1800, "type": "integer", "description": "Latest year built." }, "lotSizeMin": { "title": "Lot size (sqft): minimum", "minimum": 0, "type": "integer", "description": "Smallest lot in square feet." }, "lotSizeMax": { "title": "Lot size (sqft): maximum", "minimum": 0, "type": "integer", "description": "Largest lot in square feet." }, "hoaMax": { "title": "Max HOA fee (for sale)", "minimum": 0, "type": "integer", "description": "Highest monthly HOA fee. Set 0 for no HOA." }, "parkingSpots": { "title": "Min parking spots (for sale)", "minimum": 0, "type": "integer", "description": "Fewest parking spots." }, "hasGarage": { "title": "Has a garage", "type": "boolean", "description": "Only show properties with a garage.", "default": false }, "singleStory": { "title": "Single story only", "type": "boolean", "description": "Only show single-story properties.", "default": false }, "priceReduction": { "title": "Price reduced only", "type": "boolean", "description": "Only show listings with a recent price cut. The core filter for finding motivated sellers and stale inventory.", "default": false }, "timeOnZillow": { "title": "Max time on market", "type": "string", "description": "Longest a listing has been posted. A number of days (for example 14), or one of 6m, 12m, 24m, 36m." }, "keywords": { "title": "Keywords", "type": "string", "description": "Comma-separated keywords to match in the listing, for example: pool, casita." }, "amenities": { "title": "Amenities", "type": "array", "description": "Required amenities. Options differ by market; common ones: ac, pool, waterfront (for sale); in_unit_laundry, parking, ac, dishwasher, fitness_center (for rent).", "default": [], "items": { "type": "string" } }, "view": { "title": "View", "type": "array", "description": "Required views.", "items": { "type": "string", "enum": [ "city", "mountain", "park", "water" ], "enumTitles": [ "City", "Mountain", "Park", "Water" ] }, "default": [] }, "basement": { "title": "Basement (for sale)", "type": "array", "description": "Required basement type.", "items": { "type": "string", "enum": [ "finished", "unfinished" ], "enumTitles": [ "Finished", "Unfinished" ] }, "default": [] }, "tours": { "title": "Tour options (for sale)", "type": "array", "description": "Required tour options.", "items": { "type": "string", "enum": [ "open_house", "3d_tour", "showcase" ], "enumTitles": [ "Open house", "3D tour", "Showcase" ] }, "default": [] }, "age55Plus": { "title": "55+ communities", "enum": [ "include", "exclude", "only" ], "type": "string", "description": "How to treat 55+ communities.", "default": "include" }, "pets": { "title": "Pets allowed (for rent)", "type": "array", "description": "Required pet policy. 'No pets' cannot be combined with the others.", "items": { "type": "string", "enum": [ "cats", "small_dogs", "large_dogs", "no_pets" ], "enumTitles": [ "Cats", "Small dogs", "Large dogs", "No pets" ] }, "default": [] }, "space": { "title": "Rental space (for rent)", "enum": [ "any", "entire_place", "room" ], "type": "string", "description": "Type of rental space.", "default": "entire_place" }, "moveInDate": { "title": "Latest move-in date (for rent)", "type": "string", "description": "Only show rentals available on or before this date (YYYY-MM-DD)." }, "hideNoDateListings": { "title": "Hide rentals with no date (for rent)", "type": "boolean", "description": "Hide rentals that do not state an availability date. Use with move-in date.", "default": false }, "shortTermLease": { "title": "Short-term lease available (for rent)", "type": "boolean", "description": "Only show rentals offering a short-term lease.", "default": false }, "listingFeatures": { "title": "Rental features (for rent)", "type": "array", "description": "Required rental features.", "items": { "type": "string", "enum": [ "3d_tour", "accepts_applications", "instant_tour" ], "enumTitles": [ "3D tour", "Accepts applications", "Instant tour" ] }, "default": [] }, "maxResults": { "title": "Max results", "minimum": 10, "maximum": 50000, "type": "integer", "description": "The main cost control. Charged per listing returned, with a 10-listing minimum per search: every search fetches at least one full page, so it is billed for at least 10 listings even when fewer (or none) match.", "default": 200 }, "sortBy": { "title": "Sort by", "enum": [ "globalrelevanceex", "days", "priced", "pricea", "beds", "baths", "size", "lot", "featured", "priorityscore" ], "type": "string", "description": "Result ordering. 'Verified source' and 'Recommended' apply to rentals only.", "default": "globalrelevanceex" }, "autoShard": { "title": "Sweep past the 820-result cap", "type": "boolean", "description": "The source returns at most 820 listings per search. Turn this on to split the map into quadrants and cover a whole metro. This multiplies the number of data-source requests, so keep Max results and Max data-source requests as low as your question allows.", "default": false }, "maxUpstreamCalls": { "title": "Max data-source requests", "minimum": 1, "maximum": 200, "type": "integer", "description": "A hard ceiling on how many requests a sharded run may make, independent of Max results. Empty map areas still cost one request each. 200 covers a full metro sweep; the run also stops on its own once new listings stop appearing.", "default": 40 }, "includeImages": { "title": "Include all photo URLs", "type": "boolean", "description": "Include every listing photo URL, not just the thumbnail. This can multiply the dataset size. Photo URLs are links only; images are never rehosted.", "default": false } } }, "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 } } } } } } } } } }