# Realtor.com Search Cheap (Pay-Per-Result) (`kawsar/realtor-search`) Actor Property scraper that extracts Realtor.com listings, prices, and agent details so investors and agents can analyze market data and find deals affordably. - **URL**: https://apify.com/kawsar/realtor-search.md - **Developed by:** [Kawsar](https://apify.com/kawsar) (community) - **Categories:** Real estate, Lead generation, Automation - **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.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. 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.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 ## Realtor.com Scraper — Cheap Property Search API (Pay-Per-Result)

Realtor.com Search Cheap (Pay-Per-Result) — Scrape property listings, sold comps, rental data, agent details from Realtor.com

Scrape property listings from [Realtor.com](https://www.realtor.com/) at a fraction of the cost of the official API. This Apify actor extracts real estate data including active for-sale listings, recently sold properties, rental listings, foreclosures, new construction, agent contact details, open house schedules, listing photos, GPS coordinates, and more. No coding knowledge required. Just fill in the input fields and the actor handles everything — query construction, pagination, proxy rotation, and deduplication. --- ### What Data Can You Scrape from Realtor.com? - **Active for-sale listings** with asking prices, bedroom/bathroom counts, square footage, lot size, and listing dates - **Sold property comps** with final sale prices and close dates for market analysis - **Rental listings** with monthly rent, pet policies, and availability - **Foreclosure and distressed properties** for investment screening - **New construction listings** from builders and developers - **Agent and brokerage details** including names, office names, and fulfillment IDs - **Property photos** including primary listing photo, up to 3 gallery photos, and street view URLs - **GPS coordinates** (latitude/longitude), county name, and FIPS codes - **Open house schedules** with start and end dates - **Listing flags** like coming soon, price reduced, pending, contingent, and more --- ### Use Cases for Realtor.com Data - **Real estate investors**: Pull sold comps by ZIP code, city, or state to run CMA (Comparative Market Analysis) reports - **Real estate agents**: Generate leads by scraping for-sale listings with agent and brokerage contact details - **Property managers**: Monitor rental listings and track rent price trends across neighborhoods - **Market researchers**: Analyze inventory velocity, median prices, and days-on-market across regions - **Wholesalers**: Find foreclosures, contingent deals, and distressed properties before the competition - **Developers**: Track new construction activity and builder listings in target markets - **Data analysts**: Feed structured property data into BI tools, spreadsheets, or data warehouses --- ### Input Parameters — Full Reference #### Search Filters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `status` | array | **Yes** | `["for_sale"]` | Listing status. Options: `for_sale`, `sold`, `for_rent`, `ready_to_build`, `off_market`, `other`, `new_community`. Example: `["for_sale"]` or `["sold"]`. | | `postal_code` | string | No | — | US ZIP code. Most precise location filter. Example: `"90210"` for Beverly Hills. | | `state_code` | string | No | — | 2-letter US state code. Example: `"TX"` for Texas, `"CA"` for California. | | `city` | string | No | — | City name. Combine with `state_code` to avoid ambiguity. Example: `"Houston"`. | | `street_name` | string | No | — | Street name filter. Example: `"Sunset Blvd"`. | | `address` | string | No | — | Specific street address. Example: `"123 Main St"`. | #### Property Filters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `propertyType` | array | — | Property types to include. Options: `single_family`, `condo_townhome`, `condo_townhome_rowhome_coop`, `condo`, `condos`, `apartment`, `multi_family`, `mobile`, `land`, `farm`, `other`. Example: `["single_family", "condo_townhome"]`. | | `keywords` | array | — | Feature/amenity keywords. Options: `pool`, `basement`, `central_air`, `carport`, `den`, `hardwood_floors`, `waterfront`, `ocean_view`, `fireplace`, `garage`. Example: `["pool", "central_air"]`. | | `beds_min` / `beds_max` | integer | — | Bedroom range. Example: `beds_min: 3`, `beds_max: 5`. | | `baths_min` / `baths_max` | integer | — | Bathroom range (includes half-baths). Example: `baths_min: 2`. | | `sqft_min` / `sqft_max` | integer | — | Interior square footage range. Example: `sqft_min: 1500`, `sqft_max: 4000`. | | `lot_sqft_min` / `lot_sqft_max` | integer | — | Lot size range in sq ft. Example: `lot_sqft_min: 5000`. | | `year_built_min` / `year_built_max` | integer | — | Year built range. Example: `year_built_min: 2010`. | #### Price Filters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `list_price_min` / `list_price_max` | integer | — | Active asking price range in USD. Example: `list_price_min: 200000`, `list_price_max: 800000`. | | `sold_price_min` / `sold_price_max` | integer | — | Sold price range in USD. **Only works with `status: ["sold"]`**. Example: `sold_price_max: 500000`. | | `sold_date_min` / `sold_date_max` | string | — | Sold date range (YYYY-MM-DD). Example: `sold_date_min: "2023-01-01"`. | | `hoa_fee_max` | integer | — | Max monthly HOA fee. Example: `hoa_fee_max: 300`. | | `no_hoa_fee` | boolean | `false` | If `true`, only show properties with zero HOA fees. | #### Listing Status Flags | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `pending` | boolean | `false` | If `true`, only return properties currently under contract (pending sale). | | `contingent` | boolean | `false` | If `true`, only return contingent listings (under contract but with conditions that must be met). | | `foreclosure` | boolean | `false` | If `true`, only return properties in active foreclosure proceedings. | | `new_construction` | boolean | `false` | If `true`, only return newly built properties from developers/builders. | #### Media & Tour Filters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `has_tour` | boolean | `false` | If `true`, only return listings that have any type of virtual tour available. | | `matterport` | boolean | `false` | If `true`, only return listings with a Matterport 3D interactive walkthrough. | #### Rental Filters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `cats` | boolean | `false` | If `true`, only rental properties allowing cats. **Use with `status: ["for_rent"]`**. | | `dogs` | boolean | `false` | If `true`, only rental properties allowing dogs. **Use with `status: ["for_rent"]`**. | #### Open House Filters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `open_house_min` / `open_house_max` | string | — | Filter by open house date range (YYYY-MM-DD). Example: `open_house_min: "2024-06-01"`. | #### Sorting | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `sort_field` | string | `list_date` | Sort by: `list_date`, `list_price`, `sold_price`, `sold_date`, `beds`, `lot_sqft`, `photo_count`, `last_update_date`. | | `sort_direction` | string | `desc` | Sort order: `desc` (newest/highest first) or `asc` (oldest/lowest first). | #### Agent & Listing ID Lookups | Parameter | Type | Description | |-----------|------|-------------| | `agent_source_id` | string | Filter by a specific agent's source ID. | | `selling_agent_name` | string | Filter by selling agent's full name. Example: `"John Doe"`. | | `source_listing_id` | string | Look up a specific MLS listing ID. Example: `"12345678"`. | | `property_id` | string | Look up by Realtor.com's internal property ID. Example: `"M12345-67890"`. | | `fulfillment_id` | string | Filter by agent fulfillment ID. | #### Pagination & Limits | Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | `limit` | integer | `200` | `200` | Properties fetched per API call. Realtor.com's maximum is 200. | | `offset` | integer | `0` | — | Starting position index. Use to resume a previous scrape. | | `maxItems` | integer | `5000` | `5000` | Total properties to scrape. The actor stops once this cap is hit. | | `timeoutSecs` | integer | `300` | `3600` | Overall run timeout in seconds. | | `requestTimeoutSecs` | integer | `30` | `120` | Per-request API timeout in seconds. | #### Proxy | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `proxyConfiguration` | object | US Datacenter | Proxy settings. Default uses Apify's US datacenter proxies for reliable US-based requests. | --- ### Example Input — Full Search with All Major Filters This example searches for **active for-sale single-family homes and condos in Houston, TX** with a pool, 3-6 bedrooms, priced $200K-$800K, built after 2005: ```json { "status": ["for_sale"], "state_code": "TX", "city": "Houston", "propertyType": ["single_family", "condo_townhome"], "keywords": ["pool"], "beds_min": 3, "beds_max": 6, "baths_min": 2, "baths_max": 5, "list_price_min": 200000, "list_price_max": 800000, "sqft_min": 1500, "sqft_max": 5000, "lot_sqft_min": 3000, "lot_sqft_max": 30000, "year_built_min": 2005, "year_built_max": 2025, "hoa_fee_max": 400, "foreclosure": false, "new_construction": false, "pending": false, "contingent": false, "has_tour": false, "matterport": false, "sort_field": "list_date", "sort_direction": "desc", "limit": 200, "maxItems": 500, "timeoutSecs": 300, "requestTimeoutSecs": 30, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ```` ### Example Input — Sold Comps in a ZIP Code Pull recently sold properties in Beverly Hills for market analysis: ```json { "status": ["sold"], "postal_code": "90210", "sold_price_min": 500000, "sold_price_max": 3000000, "sold_date_min": "2023-01-01", "propertyType": ["single_family"], "sort_field": "sold_date", "sort_direction": "desc", "maxItems": 200, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ``` ### Example Input — Minimal Quick Search The simplest possible search — just a status and a location: ```json { "status": ["for_sale"], "postal_code": "10022", "maxItems": 100, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ``` ### Example Input — Foreclosures Only Find distressed properties across Florida: ```json { "status": ["for_sale"], "state_code": "FL", "foreclosure": true, "sort_field": "list_price", "sort_direction": "asc", "maxItems": 1000, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ``` ### Example Input — Rentals with Pet Policy Find pet-friendly rentals in Austin: ```json { "status": ["for_rent"], "state_code": "TX", "city": "Austin", "cats": true, "dogs": true, "beds_min": 2, "sort_field": "list_date", "sort_direction": "desc", "maxItems": 500, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ``` *** ### Output — Full Field Reference Each scraped property is pushed as a flat JSON object. Here is the complete output schema with all 40+ fields: ```json { "propertyId": "1234567890", "listingId": "OC22183456", "listPrice": 749000, "soldPrice": null, "soldDate": "", "listingStatus": "for_sale", "propertyName": "", "propertyType": "single_family", "propertySubType": null, "beds": "3", "bathsConsolidated": "2", "sqft": 1850, "lotSqft": 6500, "addressLine": "123 Oak Street", "addressCity": "Irvine", "addressState": "California", "addressStateCode": "CA", "addressPostalCode": "92612", "latitude": 33.684, "longitude": -117.826, "countyName": "Orange", "countyFips": "06059", "permalink": "123-Oak-St_Irvine_CA_92612/M12345-67890", "primaryPhotoUrl": "https://ap.rdcpix.com/...", "photoUrls": ["https://ap.rdcpix.com/..."], "streetViewUrl": "https://maps.googleapis.com/...", "hasMatterport": false, "virtualTours": [], "listDate": "2024-01-15T00:00:00Z", "priceReducedAmount": null, "isComingSoon": false, "isNewListing": true, "isPriceReduced": false, "isForeclosure": false, "isNewConstruction": false, "isPending": false, "isContingent": false, "openHouses": [], "agentName": "Jane Smith", "agentFulfillmentId": "12345", "officeName": "Berkshire Hathaway", "brandingName": "Berkshire Hathaway HomeServices", "brandingPhoto": "https://...", "communityName": "", "communityPermalink": "", "sourceId": "SOCALMLS", "sourceName": "CRMLS", "scrapedAt": "2024-01-20T14:30:00.000000+00:00", "error": null } ``` #### Output Fields Explained | Field | Type | Description | |-------|------|-------------| | `propertyId` | string | Realtor.com's permanent internal property identifier. Unique per property. | | `listingId` | string | The MLS (Multiple Listing Service) ID assigned by the local listing board. | | `listPrice` | integer | Current active asking price in USD. `null` if not listed for sale. | | `soldPrice` | integer | Final sale price in USD. Only populated for sold listings. | | `soldDate` | string | Date the property was sold. Only populated for sold listings. | | `listingStatus` | string | Current lifecycle stage: `for_sale`, `sold`, `for_rent`, `pending`, `contingent`, etc. | | `propertyName` | string | Optional property or community name (common for condos/apartments). | | `propertyType` | string | Classification: `single_family`, `condo_townhome`, `multi_family`, `apartment`, `land`, `farm`, `mobile`. | | `propertySubType` | string | More granular classification when available. | | `beds` | string | Bedroom count (or range like `"2-3"` for multi-unit). | | `bathsConsolidated` | string | Total bathroom count including half-baths. | | `sqft` | integer | Interior living space in square feet. | | `lotSqft` | integer | Total lot/land area in square feet. | | `addressLine` | string | Street address line. | | `addressCity` | string | City name. | | `addressState` | string | Full state name (e.g., `"California"`). | | `addressStateCode` | string | 2-letter state code (e.g., `"CA"`). | | `addressPostalCode` | string | 5-digit ZIP code. | | `latitude` | number | GPS latitude coordinate. | | `longitude` | number | GPS longitude coordinate. | | `countyName` | string | County name. | | `countyFips` | string | Federal FIPS county code (useful for government/census data joins). | | `permalink` | string | Realtor.com URL path to the listing (append to `https://www.realtor.com/`). | | `primaryPhotoUrl` | string | Direct URL to the main listing cover photo. | | `photoUrls` | array | Up to 3 additional listing photo URLs. | | `streetViewUrl` | string | Google Street View URL for the property location. | | `hasMatterport` | boolean | Whether the listing has a Matterport 3D tour. | | `virtualTours` | array | Virtual tour objects with `href` and `type` fields. | | `listDate` | string | ISO date when the property was first listed. | | `priceReducedAmount` | integer | Dollar amount of the most recent price reduction. `null` if no reduction. | | `isComingSoon` | boolean | Listing is in "Coming Soon" pre-market status. | | `isNewListing` | boolean | Listed within the last 14 days. | | `isPriceReduced` | boolean | Price was reduced within the last 30 days. | | `isForeclosure` | boolean | Property is in foreclosure. | | `isNewConstruction` | boolean | Newly built property. | | `isPending` | boolean | Under contract, sale pending. | | `isContingent` | boolean | Under contract with contingencies. | | `openHouses` | array | Scheduled open houses with `start_date` and `end_date`. | | `agentName` | string | Listing or selling agent's full name. | | `agentFulfillmentId` | string | Agent's fulfillment ID for follow-up queries. | | `officeName` | string | Listing brokerage/office name. | | `brandingName` | string | Agent or team branding name. | | `brandingPhoto` | string | Branding logo or photo URL. | | `communityName` | string | Community or development name (for planned communities). | | `communityPermalink` | string | URL path to the community page. | | `sourceId` | string | MLS source system ID (e.g., `"SOCALMLS"`). | | `sourceName` | string | MLS source name (e.g., `"CRMLS"`). | | `scrapedAt` | string | ISO 8601 timestamp of when this record was scraped. | | `error` | string | Error message if this record failed to parse. `null` on success. | *** ### How It Works 1. **Input Normalization**: The actor validates and normalizes your inputs. Array fields like `propertyType` and `keywords` are automatically corrected even if you accidentally pass a comma-separated string instead of an array. 2. **Query Construction**: Your flat input parameters are assembled into a properly structured API request — no manual payload construction needed. 3. **Paginated Extraction**: The actor fetches up to 200 listings per API call and automatically paginates through all available results until your `maxItems` cap is reached or no more data exists. 4. **Smart Early Exit**: If a page returns fewer than 200 results, the actor knows it has reached the end and stops immediately — no wasted requests. 5. **Deduplication**: Every `propertyId` is tracked. If the same property appears across multiple pages (common with Realtor.com's overlapping pagination), duplicates are silently skipped. 6. **Proxy Rotation**: Each page request uses a fresh US datacenter proxy IP to avoid rate limiting and blocking. 7. **Real-time Dataset Push**: Results are pushed to your Apify dataset as they arrive. You can start downloading, exporting, or syncing via API/webhooks before the run completes. *** ### Tips & Best Practices - **Always include a location filter** (`postal_code`, `city` + `state_code`, or `state_code`) alongside `status` to avoid scanning the entire national database. - **Use `maxItems` to control costs**. The default is 5000 but you can lower it to 100 or 500 for quick test runs. - **Don't combine conflicting filters**. For example, `street_name` + `address` + `postal_code` + `city` together will likely return zero results. Pick one or two location filters. - **Boolean flags only activate when set to `true`**. Setting `foreclosure: false` does NOT exclude foreclosures — it simply doesn't apply the filter. Set it to `true` to *only* show foreclosures. - **Sold comps require `status: ["sold"]`**. The `sold_price_min/max` and `sold_date_min/max` filters are ignored unless the status includes `sold`. - **Pet filters are for rentals only**. `cats` and `dogs` only apply when `status` includes `for_rent`. *** ### Frequently Asked Questions **What is the minimum required input?**\ Only `status` is technically required (e.g., `["for_sale"]`). However, you should always add a location filter to avoid impractically broad searches. **How many properties can I scrape per run?**\ Up to 5,000 per run. The actor paginates in batches of 200 (Realtor.com's API maximum) and stops when your `maxItems` cap is reached or when no more data is available. **Can I search for sold properties (comps)?**\ Yes. Set `status` to `["sold"]` and use `sold_price_min`, `sold_price_max`, `sold_date_min`, and `sold_date_max` to narrow the results. **Will I get duplicate properties?**\ No. The actor tracks every `propertyId` it has pushed and automatically skips any duplicate that reappears during pagination. **What proxy settings should I use?**\ The default (US Datacenter) works reliably. Only switch to Residential proxies if you encounter persistent blocks. **Can I pass `propertyType` as a comma-separated string?**\ Yes. The actor automatically normalizes `"single_family, condo"` into `["single_family", "condo"]`. The same applies to `keywords` and `status`. **What happens if the search has fewer results than `maxItems`?**\ The actor collects everything available and stops. You only pay for actual results, not the cap. *** ### Integrations Connect this Realtor.com scraper with other apps and services using [Apify integrations](https://apify.com/integrations): - **Google Sheets** — Auto-populate a spreadsheet with new listings - **Slack** — Get notified when foreclosures or price drops appear - **Make (Integromat)** — Build complex automation workflows - **Zapier** — Connect to 5,000+ apps with zero code - **Airbyte** — Stream property data into your data warehouse - **GitHub** — Trigger scrapes from CI/CD pipelines - **Webhooks** — Get instant HTTP callbacks when results are ready Use the [Apify API](https://docs.apify.com/api/v2) to trigger runs, fetch datasets, and integrate with any programming language. # Actor input Schema ## `status` (type: `array`): Filter properties by their current listing status. Most common options: for\_sale (currently active on the market), sold (past transactions for pulling comps), for\_rent (active rental properties), ready\_to\_build (new construction plans), off\_market (not currently listed), other, new\_community. Example: \['for\_sale', 'ready\_to\_build'] to capture both active listings and upcoming projects. ## `postal_code` (type: `string`): Filter properties exactly by a 5-digit US ZIP or postal code. This is the most reliable way to target a specific neighborhood. Example: '90210' for Beverly Hills, CA. ## `state_code` (type: `string`): Filter properties broadly by a 2-letter US state code. Best used in combination with other filters to prevent pulling too many random properties across the state. Example: 'CA' for California, 'NY' for New York. ## `city` (type: `string`): Filter properties by the exact city name. Usually best to combine with state\_code incase of duplicate city names across states (like Springfield). Example: 'Los Angeles' or 'Austin'. ## `street_name` (type: `string`): Target properties located on a specific street name. Excellent for local market analysis. Example: 'Sunset Blvd' or 'Main St'. ## `address` (type: `string`): Filter for a very specific property address line to find its history or current listing details. Example: '123 Fake Street'. ## `propertyType` (type: `array`): Filter the results by specific property types. Supported options include: apartment, condo\_townhome, condo\_townhome\_rowhome\_coop, condo, condos, single\_family, multi\_family, mobile, land, farm, other. Example: \['single\_family', 'condo'] to find only traditional residential homes. ## `keywords` (type: `array`): Filter properties by specific amenities or descriptive features. Options include: basement, carport, central\_air, den, hardwood\_floors, pool, waterfront, ocean\_view, fireplace. Example: \['pool', 'central\_air'] to find fully-equipped summer homes. ## `beds_min` (type: `integer`): Minimum threshold for the number of bedrooms. Example: 3 to only return properties with 3 or more bedrooms. ## `beds_max` (type: `integer`): Maximum threshold for the number of bedrooms. Example: 5 to exclude mega-mansions. ## `baths_min` (type: `integer`): Minimum threshold for the number of bathrooms (including half-baths). Example: 2 for properties with at least two bathrooms. ## `baths_max` (type: `integer`): Maximum threshold for the number of bathrooms. ## `list_price_min` (type: `integer`): Minimum active asking list price in USD. Example: 200000 to drop properties listed below $200k. ## `list_price_max` (type: `integer`): Maximum active asking list price in USD. Example: 900000 to cap the search at $900k. ## `sold_price_min` (type: `integer`): Minimum sold price in USD. Important: This filter only takes effect when status includes 'sold'. Example: 450000. ## `sold_price_max` (type: `integer`): Maximum sold price in USD. Important: This filter only takes effect when status includes 'sold'. Example: 850000. ## `sold_date_min` (type: `string`): Earliest date the property was sold in YYYY-MM-DD format. Crucial for pulling recent comps. Example: '2023-01-01' to only find sales from 2023 onwards. ## `sold_date_max` (type: `string`): Latest date the property was sold in YYYY-MM-DD format. Example: '2023-12-31'. ## `sqft_min` (type: `integer`): Minimum interior (living space) square footage. Example: 1500. ## `sqft_max` (type: `integer`): Maximum interior (living space) square footage. Example: 4000. ## `lot_sqft_min` (type: `integer`): Minimum exterior lot size in square feet. Example: 5000. ## `lot_sqft_max` (type: `integer`): Maximum exterior lot size in square feet. Example: 15000. ## `year_built_min` (type: `integer`): Filter by the year the construction was completed. Set a minimum year to exclude older homes. Example: 2017 for relatively new buildings. ## `year_built_max` (type: `integer`): Set a maximum year of completion to target historic or older builds. Example: 1980. ## `hoa_fee_max` (type: `integer`): Maximum Homeowners Association monthly fee allowed. Example: 300 to find properties with low or no HOA costs. Note: Has no effect if 'No HOA fee' is checked. ## `no_hoa_fee` (type: `boolean`): Check this box to exclusively show properties that have absolutely no Homeowners Association fee attached. ## `open_house_min` (type: `string`): Filter for properties with scheduled open houses from this date onward (Format: YYYY-MM-DD). Example: '2024-05-01'. ## `open_house_max` (type: `string`): Filter for properties with scheduled open houses up until this date (Format: YYYY-MM-DD). Example: '2024-05-15'. ## `pending` (type: `boolean`): If checked, strictly filter for properties marked as 'Pending' (under contract). ## `contingent` (type: `boolean`): If checked, strictly filter for properties marked as 'Contingent' (under contract but with conditions). ## `foreclosure` (type: `boolean`): If checked, strictly isolate properties that are actively in foreclosure. Outstanding for finding distressed deals. ## `new_construction` (type: `boolean`): If checked, strictly isolate properties labeled as newly constructed. Good for tracking builder developments. ## `has_tour` (type: `boolean`): If checked, only fetch listings that include at least one type of virtual tour media. ## `matterport` (type: `boolean`): If checked, only fetch listings explicitly flagged with a Matterport 3D interactive layout. ## `cats` (type: `boolean`): If checked, strictly filter rental properties to those explicitly allowing cats. ## `dogs` (type: `boolean`): If checked, strictly filter rental properties to those explicitly allowing dogs. ## `sort_field` (type: `string`): Determine the primary field by which Realtor.com sorts the API response. ## `sort_direction` (type: `string`): Determine the sorting sequence: descending (newest/highest first) or ascending (oldest/lowest first). ## `agent_source_id` (type: `string`): Filter all listings tied exclusively to a specific Agent source ID. ## `selling_agent_name` (type: `string`): Filter by the first and last name of the selling agent. Example: 'John Doe'. ## `source_listing_id` (type: `string`): Search for a specific listing using its MLS or source system ID. Example: '12345678'. ## `property_id` (type: `string`): Search directly by the Realtor.com internal property identifier. Example: 'M12345-67890'. ## `fulfillment_id` (type: `string`): Filter listings associated with a specific agent fulfillment ID. ## `limit` (type: `integer`): The number of listings fetched in a single API call. Realtor.com supports up to 200 per page. Default is 200 for maximum throughput. ## `offset` (type: `integer`): The exact positional index the scraper starts at. Useful if a previous run stopped early or if you want to skip the first X records. Set to 0 to start at the beginning. ## `maxItems` (type: `integer`): The hard cap on total listings the scraper will collect across all paginated API calls. The scraper will stop the moment this number is reached. Maximum allowed is 5000. Use this to control costs. Example: 500 stops at exactly 500 properties. ## `timeoutSecs` (type: `integer`): If the scraper surpasses this runtime duration, it will safely halt and exit. Adjust higher for very large list queries. Example: 300 = 5 minutes. ## `requestTimeoutSecs` (type: `integer`): How long the scraper waits for Realtor.com's GraphQL server to respond per API query slice. Example: 30 = 30 seconds wait time. ## `proxyConfiguration` (type: `object`): Select proxies to obscure IP and evade blocking. Note: USA datacenter proxy is set as the default. ## Actor input object example ```json { "status": [ "for_sale", "ready_to_build" ], "postal_code": "90210", "state_code": "CA", "city": "Los Angeles", "propertyType": [ "condo_townhome", "single_family" ], "keywords": [ "basement", "pool" ], "beds_min": 1, "beds_max": 5, "baths_min": 1, "list_price_min": 200000, "list_price_max": 900000, "sold_date_min": "2022-03-25", "sold_date_max": "2022-09-25", "year_built_min": 2017, "year_built_max": 2023, "no_hoa_fee": false, "pending": false, "contingent": false, "foreclosure": false, "new_construction": false, "has_tour": false, "matterport": false, "cats": false, "dogs": false, "sort_field": "list_date", "sort_direction": "desc", "limit": 200, "offset": 0, "maxItems": 5000, "timeoutSecs": 300, "requestTimeoutSecs": 30, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } } ``` # 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 = { "status": [ "for_sale" ], "postal_code": "10022", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } }; // Run the Actor and wait for it to finish const run = await client.actor("kawsar/realtor-search").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 = { "status": ["for_sale"], "postal_code": "10022", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyCountry": "US", }, } # Run the Actor and wait for it to finish run = client.actor("kawsar/realtor-search").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 '{ "status": [ "for_sale" ], "postal_code": "10022", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyCountry": "US" } }' | apify call kawsar/realtor-search --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kawsar/realtor-search", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Realtor.com Search Cheap (Pay-Per-Result)", "description": "Property scraper that extracts Realtor.com listings, prices, and agent details so investors and agents can analyze market data and find deals affordably.", "version": "0.0", "x-build-id": "xLDcDNDjYFLssluUX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kawsar~realtor-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kawsar-realtor-search", "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/kawsar~realtor-search/runs": { "post": { "operationId": "runs-sync-kawsar-realtor-search", "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/kawsar~realtor-search/run-sync": { "post": { "operationId": "run-sync-kawsar-realtor-search", "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": [ "status" ], "properties": { "status": { "title": "Listing status", "type": "array", "description": "Filter properties by their current listing status. Most common options: for_sale (currently active on the market), sold (past transactions for pulling comps), for_rent (active rental properties), ready_to_build (new construction plans), off_market (not currently listed), other, new_community. Example: ['for_sale', 'ready_to_build'] to capture both active listings and upcoming projects.", "items": { "type": "string" } }, "postal_code": { "title": "Postal code", "type": "string", "description": "Filter properties exactly by a 5-digit US ZIP or postal code. This is the most reliable way to target a specific neighborhood. Example: '90210' for Beverly Hills, CA." }, "state_code": { "title": "State code", "type": "string", "description": "Filter properties broadly by a 2-letter US state code. Best used in combination with other filters to prevent pulling too many random properties across the state. Example: 'CA' for California, 'NY' for New York." }, "city": { "title": "City", "type": "string", "description": "Filter properties by the exact city name. Usually best to combine with state_code incase of duplicate city names across states (like Springfield). Example: 'Los Angeles' or 'Austin'." }, "street_name": { "title": "Street name", "type": "string", "description": "Target properties located on a specific street name. Excellent for local market analysis. Example: 'Sunset Blvd' or 'Main St'." }, "address": { "title": "Address", "type": "string", "description": "Filter for a very specific property address line to find its history or current listing details. Example: '123 Fake Street'." }, "propertyType": { "title": "Property type", "type": "array", "description": "Filter the results by specific property types. Supported options include: apartment, condo_townhome, condo_townhome_rowhome_coop, condo, condos, single_family, multi_family, mobile, land, farm, other. Example: ['single_family', 'condo'] to find only traditional residential homes.", "items": { "type": "string" } }, "keywords": { "title": "Feature keywords", "type": "array", "description": "Filter properties by specific amenities or descriptive features. Options include: basement, carport, central_air, den, hardwood_floors, pool, waterfront, ocean_view, fireplace. Example: ['pool', 'central_air'] to find fully-equipped summer homes.", "items": { "type": "string" } }, "beds_min": { "title": "Min bedrooms", "type": "integer", "description": "Minimum threshold for the number of bedrooms. Example: 3 to only return properties with 3 or more bedrooms." }, "beds_max": { "title": "Max bedrooms", "type": "integer", "description": "Maximum threshold for the number of bedrooms. Example: 5 to exclude mega-mansions." }, "baths_min": { "title": "Min bathrooms", "type": "integer", "description": "Minimum threshold for the number of bathrooms (including half-baths). Example: 2 for properties with at least two bathrooms." }, "baths_max": { "title": "Max bathrooms", "type": "integer", "description": "Maximum threshold for the number of bathrooms." }, "list_price_min": { "title": "Min list price", "type": "integer", "description": "Minimum active asking list price in USD. Example: 200000 to drop properties listed below $200k." }, "list_price_max": { "title": "Max list price", "type": "integer", "description": "Maximum active asking list price in USD. Example: 900000 to cap the search at $900k." }, "sold_price_min": { "title": "Min sold price", "type": "integer", "description": "Minimum sold price in USD. Important: This filter only takes effect when status includes 'sold'. Example: 450000." }, "sold_price_max": { "title": "Max sold price", "type": "integer", "description": "Maximum sold price in USD. Important: This filter only takes effect when status includes 'sold'. Example: 850000." }, "sold_date_min": { "title": "Sold date from", "type": "string", "description": "Earliest date the property was sold in YYYY-MM-DD format. Crucial for pulling recent comps. Example: '2023-01-01' to only find sales from 2023 onwards." }, "sold_date_max": { "title": "Sold date to", "type": "string", "description": "Latest date the property was sold in YYYY-MM-DD format. Example: '2023-12-31'." }, "sqft_min": { "title": "Min square feet", "type": "integer", "description": "Minimum interior (living space) square footage. Example: 1500." }, "sqft_max": { "title": "Max square feet", "type": "integer", "description": "Maximum interior (living space) square footage. Example: 4000." }, "lot_sqft_min": { "title": "Min lot square feet", "type": "integer", "description": "Minimum exterior lot size in square feet. Example: 5000." }, "lot_sqft_max": { "title": "Max lot square feet", "type": "integer", "description": "Maximum exterior lot size in square feet. Example: 15000." }, "year_built_min": { "title": "Year built from", "type": "integer", "description": "Filter by the year the construction was completed. Set a minimum year to exclude older homes. Example: 2017 for relatively new buildings." }, "year_built_max": { "title": "Year built to", "type": "integer", "description": "Set a maximum year of completion to target historic or older builds. Example: 1980." }, "hoa_fee_max": { "title": "Max HOA fee", "type": "integer", "description": "Maximum Homeowners Association monthly fee allowed. Example: 300 to find properties with low or no HOA costs. Note: Has no effect if 'No HOA fee' is checked." }, "no_hoa_fee": { "title": "No HOA fee", "type": "boolean", "description": "Check this box to exclusively show properties that have absolutely no Homeowners Association fee attached.", "default": false }, "open_house_min": { "title": "Open house from", "type": "string", "description": "Filter for properties with scheduled open houses from this date onward (Format: YYYY-MM-DD). Example: '2024-05-01'." }, "open_house_max": { "title": "Open house to", "type": "string", "description": "Filter for properties with scheduled open houses up until this date (Format: YYYY-MM-DD). Example: '2024-05-15'." }, "pending": { "title": "Pending status", "type": "boolean", "description": "If checked, strictly filter for properties marked as 'Pending' (under contract).", "default": false }, "contingent": { "title": "Contingent status", "type": "boolean", "description": "If checked, strictly filter for properties marked as 'Contingent' (under contract but with conditions).", "default": false }, "foreclosure": { "title": "Foreclosures only", "type": "boolean", "description": "If checked, strictly isolate properties that are actively in foreclosure. Outstanding for finding distressed deals.", "default": false }, "new_construction": { "title": "New construction only", "type": "boolean", "description": "If checked, strictly isolate properties labeled as newly constructed. Good for tracking builder developments.", "default": false }, "has_tour": { "title": "Has virtual tour", "type": "boolean", "description": "If checked, only fetch listings that include at least one type of virtual tour media.", "default": false }, "matterport": { "title": "Requires Matterport 3D", "type": "boolean", "description": "If checked, only fetch listings explicitly flagged with a Matterport 3D interactive layout.", "default": false }, "cats": { "title": "Cats allowed (Rentals)", "type": "boolean", "description": "If checked, strictly filter rental properties to those explicitly allowing cats.", "default": false }, "dogs": { "title": "Dogs allowed (Rentals)", "type": "boolean", "description": "If checked, strictly filter rental properties to those explicitly allowing dogs.", "default": false }, "sort_field": { "title": "Sort results by", "enum": [ "list_date", "list_price", "sold_price", "sold_date", "beds", "lot_sqft", "photo_count", "last_update_date" ], "type": "string", "description": "Determine the primary field by which Realtor.com sorts the API response.", "default": "list_date" }, "sort_direction": { "title": "Sort direction", "enum": [ "desc", "asc" ], "type": "string", "description": "Determine the sorting sequence: descending (newest/highest first) or ascending (oldest/lowest first).", "default": "desc" }, "agent_source_id": { "title": "Agent source ID", "type": "string", "description": "Filter all listings tied exclusively to a specific Agent source ID." }, "selling_agent_name": { "title": "Selling agent name", "type": "string", "description": "Filter by the first and last name of the selling agent. Example: 'John Doe'." }, "source_listing_id": { "title": "MLS listing ID", "type": "string", "description": "Search for a specific listing using its MLS or source system ID. Example: '12345678'." }, "property_id": { "title": "Property ID", "type": "string", "description": "Search directly by the Realtor.com internal property identifier. Example: 'M12345-67890'." }, "fulfillment_id": { "title": "Fulfillment ID", "type": "string", "description": "Filter listings associated with a specific agent fulfillment ID." }, "limit": { "title": "Results per pagination page", "minimum": 1, "maximum": 200, "type": "integer", "description": "The number of listings fetched in a single API call. Realtor.com supports up to 200 per page. Default is 200 for maximum throughput.", "default": 200 }, "offset": { "title": "Initial page offset", "minimum": 0, "type": "integer", "description": "The exact positional index the scraper starts at. Useful if a previous run stopped early or if you want to skip the first X records. Set to 0 to start at the beginning.", "default": 0 }, "maxItems": { "title": "Maximum total results to scrape", "minimum": 1, "maximum": 5000, "type": "integer", "description": "The hard cap on total listings the scraper will collect across all paginated API calls. The scraper will stop the moment this number is reached. Maximum allowed is 5000. Use this to control costs. Example: 500 stops at exactly 500 properties.", "default": 5000 }, "timeoutSecs": { "title": "Overall actor timeout (seconds)", "minimum": 30, "maximum": 3600, "type": "integer", "description": "If the scraper surpasses this runtime duration, it will safely halt and exit. Adjust higher for very large list queries. Example: 300 = 5 minutes.", "default": 300 }, "requestTimeoutSecs": { "title": "Per-request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "How long the scraper waits for Realtor.com's GraphQL server to respond per API query slice. Example: 30 = 30 seconds wait time.", "default": 30 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Select proxies to obscure IP and evade blocking. Note: USA datacenter proxy is set as the default." } } }, "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 } } } } } } } } } } ```