{ "openapi": "3.0.1", "info": { "title": "Realtor Scraper — US Real Estate Listings & Property Data", "description": "Scrape realtor.com — US for-sale · for-rent and recently-sold listings — with price and tax history · schools · flood risk · value estimates (AVM) · mortgage breakdown and agent details. Incremental mode tracks new and changed listings across scheduled runs.", "version": "0.1", "x-build-id": "s7X6QrCA50QwcGS0Y" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/blackfalcondata~realtor-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-blackfalcondata-realtor-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/blackfalcondata~realtor-scraper/runs": { "post": { "operationId": "runs-sync-blackfalcondata-realtor-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/blackfalcondata~realtor-scraper/run-sync": { "post": { "operationId": "run-sync-blackfalcondata-realtor-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": { "searchMode": { "title": "🔁 Search Mode", "enum": [ "for_sale", "for_rent", "sold" ], "type": "string", "description": "Which listings to scrape.", "default": "for_sale" }, "searchLocations": { "title": "📍 Locations", "type": "array", "description": "One or more locations: \"City, ST\" (e.g. \"Austin, TX\"), a ZIP code (e.g. \"78704\"), or a neighborhood. Each is searched independently. Leave empty if you only use Start URLs.", "items": { "type": "string" } }, "startUrls": { "title": "🔗 Start URLs", "type": "array", "description": "Paste realtor.com search-result URLs (e.g. https://www.realtor.com/realestateandhomes-search/Austin_TX) or individual property URLs. Search URLs read their location + mode from the URL; the filters below still apply.", "items": { "type": "string" } }, "keyword": { "title": "🔤 Keyword", "type": "string", "description": "Optional text that must appear in the listing (e.g. \"pool\", \"waterfront\")." }, "maxResults": { "title": "💯 Max Results", "minimum": 0, "type": "integer", "description": "Maximum listings to return (0 = full coverage). Full coverage works even for very large markets.", "default": 100 }, "mode": { "title": "⚙️ Scrape Mode", "enum": [ "listings", "agents" ], "type": "string", "description": "Listings (default) or Agents — scrape the real-estate agent directory (name, broker, office, ratings, sales stats) for a location.", "default": "listings" }, "agentLocations": { "title": "📍 Agent Locations", "type": "array", "description": "Agents mode only: locations to find agents in — \"City, ST\" (e.g. \"Austin, TX\") or a ZIP code. Each is searched independently.", "items": { "type": "string" } }, "agentType": { "title": "🤝 Agent Type", "enum": [ "BUYER", "SELLER" ], "type": "string", "description": "Agents mode: which side the agent represents.", "default": "BUYER" }, "agentLanguages": { "title": "🗣️ Agent Languages", "type": "array", "description": "Agents mode: filter by spoken language (e.g. \"spanish\").", "items": { "type": "string" } }, "enrichAgentContacts": { "title": "📇 Enrich Agent Contacts", "type": "boolean", "description": "Agents mode: fetch each agent's full contact profile — direct & office phone, website, office address, license number, and social media. On by default.", "default": true }, "propertyTypes": { "title": "🏠 Property Types", "type": "array", "description": "Restrict to one or more property types. Leave empty for all types.", "items": { "type": "string", "enum": [ "single_family", "condo", "townhomes", "multi_family", "duplex_triplex", "mobile", "land", "farm" ], "enumTitles": [ "Single family", "Condo", "Townhome", "Multi-family", "Duplex/Triplex", "Mobile", "Land", "Farm" ] }, "default": [] }, "searchStatuses": { "title": "🏷️ Extra Statuses (for-sale only)", "type": "array", "description": "Include additional statuses alongside active for-sale listings.", "items": { "type": "string", "enum": [ "pending", "contingent", "coming_soon" ], "enumTitles": [ "Pending", "Contingent", "Coming soon" ] } }, "priceMin": { "title": "💰 Min Price (USD)", "minimum": 0, "type": "integer", "description": "Minimum listing price." }, "priceMax": { "title": "💰 Max Price (USD)", "minimum": 0, "type": "integer", "description": "Maximum listing price." }, "bedsMin": { "title": "🛏️ Min Bedrooms", "minimum": 0, "type": "integer", "description": "Minimum number of bedrooms." }, "bedsMax": { "title": "🛏️ Max Bedrooms", "minimum": 0, "type": "integer", "description": "Maximum number of bedrooms." }, "bathsMin": { "title": "🛁 Min Bathrooms", "minimum": 0, "type": "integer", "description": "Minimum number of bathrooms." }, "bathsMax": { "title": "🛁 Max Bathrooms", "minimum": 0, "type": "integer", "description": "Maximum number of bathrooms." }, "sqftMin": { "title": "📐 Min Sqft", "minimum": 0, "type": "integer", "description": "Minimum interior square footage." }, "sqftMax": { "title": "📐 Max Sqft", "minimum": 0, "type": "integer", "description": "Maximum interior square footage." }, "lotSqftMin": { "title": "🌳 Min Lot Size (sq ft)", "minimum": 0, "type": "integer", "description": "Minimum lot size in square feet (1 acre = 43,560 sq ft)." }, "lotSqftMax": { "title": "🌳 Max Lot Size (sq ft)", "minimum": 0, "type": "integer", "description": "Maximum lot size in square feet." }, "yearBuiltMin": { "title": "🏗️ Built From (year)", "minimum": 1700, "maximum": 2100, "type": "integer", "description": "Only homes built in or after this year (e.g. 2015)." }, "yearBuiltMax": { "title": "🏗️ Built Until (year)", "minimum": 1700, "maximum": 2100, "type": "integer", "description": "Only homes built in or before this year." }, "hoaFeeMax": { "title": "🏘️ Max HOA Fee ($/month)", "minimum": 0, "type": "integer", "description": "Maximum monthly HOA fee. 0 = only homes with no HOA fee." }, "garageMin": { "title": "🚗 Min Garage Spaces", "minimum": 0, "type": "integer", "description": "Minimum number of garage spaces." }, "listedWithinDays": { "title": "🆕 Listed In The Last (days)", "minimum": 1, "type": "integer", "description": "Only listings first listed within this many days (e.g. 7). Combined with incremental mode, listings that age out of the window are never reported as expired." }, "priceReducedWithinDays": { "title": "📉 Price Reduced In The Last (days)", "minimum": 1, "type": "integer", "description": "Only listings whose price was cut within this many days." }, "soldWithinDays": { "title": "🏷️ Sold In The Last (days)", "minimum": 1, "type": "integer", "description": "Recently sold searches only: only homes sold within this many days." }, "openHouseWithinDays": { "title": "🚪 Open House In The Next (days)", "minimum": 1, "type": "integer", "description": "Only listings with an open house scheduled within this many days from today." }, "pendingListings": { "title": "⏳ Pending Listings", "enum": [ "include", "only", "exclude" ], "type": "string", "description": "Include, show only, or exclude listings marked pending." }, "contingentListings": { "title": "📑 Contingent Listings", "enum": [ "include", "only", "exclude" ], "type": "string", "description": "Include, show only, or exclude listings under contract with contingencies." }, "foreclosures": { "title": "🏚️ Foreclosures", "enum": [ "include", "only", "exclude" ], "type": "string", "description": "Include, show only, or exclude foreclosures." }, "newConstruction": { "title": "🆕 New Construction", "enum": [ "include", "only", "exclude" ], "type": "string", "description": "Include, show only, or exclude new construction." }, "onlyWithVirtualTour": { "title": "🎥 Only With Virtual Tour", "type": "boolean", "description": "Only listings that have a virtual tour." }, "onlyWith3dTour": { "title": "🧊 Only With 3D Tour", "type": "boolean", "description": "Only listings that have a 3D (Matterport) tour." }, "catsAllowed": { "title": "🐈 Cats Allowed", "type": "boolean", "description": "Rentals only: only listings that allow cats." }, "dogsAllowed": { "title": "🐕 Dogs Allowed", "type": "boolean", "description": "Rentals only: only listings that allow dogs." }, "tags": { "title": "✨ Amenity Tags", "type": "array", "description": "Only listings carrying ALL of these tags (e.g. swimming pool, waterfront, single story).", "items": { "type": "string", "enum": [ "swimming_pool", "community_swimming_pool", "spa_or_hot_tub", "garage_1_or_more", "garage_2_or_more", "garage_3_or_more", "carport", "rv_or_boat_parking", "single_story", "two_or_more_stories", "basement", "central_air", "central_heat", "forced_air", "fireplace", "hardwood_floors", "dishwasher", "washer_dryer", "laundry_room", "den_or_office", "home_office", "dining_room", "family_room", "game_room", "media_room", "theater_room", "open_floor_plan", "updated_kitchen", "gourmet_kitchen", "kitchen_island", "walk_in_closet", "walk_in_pantry", "high_ceiling", "vaulted_ceiling", "wet_bar", "wine_cellar", "elevator", "furnished", "smart_homes", "solar_panels", "energy_efficient", "new_roof", "big_yard", "big_lot", "fenced_yard", "corner_lot", "cul_de_sac", "patio", "covered_patio", "balcony", "porch", "outdoor_kitchen", "fire_pit", "view", "city_view", "water_view", "ocean_view", "lake_view", "river_view", "mountain_view", "hill_or_mountain_view", "golf_course_view", "waterfront", "beach", "boat_dock", "marina", "gated_community", "community_security_features", "community_gym", "community_clubhouse", "community_tennis_court", "community_golf", "community_park", "community_outdoor_space", "community_spa_or_hot_tub", "community_elevator", "community_doorman", "community_boat_facilities", "recreation_facilities", "golf_course", "tennis_court", "basketball_court", "playground", "trails", "greenbelt", "horse_stables", "equestrian", "guest_house", "farm", "ranch", "pets_allowed", "disability_features", "senior_community", "fixer_upper", "investment_opportunity", "rental_property", "lease_option", "new_construction", "no_hoa", "low_hoa", "hoa" ], "enumTitles": [ "Swimming pool", "Community swimming pool", "Spa or hot tub", "Garage 1 or more", "Garage 2 or more", "Garage 3 or more", "Carport", "Rv or boat parking", "Single story", "Two or more stories", "Basement", "Central air", "Central heat", "Forced air", "Fireplace", "Hardwood floors", "Dishwasher", "Washer dryer", "Laundry room", "Den or office", "Home office", "Dining room", "Family room", "Game room", "Media room", "Theater room", "Open floor plan", "Updated kitchen", "Gourmet kitchen", "Kitchen island", "Walk in closet", "Walk in pantry", "High ceiling", "Vaulted ceiling", "Wet bar", "Wine cellar", "Elevator", "Furnished", "Smart homes", "Solar panels", "Energy efficient", "New roof", "Big yard", "Big lot", "Fenced yard", "Corner lot", "Cul de sac", "Patio", "Covered patio", "Balcony", "Porch", "Outdoor kitchen", "Fire pit", "View", "City view", "Water view", "Ocean view", "Lake view", "River view", "Mountain view", "Hill or mountain view", "Golf course view", "Waterfront", "Beach", "Boat dock", "Marina", "Gated community", "Community security features", "Community gym", "Community clubhouse", "Community tennis court", "Community golf", "Community park", "Community outdoor space", "Community spa or hot tub", "Community elevator", "Community doorman", "Community boat facilities", "Recreation facilities", "Golf course", "Tennis court", "Basketball court", "Playground", "Trails", "Greenbelt", "Horse stables", "Equestrian", "Guest house", "Farm", "Ranch", "Pets allowed", "Disability features", "Senior community", "Fixer upper", "Investment opportunity", "Rental property", "Lease option", "New construction", "No hoa", "Low hoa", "Hoa" ] } }, "sortBy": { "title": "↕️ Sort By", "enum": [ "newest", "oldest", "price_low", "price_high", "largest_sqft", "smallest_sqft", "most_beds", "largest_lot", "recently_updated", "recently_price_reduced", "recently_sold", "most_photos" ], "type": "string", "description": "Order of the results. Matters most with a Max Results limit: it decides which listings you get." }, "searchRadiusMiles": { "title": "📐 Widen Location By (miles)", "minimum": 1, "maximum": 50, "type": "integer", "description": "Also include listings within this many miles around each location (max 50). For a radius around a map point, use the centre + radius fields below." }, "centerLat": { "title": "🧭 Center Latitude", "type": "number", "description": "Centre latitude in decimal degrees (e.g. 30.2672). With Centre Longitude and Radius it either searches around the point on its own, or narrows each location to the circle." }, "centerLng": { "title": "🧭 Center Longitude", "type": "number", "description": "Centre longitude in decimal degrees (e.g. -97.7431). West of Greenwich is negative, so every US longitude is below zero." }, "radiusKm": { "title": "📏 Radius (km)", "minimum": 0, "type": "integer", "description": "Keep only listings within this many kilometres of the centre point. With centre + radius and no location, the run searches the circle itself." }, "includeDetails": { "title": "📋 Include Detail Enrichment", "type": "boolean", "description": "Fetch each listing's full detail: price history, tax history, schools, flood risk, value estimates (AVM), mortgage breakdown, and full description. On by default. Turn off for faster, cheaper search-only records.", "default": true }, "enrichEmails": { "title": "📧 Discover Contact Emails", "type": "boolean", "description": "Best-effort agent/advertiser email discovery (billed per listing with a match).", "default": false }, "descriptionMaxLength": { "title": "✂️ Description Max Length", "minimum": 0, "type": "integer", "description": "Truncate description to this many characters. 0 = no truncation.", "default": 0 }, "descriptionFormat": { "title": "📝 Description Format", "enum": [ "text", "html", "markdown" ], "type": "string", "description": "Keep one description representation and drop the others to shrink payload.", "default": "text" }, "excludeEmptyFields": { "title": "🧹 Exclude Empty Fields", "type": "boolean", "description": "Drop null / empty-string / empty-array fields from each record.", "default": false }, "compact": { "title": "📦 Compact Output", "type": "boolean", "description": "Output only core comparison fields (for AI-agent / MCP workflows).", "default": false }, "incrementalMode": { "title": "♻️ Incremental Mode", "type": "boolean", "description": "Track new/changed/expired listings across runs. Requires a State Key.", "default": false }, "stateKey": { "title": "🔑 State Key", "type": "string", "description": "Stable identifier for this tracking universe (e.g. \"austin-tx-for-sale\")." }, "emitUnchanged": { "title": "♻️ Emit Unchanged Records", "type": "boolean", "description": "When incremental, also emit listings that have not changed.", "default": false }, "emitExpired": { "title": "⚰️ Emit Expired Records", "type": "boolean", "description": "When incremental, also emit listings no longer found (now off-market). These off-market markers are always included so change tracking stays complete — they are not subject to Max Results.", "default": false }, "skipReposts": { "title": "🚫 Skip Reposts", "type": "boolean", "description": "When incremental, skip listings that are reposts of previously seen (now expired) listings.", "default": false }, "notifyOnlyChanges": { "title": "🔄 Notify Only New/Updated", "type": "boolean", "description": "When Incremental Mode is on, only notify for NEW and UPDATED listings.", "default": false }, "notificationLimit": { "title": "📊 Max Listings Per Notification", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of listings included in each notification message (1–20).", "default": 5 }, "telegramToken": { "title": "🔑 Telegram Bot Token", "type": "string", "description": "Telegram bot token (from @BotFather). Required for Telegram notifications." }, "telegramChatId": { "title": "💬 Telegram Chat ID", "type": "string", "description": "Telegram chat or channel ID where alerts are sent." }, "discordWebhookUrl": { "title": "🎮 Discord Webhook URL", "type": "string", "description": "Discord incoming webhook URL." }, "slackWebhookUrl": { "title": "💼 Slack Webhook URL", "type": "string", "description": "Slack incoming webhook URL." }, "whatsappPhoneNumberId": { "title": "📱 WhatsApp Phone Number ID", "type": "string", "description": "WhatsApp Business phone number ID from Meta Business Manager." }, "whatsappAccessToken": { "title": "🔐 WhatsApp Access Token", "type": "string", "description": "Meta Cloud API access token with whatsapp_business_messaging scope." }, "whatsappTo": { "title": "📨 WhatsApp Recipient", "type": "string", "description": "Recipient phone number in E.164 format (e.g. +14155551234)." }, "webhookUrl": { "title": "🪝 Generic Webhook URL", "type": "string", "description": "Universal escape hatch for n8n / Make / Zapier / custom HTTP backends. Receives a JSON POST per run." }, "webhookHeaders": { "title": "🪝 Webhook Headers (optional)", "type": "object", "description": "Additional HTTP headers sent with the generic webhook POST." }, "appConnector": { "title": "📤 Send results to a connected app", "type": "string", "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results (including contact details where available). A run-summary is written to the connected app; support is best-effort as Apify expands its connector catalog." }, "mcpIssueTeam": { "title": "🏷️ Issue tracker team", "type": "string", "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one." }, "cityName": { "title": "🏙️ City Name", "type": "string", "description": "A US city with its state (e.g. \"Austin, TX\"). Used when Search Locations is empty; same as one Search Locations entry." }, "lat": { "title": "🌐 Latitude", "minimum": -90, "maximum": 90, "type": "number", "description": "Same as Centre Latitude (decimal degrees, e.g. 30.2672). Pair with Longitude and a radius in km." }, "lon": { "title": "🌐 Longitude", "minimum": -180, "maximum": 180, "type": "number", "description": "Same as Centre Longitude (decimal degrees, e.g. -97.7431)." }, "query": { "title": "🔍 Search Term(s)", "type": "string", "description": "Same as Keyword: text that must appear in the listing (e.g. \"pool\"). A JSON array of terms is combined into one keyword search." } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }