# HomeFinder Real Estate Scraper (`crawlerbros/homefinder-scraper`) Actor Scrape HomeFinder.com real estate listings - homes for sale, homes for rent, and search by city/state or ZIP code. Get price, beds/baths, sqft, address, coordinates, photos, agent/brokerage contact, and listing URLs. - **URL**: https://apify.com/crawlerbros/homefinder-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Real estate, Automation, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## HomeFinder Real Estate Scraper Scrape real estate listings from [HomeFinder.com](https://www.homefinder.com) — homes for sale and homes for rent across the United States. Search by city + state or by ZIP code. Get price, beds/baths, square footage, lot size, year built, address and coordinates, photos, property type, agent/brokerage contact, and the listing detail URL. No login, no cookies, no proxy required. ### What this actor does - **Two search modes:** `search` (city + state) and `byZip` (5-digit ZIP code) - **For sale or for rent:** every listing is scraped with its actual `for_sale` / `for_rent` status - **Property type filter:** single family, condo, co-op, multi-family, townhome, mobile/manufactured, land, apartment - **Price, bedroom, bathroom, square footage, and lot size filters** - **Sort order:** best match, price low-to-high, price high-to-low, or newest listings first - **Reliable pagination:** paginates using the site's own authoritative listing count, so results aren't silently truncated - **Empty fields are omitted** — every record only contains fields with real data ### Output per listing - `propertyId`, `listingId`, `status`, `transactionType`, `propertyType`, `propertyName` - `listPrice` (or `listPriceMin`/`listPriceMax` for rental unit ranges), `priceReducedAmount` - `beds` / `bedsMin` / `bedsMax`, `bathsConsolidated` / `bathsMin` / `bathsMax` - `sqft` / `sqftMin` / `sqftMax`, `lotSqft`, `yearBuilt`, `garage` - `soldPrice`, `soldDate` (for previously-sold properties) - `address`, `city`, `state`, `stateCode`, `postalCode`, `county`, `latitude`, `longitude` - `primaryPhotoUrl`, `photoUrls[]` (up to 5), `photoCount` - `sourceName`, `sourceType`, `brokerageName`, `agentName`, `agentEmail`, `agentPhone` - `isNewListing`, `isPriceReduced`, `isForeclosure`, `isNewConstruction`, `isPending`, `isContingent`, `isComingSoon`, `isAuction` - `petsAllowedCats`, `petsAllowedDogs`, `hasSpecials`, `applicationUrl` (rentals) - `hasMatterportTour`, `listDate`, `listingUrl` - `recordType: "property"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | select | `search` | `search` (city+state) or `byZip` | | `city` | string | `New York` | City name (mode=search) | | `state` | select | `NY` | 2-letter US state code (mode=search) | | `zipCode` | string | `10001` | 5-digit ZIP code (mode=byZip) | | `transactionType` | select | `for_sale` | `for_sale` or `for_rent` | | `propertyType` | select | `any` | Property type filter | | `priceMin` | int | – | Minimum listing price ($) | | `priceMax` | int | – | Maximum listing price ($) | | `bedroomsMin` | select | `0` (any) | Minimum bedrooms | | `bathroomsMin` | select | `0` (any) | Minimum bathrooms | | `sqftMin` | int | – | Minimum square footage | | `sqftMax` | int | – | Maximum square footage | | `lotSqftMin` | int | – | Minimum lot size in sq ft (for-sale listings only) | | `lotSqftMax` | int | – | Maximum lot size in sq ft (for-sale listings only) | | `sortOrder` | select | `relevance` | `relevance`, `price_asc`, `price_desc`, or `newest` | | `maxItems` | int | `30` | Hard cap on emitted records (1–1000) | #### Example: homes for sale in New York, NY ```json { "mode": "search", "city": "New York", "state": "NY", "transactionType": "for_sale", "maxItems": 50 } ```` #### Example: rentals near a ZIP code, 2+ beds ```json { "mode": "byZip", "zipCode": "10001", "transactionType": "for_rent", "bedroomsMin": "2", "maxItems": 50 } ``` #### Example: condos for sale in a price band ```json { "mode": "search", "city": "Austin", "state": "TX", "transactionType": "for_sale", "propertyType": "condos", "priceMin": 200000, "priceMax": 500000, "maxItems": 100 } ``` #### Example: newest single-family homes, 1,500–2,500 sqft, on a 5,000+ sqft lot ```json { "mode": "search", "city": "Phoenix", "state": "AZ", "transactionType": "for_sale", "propertyType": "single_family", "sqftMin": 1500, "sqftMax": 2500, "lotSqftMin": 5000, "sortOrder": "newest", "maxItems": 50 } ``` ### Use cases - **Real estate market research** — track pricing, inventory, and property mix by city or ZIP - **Relocation & lead gen** — build a searchable database of homes/rentals for a target area - **Investment analysis** — filter by price, beds, baths, and property type across markets - **PropTech data feeds** — power listing search UIs with fresh, structured records - **Rental market tracking** — compare rent ranges and amenities across neighborhoods ### FAQ **Do I need a proxy or login?** No. HomeFinder.com serves listing data via a public, server-rendered Next.js page with no authentication or anti-bot wall observed. **How does pagination work?** Each search page embeds the site's own authoritative total listing count. The actor keeps fetching pages until it has covered that count, hit `maxItems`, or a page returns no new listings — it never silently stops early on a guessed page size. **Why do some rental listings show `listPriceMin`/`listPriceMax` instead of `listPrice`?** Rental communities often list a price range across multiple unit types. When only a range is available, `listPrice` is filled in as the midpoint of the range for easy filtering/sorting, and the original range is preserved. **What if my city/state or ZIP returns 0 results?** The actor sets a clear status message and finishes with an empty dataset rather than erroring — check the run's status message for details. **Does the lot size filter work for rentals?** No — apartment/rental listings on HomeFinder.com don't carry lot size data, so `lotSqftMin`/`lotSqftMax` only take effect when `transactionType` is `for_sale`. **What states/ZIPs are supported?** All 50 US states + DC, and any valid 5-digit US ZIP code. **How fresh is the data?** Listings are served live from HomeFinder.com's search index at scrape time. # Actor input Schema ## `mode` (type: `string`): How to locate listings. ## `city` (type: `string`): City name, e.g. `New York`, `Austin`, `Phoenix`. ## `state` (type: `string`): 2-letter US state code, e.g. `NY`, `TX`, `AZ`. ## `zipCode` (type: `string`): 5-digit US ZIP code, e.g. `10001`. ## `transactionType` (type: `string`): Whether to scrape sale listings or rental listings. ## `propertyType` (type: `string`): Filter to a single property type. Leave as `Any` to include all types. ## `priceMin` (type: `integer`): Drop listings priced below this amount. ## `priceMax` (type: `integer`): Drop listings priced above this amount. ## `bedroomsMin` (type: `string`): Drop listings with fewer bedrooms than this. ## `bathroomsMin` (type: `string`): Drop listings with fewer bathrooms than this. ## `sqftMin` (type: `integer`): Drop listings with fewer square feet than this. ## `sqftMax` (type: `integer`): Drop listings with more square feet than this. ## `lotSqftMin` (type: `integer`): Drop listings with a smaller lot than this. Only applies when Transaction type = For sale (rentals have no lot data). ## `lotSqftMax` (type: `integer`): Drop listings with a larger lot than this. Only applies when Transaction type = For sale (rentals have no lot data). ## `sortOrder` (type: `string`): Order in which HomeFinder returns listings. ## `maxItems` (type: `integer`): Hard cap on emitted records. ## Actor input object example ```json { "mode": "search", "city": "New York", "state": "NY", "zipCode": "10001", "transactionType": "for_sale", "propertyType": "any", "bedroomsMin": "0", "bathroomsMin": "0", "sortOrder": "relevance", "maxItems": 30 } ``` # Actor output Schema ## `listings` (type: `string`): Dataset containing all scraped HomeFinder property listings. # 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 = { "mode": "search", "city": "New York", "state": "NY", "zipCode": "10001", "transactionType": "for_sale", "propertyType": "any", "bedroomsMin": "0", "bathroomsMin": "0", "sortOrder": "relevance", "maxItems": 30 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/homefinder-scraper").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 = { "mode": "search", "city": "New York", "state": "NY", "zipCode": "10001", "transactionType": "for_sale", "propertyType": "any", "bedroomsMin": "0", "bathroomsMin": "0", "sortOrder": "relevance", "maxItems": 30, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/homefinder-scraper").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 '{ "mode": "search", "city": "New York", "state": "NY", "zipCode": "10001", "transactionType": "for_sale", "propertyType": "any", "bedroomsMin": "0", "bathroomsMin": "0", "sortOrder": "relevance", "maxItems": 30 }' | apify call crawlerbros/homefinder-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/homefinder-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "HomeFinder Real Estate Scraper", "description": "Scrape HomeFinder.com real estate listings - homes for sale, homes for rent, and search by city/state or ZIP code. Get price, beds/baths, sqft, address, coordinates, photos, agent/brokerage contact, and listing URLs.", "version": "1.0", "x-build-id": "wf7mVjtBCbFLRAhLr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~homefinder-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-homefinder-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/crawlerbros~homefinder-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-homefinder-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/crawlerbros~homefinder-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-homefinder-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", "required": [ "mode", "transactionType" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "byZip" ], "type": "string", "description": "How to locate listings.", "default": "search" }, "city": { "title": "City (mode=search)", "type": "string", "description": "City name, e.g. `New York`, `Austin`, `Phoenix`.", "default": "New York" }, "state": { "title": "State (mode=search)", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ], "type": "string", "description": "2-letter US state code, e.g. `NY`, `TX`, `AZ`.", "default": "NY" }, "zipCode": { "title": "ZIP code (mode=byZip)", "type": "string", "description": "5-digit US ZIP code, e.g. `10001`.", "default": "10001" }, "transactionType": { "title": "For sale or for rent", "enum": [ "for_sale", "for_rent" ], "type": "string", "description": "Whether to scrape sale listings or rental listings.", "default": "for_sale" }, "propertyType": { "title": "Property type", "enum": [ "any", "single_family", "condos", "coop", "multi_family", "townhomes", "mobile", "land", "apartment" ], "type": "string", "description": "Filter to a single property type. Leave as `Any` to include all types.", "default": "any" }, "priceMin": { "title": "Min price ($)", "minimum": 0, "maximum": 100000000, "type": "integer", "description": "Drop listings priced below this amount." }, "priceMax": { "title": "Max price ($)", "minimum": 0, "maximum": 100000000, "type": "integer", "description": "Drop listings priced above this amount." }, "bedroomsMin": { "title": "Min bedrooms", "enum": [ "0", "1", "2", "3", "4", "5", "6" ], "type": "string", "description": "Drop listings with fewer bedrooms than this.", "default": "0" }, "bathroomsMin": { "title": "Min bathrooms", "enum": [ "0", "1", "2", "3", "4", "5" ], "type": "string", "description": "Drop listings with fewer bathrooms than this.", "default": "0" }, "sqftMin": { "title": "Min square footage", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Drop listings with fewer square feet than this." }, "sqftMax": { "title": "Max square footage", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Drop listings with more square feet than this." }, "lotSqftMin": { "title": "Min lot size (sq ft, for-sale only)", "minimum": 0, "maximum": 5000000, "type": "integer", "description": "Drop listings with a smaller lot than this. Only applies when Transaction type = For sale (rentals have no lot data)." }, "lotSqftMax": { "title": "Max lot size (sq ft, for-sale only)", "minimum": 0, "maximum": 5000000, "type": "integer", "description": "Drop listings with a larger lot than this. Only applies when Transaction type = For sale (rentals have no lot data)." }, "sortOrder": { "title": "Sort order", "enum": [ "relevance", "price_asc", "price_desc", "newest" ], "type": "string", "description": "Order in which HomeFinder returns listings.", "default": "relevance" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on emitted records.", "default": 30 } } }, "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 } } } } } } } } } } ```