# US Real Estate Lead Finder (`moving_beacon-owner1/us-real-estate-lead-finder`) Actor An Apify actor that finds leads, not just listings, across the US real estate market. Built on top of HomeHarvest (Realtor.com data), it scores every record on a 0–100 lead-quality scale, tags motivated-seller signals, and extracts full agent contact info for outreach. - **URL**: https://apify.com/moving\_beacon-owner1/us-real-estate-lead-finder.md - **Developed by:** [Jamshaid Arif](https://apify.com/moving_beacon-owner1) (community) - **Categories:** Lead generation, Real estate, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## US Real Estate Lead Finder An Apify actor that finds **leads**, not just listings, across the US real estate market. Built on top of [HomeHarvest](https://github.com/Bunsly/HomeHarvest) (Realtor.com data), it scores every record on a 0–100 lead-quality scale, tags motivated-seller signals, and extracts full agent contact info for outreach. ### What makes it a lead finder (not just a scraper) Each record is enriched with: | Field | What it tells you | |---|---| | `lead_score` | 0–100 composite score (baseline 50) | | `lead_tags` | One or more category labels (see below) | | `motivated_seller` | Boolean — does this record carry strong sell-pressure signals? | | `lead_summary` | Human-readable concatenation of tags | | `full_address` | Pre-built single-string address | | `agent_name`, `agent_phones`, `agent_email` | Direct outreach contact | | `broker_name`, `office_name`, `office_phones` | Brokerage info | #### Lead categories | Tag | Trigger | |---|---| | `FORECLOSURE` | Status contains foreclosure / REO / bank-owned / auction | | `HIGH_DOM_60` / `90` / `180` | Days on market ≥ 60 / 90 / 180 | | `PRICE_REDUCED` | Current list price < historical max by more than 2% | | `EXPIRED` | Status is expired / withdrawn / cancelled | | `PENDING` | Pending / contingent / under contract — buyer-side lead | | `SOLD` | Recently closed — buyer-follow-up lead | | `NEW_CONSTRUCTION` | Builder-direct opportunity | | `HIGH_VALUE` | List or sold price ≥ $1M | | `HAS_AGENT_CONTACT` | Record has agent name/phone/email (actionable) | #### Scoring weights (baseline 50) ```` FORECLOSURE +30 HIGH\_DOM\_180 +25 EXPIRED +25 HIGH\_DOM\_90 +20 PRICE\_REDUCED +20 PENDING +15 HIGH\_DOM\_60 +10 SOLD +10 NEW\_CONSTRUCTION +5 HIGH\_VALUE +5 HAS\_AGENT\_CONTACT +5 capped at 100 ```` ### Inputs (see `.actor/input_schema.json` for the full schema) The interesting ones for lead-finding: - `locations` (required) — array of cities, zips, or full addresses - `listing_type` — `for_sale`, `for_rent`, `sold`, `pending` - `foreclosure_only` — narrow to foreclosure / REO only - `mls_only` — exclude off-market / Zestimate-only records - `require_agent_contact` — drop leads without agent contact - `motivated_sellers_only` — only keep leads with a motivation tag - `min_lead_score` — threshold 0–100 - `require_lead_tags` — must have at least one of the chosen tags - `min_days_on_market` — stale-listing search (try 60, 90, 180) - `past_days` / `date_from` / `date_to` — time window ### Example runs **Motivated sellers in Phoenix (90+ DOM, agent contact required)** ```json { "locations": ["Phoenix, AZ"], "listing_type": "for_sale", "min_days_on_market": 90, "require_agent_contact": true, "motivated_sellers_only": true, "output_format": "leads_only" } ```` **Foreclosure leads across multiple Texas metros** ```json { "locations": ["Houston, TX", "Dallas, TX", "Austin, TX", "San Antonio, TX"], "listing_type": "for_sale", "foreclosure_only": true, "min_lead_score": 70 } ``` **Luxury listings sitting on the market in California** ```json { "locations": ["Beverly Hills, CA", "Malibu, CA", "Newport Beach, CA"], "listing_type": "for_sale", "min_price": 2000000, "min_days_on_market": 60, "require_lead_tags": ["HIGH_DOM_90", "HIGH_DOM_180", "PRICE_REDUCED"] } ``` **Recently sold homes near a specific address (buyer-follow-up leads, 5-mile radius)** ```json { "locations": ["1600 Amphitheatre Parkway, Mountain View, CA"], "listing_type": "sold", "radius": 5, "past_days": 30, "output_format": "leads_only" } ``` ### Output Each dataset record contains either every HomeHarvest column (`output_format: full`) or a focused subset (`output_format: leads_only`), plus the lead-finder enrichment fields above. The actor also writes a `SUMMARY` key in the key-value store with totals, tag distribution, applied filters, and any errors. A pre-built dataset view called **Lead Overview** shows the most important columns (score, tags, address, price, DOM, agent) as a sortable table. # Actor input Schema ## `locations` (type: `array`): US locations to search. Accepts cities ('Austin, TX'), zip codes ('78704'), counties, or full addresses (enables the radius search). ## `listing_type` (type: `string`): Which type of listing to fetch. ## `property_type` (type: `array`): Restrict to these property types. Leave empty for all. ## `past_days` (type: `integer`): Look back this many days from today. Ignored if date\_from is set. ## `date_from` (type: `string`): YYYY-MM-DD. Takes priority over past\_days when set. ## `date_to` (type: `string`): YYYY-MM-DD. Used together with date\_from. ## `radius` (type: `integer`): Search radius around an address. Only effective when location is a full street address. ## `foreclosure_only` (type: `boolean`): If true, only fetch foreclosure / REO / bank-owned listings. ## `mls_only` (type: `boolean`): If true, only return properties with a valid MLS ID (excludes off-market). ## `require_agent_contact` (type: `boolean`): Drop leads with no agent name/phone/email. ## `motivated_sellers_only` (type: `boolean`): Keep only leads flagged as motivated (foreclosure, high DOM, price-reduced, expired). ## `min_lead_score` (type: `integer`): 0–100. Filters out anything below this score. ## `require_lead_tags` (type: `array`): Listing must have AT LEAST ONE of these tags (OR logic). ## `min_price` (type: `integer`): Filter out listings below this price. 0 = no minimum. ## `max_price` (type: `integer`): Filter out listings above this price. 0 = no maximum. ## `min_beds` (type: `integer`): Minimum number of bedrooms. 0 = no minimum. ## `min_baths` (type: `integer`): Minimum number of full bathrooms. 0 = no minimum. ## `min_sqft` (type: `integer`): Minimum interior square footage. 0 = no minimum. ## `min_days_on_market` (type: `integer`): Use 60 / 90 / 180 to surface stale listings. ## `max_days_on_market` (type: `integer`): Drop listings older than this many days on market. 0 = no maximum. ## `max_results_per_location` (type: `integer`): Cap leads pushed per location. 0 = unlimited. ## `output_format` (type: `string`): 'full' returns every HomeHarvest column; 'leads\_only' returns a focused outreach-ready subset. ## Actor input object example ```json { "locations": [ "Austin, TX", "Phoenix, AZ" ], "listing_type": "for_sale", "property_type": [], "past_days": 30, "date_from": "", "date_to": "", "radius": 0, "foreclosure_only": false, "mls_only": false, "require_agent_contact": false, "motivated_sellers_only": false, "min_lead_score": 0, "require_lead_tags": [], "min_price": 0, "max_price": 0, "min_beds": 0, "min_baths": 0, "min_sqft": 0, "min_days_on_market": 0, "max_days_on_market": 0, "max_results_per_location": 0, "output_format": "full" } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "locations": [ "Austin, TX", "Phoenix, AZ" ] }; // Run the Actor and wait for it to finish const run = await client.actor("moving_beacon-owner1/us-real-estate-lead-finder").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "locations": [ "Austin, TX", "Phoenix, AZ", ] } # Run the Actor and wait for it to finish run = client.actor("moving_beacon-owner1/us-real-estate-lead-finder").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "locations": [ "Austin, TX", "Phoenix, AZ" ] }' | apify call moving_beacon-owner1/us-real-estate-lead-finder --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=moving_beacon-owner1/us-real-estate-lead-finder", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "US Real Estate Lead Finder", "description": "An Apify actor that finds leads, not just listings, across the US real estate market. Built on top of HomeHarvest (Realtor.com data), it scores every record on a 0–100 lead-quality scale, tags motivated-seller signals, and extracts full agent contact info for outreach.", "version": "0.0", "x-build-id": "8oiwWph8vMDaEABON" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/moving_beacon-owner1~us-real-estate-lead-finder/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-moving_beacon-owner1-us-real-estate-lead-finder", "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/moving_beacon-owner1~us-real-estate-lead-finder/runs": { "post": { "operationId": "runs-sync-moving_beacon-owner1-us-real-estate-lead-finder", "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/moving_beacon-owner1~us-real-estate-lead-finder/run-sync": { "post": { "operationId": "run-sync-moving_beacon-owner1-us-real-estate-lead-finder", "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": [ "locations" ], "properties": { "locations": { "title": "Locations", "type": "array", "description": "US locations to search. Accepts cities ('Austin, TX'), zip codes ('78704'), counties, or full addresses (enables the radius search).", "default": [ "Austin, TX" ], "items": { "type": "string" } }, "listing_type": { "title": "Listing type", "enum": [ "for_sale", "for_rent", "sold", "pending" ], "type": "string", "description": "Which type of listing to fetch.", "default": "for_sale" }, "property_type": { "title": "Property types", "uniqueItems": true, "type": "array", "description": "Restrict to these property types. Leave empty for all.", "items": { "type": "string", "enum": [ "single_family", "multi_family", "condos", "condo_townhome", "condo_townhome_rowhome_coop", "townhomes", "duplex_triplex", "farm", "land", "mobile" ] }, "default": [] }, "past_days": { "title": "Past days", "minimum": 0, "maximum": 365, "type": "integer", "description": "Look back this many days from today. Ignored if date_from is set.", "default": 30 }, "date_from": { "title": "Date from (overrides past_days)", "type": "string", "description": "YYYY-MM-DD. Takes priority over past_days when set.", "default": "" }, "date_to": { "title": "Date to", "type": "string", "description": "YYYY-MM-DD. Used together with date_from.", "default": "" }, "radius": { "title": "Radius (miles)", "minimum": 0, "maximum": 50, "type": "integer", "description": "Search radius around an address. Only effective when location is a full street address.", "default": 0 }, "foreclosure_only": { "title": "Foreclosures only", "type": "boolean", "description": "If true, only fetch foreclosure / REO / bank-owned listings.", "default": false }, "mls_only": { "title": "MLS-listed only", "type": "boolean", "description": "If true, only return properties with a valid MLS ID (excludes off-market).", "default": false }, "require_agent_contact": { "title": "Require agent contact", "type": "boolean", "description": "Drop leads with no agent name/phone/email.", "default": false }, "motivated_sellers_only": { "title": "Motivated sellers only", "type": "boolean", "description": "Keep only leads flagged as motivated (foreclosure, high DOM, price-reduced, expired).", "default": false }, "min_lead_score": { "title": "Minimum lead score", "minimum": 0, "maximum": 100, "type": "integer", "description": "0–100. Filters out anything below this score.", "default": 0 }, "require_lead_tags": { "title": "Required lead tags", "uniqueItems": true, "type": "array", "description": "Listing must have AT LEAST ONE of these tags (OR logic).", "items": { "type": "string", "enum": [ "FORECLOSURE", "HIGH_DOM_60", "HIGH_DOM_90", "HIGH_DOM_180", "PRICE_REDUCED", "EXPIRED", "PENDING", "SOLD", "NEW_CONSTRUCTION", "HIGH_VALUE", "HAS_AGENT_CONTACT" ] }, "default": [] }, "min_price": { "title": "Min price (USD)", "minimum": 0, "type": "integer", "description": "Filter out listings below this price. 0 = no minimum.", "default": 0 }, "max_price": { "title": "Max price (USD)", "minimum": 0, "type": "integer", "description": "Filter out listings above this price. 0 = no maximum.", "default": 0 }, "min_beds": { "title": "Min bedrooms", "minimum": 0, "type": "integer", "description": "Minimum number of bedrooms. 0 = no minimum.", "default": 0 }, "min_baths": { "title": "Min bathrooms", "minimum": 0, "type": "integer", "description": "Minimum number of full bathrooms. 0 = no minimum.", "default": 0 }, "min_sqft": { "title": "Min square feet", "minimum": 0, "type": "integer", "description": "Minimum interior square footage. 0 = no minimum.", "default": 0 }, "min_days_on_market": { "title": "Min days on market", "minimum": 0, "type": "integer", "description": "Use 60 / 90 / 180 to surface stale listings.", "default": 0 }, "max_days_on_market": { "title": "Max days on market", "minimum": 0, "type": "integer", "description": "Drop listings older than this many days on market. 0 = no maximum.", "default": 0 }, "max_results_per_location": { "title": "Max results per location", "minimum": 0, "type": "integer", "description": "Cap leads pushed per location. 0 = unlimited.", "default": 0 }, "output_format": { "title": "Output format", "enum": [ "full", "leads_only" ], "type": "string", "description": "'full' returns every HomeHarvest column; 'leads_only' returns a focused outreach-ready subset.", "default": "full" } } }, "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 } } } } } } } } } } ```