# Homes.com Listing Scraper (`khadinakbar/homes-com-listing-scraper`) Actor

Private development candidate for Homes.com listing extraction. Cloud source-access testing is blocked; production readiness is unverified. Source-linked listing parser, bounded pagination and charge safeguards. Provisional $0.60/1,000 listings plus startup and platform usage.

- **URL**: https://apify.com/khadinakbar/homes-com-listing-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Real estate, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.60 / 1,000 listing saveds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Homes.com Listing Scraper

Turn Homes.com city, ZIP, filtered search and individual property URLs into one structured dataset for property research. Each row includes a canonical listing URL, address, advertised price, bedrooms, bathrooms, floor area, available photo links and retrieval time. The scraper preserves URL filters, follows the site's pagination and removes duplicate properties within a run.

This Actor is an independent tool and is not affiliated with Homes.com or CoStar Group. This private development build is blocked on source access: the HTTP and US residential browser cloud canaries returned no listings. It is not ready for production or Store publication.

### Choose the right workflow

Use this Actor when you already have Homes.com listing or search URLs and need a bounded, source-linked property dataset. Analysts can compare advertised prices and floor areas or refresh a previously saved set of listing URLs. The source remains authoritative: advertised prices are not appraisals and the output is not an MLS feed or a complete market inventory.

The Actor returns property listing records. Agent-directory profiles, contact harvesting, authenticated pages, neighborhood reports, school records, property ownership and historical transaction feeds are outside its scope. Search URLs for sale, rent or sold pages require separate successful live tests before those modes are claimed as supported.

### From a search page to a comparison dataset

A property researcher starts with an Austin search URL, sets a result and page limit, and exports the dataset as JSON, CSV or Excel through Apify. Rows carry the original source page and collection time so the researcher can open each property and check its current availability. Read the run outcome before comparing cities: a result cap, page cap or failed page means the scan is partial.

### Quick start

```json
{
  "startUrls": [{"url": "https://www.homes.com/austin-tx/"}],
  "maxResults": 100,
  "maxPages": 5,
  "transport": "auto"
}
```

`startUrls` accepts 1–50 HTTPS Homes.com URLs. `maxResults` limits unique saved rows across the complete run; `maxPages` limits successfully scanned pages. `transport: auto` attempts HTTP then browser retrieval. `http` and `browser` select one route for diagnostics. The browser route uses Apify US residential proxy by default; `useResidentialProxy: false` is available for direct-route diagnostics. Residential traffic is additional caller-paid platform usage. Request timeouts and an overall work deadline bound slow sources. Extra unused input settings are ignored.

To collect one property, pass its complete `/property/.../.../` URL. Copy the actual URL from Homes.com rather than constructing a property ID.

### What one result contains

| Field | Meaning |
| --- | --- |
| `listingId`, `listingUrl` | Property identity and canonical source link |
| `address`, `streetAddress`, `city`, `state`, `postalCode` | Address shown by the source |
| `price`, `currency`, `priceText` | Advertised price and original price wording; unknown price is null |
| `bedrooms`, `bathrooms`, `squareFeet` | Source counts and floor area in square feet; missing values are null |
| `listingStatus`, `propertyType` | Classification when present in source metadata |
| `description`, `photos` | Up to 1,000 description characters and ten photo URLs; images are not downloaded |
| `latitude`, `longitude`, `yearBuilt` | Optional detail metadata when supplied |
| `sourceUrl`, `scrapedAt`, `dataSource`, `extractionMethod` | Retrieval provenance and extraction route |

Representative parser example, based on the source page inspected on October 14, 2026; it is not a cloud acceptance claim:

```json
{
  "listingId": "x5zewgn876r6t",
  "listingUrl": "https://www.homes.com/property/7516-windrush-dr-austin-tx/x5zewgn876r6t/",
  "price": 549000,
  "currency": "USD",
  "priceText": "$549,000",
  "address": "7516 Windrush Dr, Austin, TX 78729",
  "streetAddress": "7516 Windrush Dr",
  "city": "Austin",
  "state": "TX",
  "postalCode": "78729",
  "bedrooms": 4,
  "bathrooms": 2.5,
  "squareFeet": 2884,
  "propertyType": "SingleFamilyResidence",
  "listingStatus": "for sale",
  "description": null,
  "photos": [],
  "latitude": null,
  "longitude": null,
  "yearBuilt": null,
  "sourceUrl": "https://www.homes.com/austin-tx/",
  "scrapedAt": "2026-10-14T12:00:00.000Z",
  "dataSource": "homes.com",
  "extractionMethod": "jsonLd+listingCard"
}
```

### Pricing and predictable limits

Proposed Pay per event pricing is **$0.60 per 1,000 saved listings**, plus **$0.00005 per startup event**. Apify calculates startup events per GB of allocated memory, with a minimum of one; at the default 2 GB this is $0.00010. Compute, browser operation, storage and traffic usage are additional and paid by the caller. The live [Pricing tab](https://apify.com/khadinakbar/homes-com-listing-scraper/pricing) becomes authoritative once pricing is configured.

At these proposed rates, 100 saved listings at 2 GB cost $0.06010 in event fees, plus platform usage. One listing costs $0.00070 in event fees, plus platform usage. The result event is attached to the validated dataset write. Duplicate properties do not create additional result events. Empty or failed runs can still incur startup and platform usage costs. A maximum event-charge setting does not cap platform usage.

All supported inputs use the same extraction quality and output fields across account plans. Owner test event counts establish billing behavior, not earned revenue or non-owner FREE-account acceptance.

### API example

```bash
export APIFY_TOKEN='YOUR_APIFY_TOKEN'
curl --request POST \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"startUrls":[{"url":"https://www.homes.com/austin-tx/"}],"maxResults":10,"maxPages":1}' \
  'https://api.apify.com/v2/acts/khadinakbar~homes-com-listing-scraper/runs'
```

Keep API tokens in environment variables and authorization headers. Poll the returned run ID and retrieve its default dataset after completion. Fetch `OUTPUT` and `RUN_SUMMARY` from the default key-value store to assess completeness, page failures and named result events. Apify supports dataset exports to CSV, Excel and JSON.

### AI-agent prompt card

> Collect up to 25 unique Homes.com listings from this search URL. Return source links, advertised price, bedrooms, bathrooms and square feet. Read OUTPUT before summarizing; state whether the scan was partial. Do not treat missing values as zero or describe the results as a complete market inventory.

Use a small explicit result/page limit. Through Apify's hosted MCP, discover the Actor and inspect its current schema, start a run with the exact inputs, wait for its outcome and retrieve bounded dataset pages. Actual hosted MCP execution has not yet been verified for this private build; the HTTP API is a separate interface.

### Best results and troubleshooting

- Copy a working Homes.com search URL, including its filters. Start with one city and a small result limit.
- Use several pages only when you need broader coverage. Homes.com can impose its own pagination and inventory limits; this Actor does not claim to remove them.
- `PARTIAL` means useful data or a controlled stop remains inspectable. Check `stopReason`, failed-page counts and warnings.
- `VALID_EMPTY` requires an explicit source empty-result marker. Access denial, challenges and markup drift are never silently labelled empty.
- `INVALID_INPUT` explains which setting to correct. `UPSTREAM_FAILED` means the source returned no useful data; wait or narrow the run. `CONFIG_ERROR` identifies runtime or unresolved delivery state.
- After an interruption, the saved state fingerprints the input and build. Uncertain listing writes or charges block additional billable work until reviewed; this is a conservative resume safeguard, not an exactly-once transaction guarantee.

### Evidence and freshness

Local tests cover the fractional-bath discrepancy, genuine zero versus missing values, malformed metadata, challenge pages, pagination, deduplication, result/page limits, rate limits and resume safeguards. Two cloud canaries failed honestly with zero dataset rows and zero listing events; they do not pass acceptance. Cloud validation and measured cost evidence are recorded separately in the private release logbook. A successful browser page view or local test is not proof of a deployed working Actor or a production reliability percentage.

Builder's note: Homes.com's structured data can omit half baths shown in the visible listing card. The extractor merges by canonical property URL and gives the visible card count precedence, while retaining null for genuinely missing data.

### Data-use boundary

Collect only information you have authority to access and use. [Homes.com's current Terms of Use](https://www.homes.com/about/homesterms-of-use/) restrict automated extraction and redistribution. The owner must review rights and the intended use before publication. Source links and timestamps establish provenance, not permission. The Actor collects listing facts and photo links; it does not download photos or harvest agent phone numbers or emails.

# Actor input Schema

## `startUrls` (type: `array`):

Add 1–50 HTTPS Homes.com city, ZIP, filtered search or individual property URLs. Example: https://www.homes.com/austin-tx/. Filters in the URL are preserved. Agent directories and login pages are not supported.

## `maxResults` (type: `integer`):

Stop after this many unique listings across all URLs. Accepts 1–10,000; default 100. Each saved listing has one result event; platform usage is additional.

## `maxPages` (type: `integer`):

Limit total successful page scans across all inputs and pagination. Accepts 1–250; default 5. Results are partial when further pages remain.

## `transport` (type: `string`):

Choose auto, http or browser. Auto tries direct HTTP then a browser if the page is unusable. Default auto. HTTP-only is a diagnostic route and can fail on protected pages.

## `requestTimeoutSecs` (type: `integer`):

Bound each retrieval route to 10–90 seconds. Default 45. A timeout produces a failure diagnostic rather than an empty listing page.

## `maxRunSecs` (type: `integer`):

Stop starting page work after 30–3,600 seconds. Default 600. Saved listings remain available in a partial result; terminal storage writes may take additional time.

## `useResidentialProxy` (type: `boolean`):

Use Apify US residential proxy for the browser route. Default enabled after cloud access-denial testing. Proxy bandwidth is additional platform usage paid by the caller. Disable only for direct-route diagnostics.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.homes.com/austin-tx/"
    }
  ],
  "maxResults": 100,
  "maxPages": 5,
  "transport": "auto",
  "requestTimeoutSecs": 45,
  "maxRunSecs": 600,
  "useResidentialProxy": true
}
```

# Actor output Schema

## `listings` (type: `string`):

No description

## `output` (type: `string`):

No description

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

No description

# 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 = {
    "startUrls": [
        {
            "url": "https://www.homes.com/austin-tx/"
        }
    ]
};

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

# Prepare the Actor input
run_input = { "startUrls": [{ "url": "https://www.homes.com/austin-tx/" }] }

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/homes-com-listing-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.homes.com/austin-tx/"
    }
  ]
}' |
apify call khadinakbar/homes-com-listing-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/homes-com-listing-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Q28GEA52NeKIW6nSV/builds/7JQ9zHDvjcnptO63n/openapi.json