# Realtor.com US Property Listings Scraper (`datascraperes/realtor-property-search`) Actor

Search Realtor.com property listings across the United States by city, state, or ZIP. Get homes for sale, rent, or sold with prices, beds, baths, photos, location data, optional property details, and listing history.

- **URL**: https://apify.com/datascraperes/realtor-property-search.md
- **Developed by:** [DataScraperES](https://apify.com/datascraperes) (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

$1.00 / 1,000 property 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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

Search **Realtor.com property listings in the United States** by city, state, or ZIP code. Get structured data for homes for sale, rentals, and recently sold properties, then download the results from your Apify Dataset in JSON, CSV, Excel, or other available formats.

This Actor is designed for market research, comparable-sales research, property inventory analysis, acquisition research, and real-estate data workflows. No programming is required: configure the fields in the **Input** tab, run the Actor, and open the Dataset when it finishes.

> **Unofficial tool:** This Actor is not affiliated with, endorsed by, or sponsored by Realtor.com.

### What this Realtor.com property scraper can do

- Search listings in one or many US cities, states, or ZIP codes.
- Include homes that are `for_sale`, `for_rent`, or `sold`.
- Filter results by price, minimum bedrooms, minimum bathrooms, and property type.
- Collect listing price, address, beds, baths, square footage, property type, photos, listing URL, status, and more.
- Optionally enrich each property with additional property details and available listing or tax history.
- Set a limit for each location and another limit for the entire run, so the collection stays within your intended scope.

### Quick start

1. Open the **Input** tab.
2. In **Locations**, click **Add location** and fill in city and state, a ZIP code, or a state code.
3. Choose the listing status, filters, and result limits you need.
4. Click **Start**.
5. When the run completes, open the **Dataset** to inspect or download the property records.

For a first run, use one city or ZIP code and a small `maxTotalResults` value. This lets you verify that the selected filters return the type of inventory you expect before collecting a larger market.

### Search locations

Use the **Locations** form to add one or more search areas. Each added location has separate **City**, **State code**, and **ZIP code** fields, so no JSON is needed. Fill in city and state together, a ZIP code, or only a state code; leave unused fields blank. Each location must include either a US state code or a ZIP code.

| Search area | Example |
| --- | --- |
| City and state | `{"city": "Austin", "stateCode": "TX"}` |
| ZIP code | `{"postalCode": "10026"}` |
| Entire state | `{"stateCode": "CA"}` |

Use the two-letter US state abbreviation, such as `TX`, `CA`, or `NY`. ZIP codes can use five digits or ZIP+4 format.

### Input options

| Field | What it controls | Default / allowed values |
| --- | --- | --- |
| `locations` | Where to search. Add one or more city/state, state, or ZIP objects. | Required; up to 1,000 locations. |
| `listingStatuses` | Which listing markets to include. | `for_sale` by default. Also `for_rent` and `sold`. |
| `minPrice` / `maxPrice` | Listing price range. | Optional, in USD. |
| `minBeds` / `minBaths` | Minimum number of bedrooms or bathrooms. | Optional. Decimals are supported for baths. |
| `propertyTypes` | Restrict the search to property types. | Optional list, for example `single_family` or `condo`. |
| `maxResultsPerLocation` | Maximum unique properties returned from each individual location. | 100 by default; from 1 to 10,000. |
| `maxTotalResults` | Hard maximum number of unique properties for the whole run, across every location. | 1,000 by default; from 1 to 10,000. |
| `outputMode` | Amount of listing data included in each result. | `full` by default. Choose `compact`, `standard`, or `full`. |
| `fetchDetails` | Adds available property-detail data to every returned listing. | `false` by default. |
| `fetchHistory` | Adds available listing-event and tax history. It also includes property details. | `false` by default. |
| `requestDelaySeconds` | Optional pause between pages of a large search. | 0.2 seconds by default; from 0 to 10. |

#### Example input: homes for sale in Austin

This example searches Austin, Texas for single-family homes and condos priced from $500,000 to $800,000, with at least three bedrooms and two bathrooms. It returns at most 100 properties from Austin and never more than 100 properties for the run.

```json
{
  "locations": [
    {
      "city": "Austin",
      "stateCode": "TX"
    }
  ],
  "listingStatuses": [
    "for_sale"
  ],
  "minPrice": 500000,
  "maxPrice": 800000,
  "minBeds": 3,
  "minBaths": 2,
  "propertyTypes": [
    "single_family",
    "condo"
  ],
  "maxResultsPerLocation": 100,
  "maxTotalResults": 100,
  "outputMode": "full",
  "fetchDetails": true,
  "fetchHistory": true
}
```

#### Example input: multiple ZIP codes and rental listings

Use several location objects to compare inventory across areas. The `maxTotalResults` limit applies to all of them combined, not to each ZIP code separately.

```json
{
  "locations": [
    { "postalCode": "10026" },
    { "postalCode": "10027" },
    { "postalCode": "10030" }
  ],
  "listingStatuses": [
    "for_rent"
  ],
  "minBeds": 1,
  "maxResultsPerLocation": 50,
  "maxTotalResults": 120,
  "outputMode": "standard"
}
```

### Choosing an output mode

| Mode | Best for | Included data |
| --- | --- | --- |
| `compact` | Quick inventory checks and small exports. | Property and listing IDs, status, listing URL, price, date, address, beds, baths, size, type, subtype, and year built. |
| `standard` | Market comparison and pricing analysis. | Everything in `compact`, plus price ranges and reductions, last update date, listing source, flags, and tags. |
| `full` | Detailed property research and richer exports. | Everything in `standard`, plus complete location and description data, photos, branding, and open-house information when available. |

Turn on `fetchDetails` when you need an additional detail record for each property. Turn on `fetchHistory` when you also want available listing events and tax history. These fields depend on the information available for each individual property, so they can be absent or incomplete for some listings.

### What data does each result contain?

Each Dataset item represents one unique property. Field availability varies by listing, market, and the selected output mode.

| Data group | Example fields |
| --- | --- |
| Listing identity | `property_id`, `listing_id`, `status`, `permalink` |
| Price and dates | `list_price`, `list_date`, `last_update_date`, price range, price reduction |
| Address and geography | Street address, city, state, ZIP code, county, and coordinates when available |
| Property features | Beds, baths, square footage, lot size, garage, stories, property type, subtype, year built, and description |
| Listing context | Source, tags, listing flags, open houses, and branding when available |
| Media | Photo URLs in `full` mode when available |
| Optional enrichment | `detail`, including available primary photo, property history, and tax history when selected |
| Search context | The location and listing statuses that produced the record |

#### Example output

This is a simplified `full` result with property details and history enabled. Actual values and optional fields vary by listing.

```json
{
  "property_id": "4995062716",
  "listing_id": "2998848624",
  "status": "for_sale",
  "permalink": "https://www.realtor.com/realestateandhomes-detail/example-property",
  "list_price": 659990,
  "list_date": "2026-07-20T00:00:00Z",
  "location": {
    "address": {
      "line": "123 Example Street",
      "city": "Miller Place",
      "state_code": "NY",
      "postal_code": "11764",
      "coordinate": {
        "lat": 40.959,
        "lon": -72.997
      }
    }
  },
  "description": {
    "beds": 3,
    "baths": 2,
    "sqft": 1810,
    "type": "single_family",
    "year_built": 1988
  },
  "photos": [
    {
      "href": "https://example.com/property-photo.jpg"
    }
  ],
  "detail": {
    "property_id": "4995062716",
    "primary_photo": {
      "href": "https://example.com/property-primary-photo.jpg"
    },
    "property_history": [
      {
        "date": "2026-07-20",
        "event_name": "Listed",
        "price": 659990
      }
    ],
    "tax_history": [
      {
        "year": 2025,
        "tax": 8420
      }
    ]
  },
  "search_context": {
    "location": {
      "city": "Miller Place",
      "stateCode": "NY"
    },
    "statuses": [
      "for_sale"
    ]
  }
}
```

### Results, limits, and pricing

The Actor charges **$1 per 1,000 saved property results** ($0.001 per saved property). You are charged only for unique properties saved to the Dataset. Empty searches, duplicate properties, and properties whose optional enrichment is unavailable do not create additional result charges.

Use `maxTotalResults` to set the largest number of properties you want from the run. For example, a `maxTotalResults` value of 1,000 caps the Actor at 1,000 saved properties, which corresponds to a maximum result charge of $1.00. You can also set Apify's **maximum charge per run** before starting when you want an additional billing cap.

`maxResultsPerLocation` and `maxTotalResults` work together:

- `maxResultsPerLocation` limits each city, state, or ZIP code.
- `maxTotalResults` limits the combined output from all locations.
- The Actor stops collecting new properties once either applicable limit is reached.

### Tips for useful property research

- Start with a ZIP code when you need a focused neighborhood sample.
- Use city plus state for a broader local inventory view.
- Use `sold` listings for comparable-sales research; availability may differ by market.
- Keep `outputMode` on `compact` or `standard` for lightweight price and inventory analysis; choose `full` when you need photos, open houses, or richer property context.
- Enable property details and history only when those fields are needed for the analysis.
- For large multi-location research, run a small test first to validate filters and estimate the expected volume.

### Data availability and responsible use

Listing data changes frequently and some fields are not available for every property. A property can have no photos, history, open houses, coordinates, or optional detail data. Use the exported data responsibly and make sure your intended use complies with applicable terms, laws, and privacy requirements.

# Actor input Schema

## `locations` (type: `array`):

Add each search area as a simple form. Enter city and state together, a ZIP code, or only a state code. Leave unused fields blank.

## `listingStatuses` (type: `array`):

Choose purchase, rental, or recently sold properties.

## `minPrice` (type: `integer`):

Lowest listing price to include.

## `maxPrice` (type: `integer`):

Highest listing price to include.

## `minBeds` (type: `number`):

Minimum bedroom count.

## `minBaths` (type: `number`):

Minimum bathroom count.

## `propertyTypes` (type: `array`):

Optional Realtor property-type values, for example single\_family.

## `maxResultsPerLocation` (type: `integer`):

Stop after this many unique properties for each location.

## `maxTotalResults` (type: `integer`):

Hard run-wide result limit across all locations. Apify's maximum charge per run can impose a lower billing limit.

## `outputMode` (type: `string`):

Choose compact, standard, or the richest listing record.

## `fetchDetails` (type: `boolean`):

Add a detail lookup for every returned property.

## `fetchHistory` (type: `boolean`):

Add listing event history for every returned property. Automatically enables property details.

## `requestDelaySeconds` (type: `number`):

Pause between paginated search requests.

## Actor input object example

```json
{
  "locations": [
    {
      "city": "Austin",
      "stateCode": "TX"
    }
  ],
  "listingStatuses": [
    "for_sale"
  ],
  "maxResultsPerLocation": 10,
  "maxTotalResults": 20,
  "outputMode": "full",
  "fetchDetails": false,
  "fetchHistory": false,
  "requestDelaySeconds": 0.2
}
```

# Actor output Schema

## `results` (type: `string`):

Properties saved by the run.

## `summary` (type: `string`):

Aggregate progress, failure, billing, and transport metrics.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "locations": [
        {
            "city": "Austin",
            "stateCode": "TX"
        }
    ],
    "listingStatuses": [
        "for_sale"
    ],
    "maxResultsPerLocation": 10,
    "maxTotalResults": 20,
    "outputMode": "full"
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascraperes/realtor-property-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "locations": [{
            "city": "Austin",
            "stateCode": "TX",
        }],
    "listingStatuses": ["for_sale"],
    "maxResultsPerLocation": 10,
    "maxTotalResults": 20,
    "outputMode": "full",
}

# Run the Actor and wait for it to finish
run = client.actor("datascraperes/realtor-property-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 '{
  "locations": [
    {
      "city": "Austin",
      "stateCode": "TX"
    }
  ],
  "listingStatuses": [
    "for_sale"
  ],
  "maxResultsPerLocation": 10,
  "maxTotalResults": 20,
  "outputMode": "full"
}' |
apify call datascraperes/realtor-property-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datascraperes/realtor-property-search",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/UQrXuMMWkLKBiJsYn/builds/K7YQR8XM4s9vJ2qr4/openapi.json