# NewHomeSource - New Homes, Floor Plans & Communities (`abotapi/newhomesource-scraper`) Actor

Scrape new homes, floor plans, builders and communities from NewHomeSource.com. Search by US state or city, or paste URLs. Get prices, beds, baths, stories, garage, square footage, builder, location, amenities, community details and available plans.

- **URL**: https://apify.com/abotapi/newhomesource-scraper.md
- **Developed by:** [Abot API](https://apify.com/abotapi) (community)
- **Categories:** Real estate, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 33 total users, 18 monthly users, 88.8% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 home 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/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

## NewHomeSource Scraper: New Construction Homes, Floor Plans, Builders and Communities

NewHomeSource Scraper turns NewHomeSource into a clean new-construction data feed. Pick a US state (optionally narrow to one city) and get every matching community and every home or floor plan inside it, or paste community, home, state or market links to scrape only those. Each result is one flat row with home specs, price, address, geo coordinates, community context and builder contact, ready for JSON, CSV, Excel or your own API.

### Why This Scraper?

- **Two ways to find data.** Walk a whole state, optionally narrowed to one city, in search mode, or paste community, plan, spec-home, state or market links in URL mode. No need to build URLs by hand.
- **One flat row per home.** Every result carries the home's own specs, price and status alongside the community's price band, floor-plan count, quick-move-in count and address, and the builder's name, id and phone, all in one record.
- **State-wide coverage on demand.** Pick a state once and the actor walks its market areas, every community inside them, and every home or floor plan inside each community.
- **Optional deep detail.** Turn on full detail extraction to add the complete specification, photo gallery, videos, amenities, fees, school districts and sales-office contact per home, billed only for homes actually returned.
- **Filters that narrow before you pay.** Home type, price, bedroom, bathroom and size bounds apply to both search and URL mode, so filtered-out homes are never collected or charged.
- **Built for monitoring, with views.** The dataset has Homes, Home details and Changes views. Incremental mode tracks a search over time and returns only new and changed homes on recurring runs, and a run that could not reach the data source fails loudly instead of returning an empty dataset.
- **Resume without re-paying.** Continue an interrupted run from its run or dataset id and skip everything already collected there.

### Use Cases

- **Builder and market research:** track price bands, floor-plan counts and quick-move-in inventory across a state or metro to see where builders are pricing and releasing homes.
- **Real estate lead generation:** collect builder and community contact details alongside home specs for outreach or CRM import.
- **Listing and price monitoring:** schedule the actor with incremental mode to catch new homes, price changes and homes that sell out.
- **Market analytics and dashboards:** feed home counts, price ranges and geo coordinates into a BI tool or map to visualize new-construction supply.
- **Relocation and homebuying tools:** power a search or comparison app with structured floor plan, price and school-district data.

### Data You Get

> Sample shape: values are illustrative placeholders, not from a live record.

| Field | Example |
| --- | --- |
| `homeId` | `2787050` |
| `floorPlan` | `"The Pearson"` |
| `bedrooms` / `bathrooms` | `4` / `3` |
| `halfBathrooms` / `garageCount` | `1` / `2` |
| `stories` / `homeSizeSqft` | `2` / `2450` |
| `homePrice` | `385990` |
| `status` / `homeType` | `"Active"` / `"Single Family"` |
| `isSpec` | `false` |
| `moveInDate` | `"2025-06-01"` |
| `address` | `"123 Example Lane"` |
| `city` / `state` / `zip` | `"Example City"` / `"TX"` / `"75001"` |
| `latitude` / `longitude` | `"32.7767"` / `"-96.7970"` |
| `communityId` / `communityName` | `202479` / `"Sample Community"` |
| `communityMinHomePrice` / `communityMaxHomePrice` | `320000` / `450000` |
| `totalFloorPlans` / `qmiCount` | `8` / `3` |
| `builderId` / `builderName` | `5501` / `"Sample Builder Homes"` |
| `phone` | `"555-0100"` |
| `homeUrl` | link to the home or floor plan page |
| `subtype` | `"floorplan"` (also `"qmi"` or `"basic"`) |
| `communityUrl` | link to the community page |
| `schoolDistricts` | `[{"id": null, "name": "Example County Schools"}]` |
| `changeType` | `"NEW"` (incremental mode only) |

Turning on full detail extraction, or pasting a specific home link (see below), adds a larger set of fields to the same row: `description` and `marketingDescription`, `lotSqft`, the full photo gallery (`images`, `imagesCount`), `videos`, `tourUrl` and `planViewerUrl`, the builder's `builderUrl`, the sales office's `salesOfficeAddress`, `salesOfficeEmail` and `salesOfficePhone`, `schools` and a detailed `schoolDistricts`, `agents`, `homeOptions`, `feesAndRates`, `utilities`, `amenities`, `customAmenities` and `planAmenities`, plus the community's own `communityImages`, `communityVideos`, `communityHours`, `communityDirections`, `communityMapUrl`, `communitySchoolDistricts`, `communitySchools` and `communityAgents`. (The brand fields `brandId`, `brandLogo` and `brandSiteUrl` are already present on every record; full detail only refreshes them.) In incremental mode, `changedFields`, `firstSeenAt` and `lastSeenAt` are added alongside `changeType`.

### How to Use

1. Pick a **mode**: `search` (walk a US state, optionally one city) or `url` (paste specific community or home links).
2. Set the **home type, price, bedroom, bathroom and size filters**. They apply to both modes, and homes they exclude are never collected or charged.
3. Optionally turn on **Fetch full home details** to add the full specification, photo gallery, amenities and sales-office contact per home, billed only for homes returned.
4. Set **Max items** to cap run size and cost, then click **Start**.

**Search a whole state:**

```json
{
  "mode": "search",
  "state": "Texas",
  "maxItems": 50
}
```

**Search one city with filters:**

```json
{
  "mode": "search",
  "state": "Florida",
  "city": "Orlando",
  "homeTypes": ["qmi"],
  "minPrice": 350000,
  "maxPrice": 600000,
  "minBedrooms": 3,
  "maxItems": 100
}
```

**Paste community and home links:**

```json
{
  "mode": "url",
  "urls": [
    "https://www.newhomesource.com/community/id/kuna/medallion-at-valor-by-tresidio-homes/202479",
    "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050"
  ]
}
```

**Recurring monitoring with incremental mode:**

```json
{
  "mode": "search",
  "state": "North Carolina",
  "incrementalMode": true,
  "stateKey": "nc-monitor",
  "maxItems": 0
}
```

#### Run it from your code

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("abotapi/newhomesource-scraper").call(run_input={"mode": "search", "state": "Texas", "maxItems": 50})
for home in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(home["floorPlan"], home["homePrice"], home["city"])
```

JavaScript:

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('abotapi/newhomesource-scraper').call({ mode: 'search', state: 'Texas', maxItems: 50 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

Or connect it to Make, Zapier, n8n, Google Sheets or webhooks from the **Integrations** tab.

#### Supported links

| Link shape | Example | Result |
| --- | --- | --- |
| Community | `/community/tx/austin/parten-65ft-lots-highland-homes/159524` | Every home and floor plan in the community |
| Plan | `/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050` | That floor plan, with full detail |
| Spec home | `/specdetail/595-bird-hollow-austin-tx-78737/3317367` | That quick-move-in home, with full detail |
| Basic home | `/basichome/...` | That home, with full detail |
| State | `/communities/tx`, `/state/texas` or `/new-homes/texas` | Every community and home in the state |
| Market | `/communities/tx/austin-area` or `/new-homes/texas/austin-area` | Every community and home in the market area |

Links are resolved by their numeric id. A link the actor cannot resolve (for example an inactive community) logs a warning naming it and is skipped. The default `urls` value is four example links, one per shape (community, plan, spec home, market), so a URL-mode run with the field untouched scrapes those examples, bounded by **Max items**. Changing the field replaces the examples entirely.

#### Detail enrichment and billing

Turning on Fetch full home details adds one extra request per home for the full specification, gallery, videos, amenities, fees, utilities and sales-office contact, plus one request for the home's community details, each with a bounded per-home time budget so one slow home cannot stall the run. The detail-enrichment surcharge is charged one unit per home, at the moment that home is added to the dataset, so it is never lost if a run is stopped part-way; it applies only to homes that are both enriched and actually returned, never per fetch alone. A home suppressed by incremental mode because it is unchanged since the last run still has its detail page read to compute the comparison, but it is never billed the surcharge if it is not returned. Pasted single-home links (plan, specdetail, basichome) always fetch and return full detail and community context, and are always charged the surcharge, because those links only resolve through the detail endpoint; the toggle only controls whether homes found by a state or city search, or by a pasted community link, also fetch full detail per home.

#### Resume and recurring updates

- **Resume** (`resumeFromRunId`): paste a previous run or dataset id to continue an interrupted run without returning or re-charging homes already collected there.
- **Incremental mode** (`incrementalMode`): for scheduled runs over the same search. Each home is classified `NEW` the first time it is seen, `UPDATED` (with `changedFields` listing what changed) when its data differs from the stored baseline, or `UNCHANGED` (suppressed and not billed unless `emitUnchanged` is on). Turning on `emitExpired` marks homes no longer found as `EXPIRED`, but only once a run reaches the natural end of every scope it tracks, not when Max items or Max pages cut a walk short, and not on a Resume run; a partial run leaves the previous state untouched instead of guessing. `REAPPEARED` is not a routine result: it only appears for a home that an earlier complete run, with `emitExpired` on, had already marked `EXPIRED`, and that is then found again on a later run. `stateKey` names or shares the stored state; leave it empty and the actor derives one automatically from the state, city, URLs and filters, so different searches never mix state with each other.
- **Ignore fields when detecting changes** (`ignoreFieldsForChanges`): list field names that must not count as a change. A name matches at any depth, including nested objects and lists; ignored fields stay in the output and are only left out of the `UPDATED` comparison and `changedFields`. The scrape timestamp `scrapedAt` is never compared. Every other output field (price, beds, baths, size, status, incentives, plans, specs and nested values) is compared.

### Send results into your apps (MCP connectors)

Optionally pipe the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. This is an extra delivery step after the scrape; the Apify dataset is never changed.

**What gets written to the connector:** a condensed, human-readable summary of each home, not the full JSON. Each item becomes one entry with a title and its key fields flattened to plain text. The complete record always stays in the Apify dataset.

1. Authorize a connector once under **Apify > Settings > Integrations** (Notion, Linear, Airtable, or Apify).
2. Select it in the **"Pipe results into your apps"** input field. If the picker is empty, you have not authorized a connector yet.
3. For **Notion**, also set `notionParentPageUrl` to the page where items should be created.

The connection is mediated by Apify's MCP proxy, so this actor never sees your third-party credentials. Leave the field empty to skip.

### Input Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | string | `search` | `search` walks a state (optionally one city); `url` scrapes only pasted links. |
| `state` | string | `Alabama` | US state to walk in search mode. The default is just a starting example, pick any state. |
| `city` | string | (none) | Optional. Narrow a state search to one city by plain name (e.g. `Austin`); a name that matches nothing logs a warning. Search mode only. |
| `urls` | array | 4 example links (community, plan, spec, market) | NewHomeSource community, plan, `/specdetail/`, basic home, state (`/communities/{st}`, `/state/{name}` or `/new-homes/{state}`) or market (`/communities/{st}/{market}-area` or `/new-homes/{state}/{market}-area`) links, where `{st}` is the 2-letter state code. URL mode only. **Behaviour note:** in URL mode with this field untouched, the actor scrapes one example per link shape (bounded by Max items). Links it cannot resolve log a warning naming the link. |
| `startUrls` | array | empty | Alias of `urls`, merged with it. Strings or `{"url": ...}` objects. **Behaviour note:** if you fill this field, the run switches to URL mode even when Mode says search, and when `urls` is left at its four example links only your `startUrls` run (the examples are not scraped or billed). |
| `homeTypes` | array | `["floorplan", "qmi"]` | Which kinds of listings to include: floor plans, QMI / spec homes, or both. |
| `minPrice` | integer | (none) | Only keep homes priced at or above this amount. |
| `maxPrice` | integer | (none) | Only keep homes priced at or below this amount. |
| `minBedrooms` | integer | (none) | Only keep homes with at least this many bedrooms. |
| `minBathrooms` | integer | (none) | Only keep homes with at least this many bathrooms. |
| `minSqft` | integer | (none) | Only keep homes at least this many square feet. |
| `maxSqft` | integer | (none) | Only keep homes at most this many square feet. |
| `fetchDetails` | boolean | `false` | Fetch the full specification, gallery, videos and sales-office contact per home. Billed as a per-home surcharge for homes returned. |
| `maxItems` | integer | `20` | Stop after this many home rows across all searches or URLs. `0` = unlimited. |
| `maxPages` | integer | `0` | Optional hard cap on result pages walked per state, city or URL. `0` = unlimited. |
| `resumeFromRunId` | string | (none) | Continue one interrupted run without re-collecting or re-charging its homes. |
| `incrementalMode` | boolean | `false` | Turn on for recurring runs over the same search: classify homes as new, updated, unchanged, expired or reappeared. |
| `stateKey` | string | (none) | Name or share an incremental-mode state. Leave empty to derive one automatically from the search setup. |
| `emitUnchanged` | boolean | `false` | Also return (and bill) homes unchanged since the last run. Incremental mode only. |
| `emitExpired` | boolean | `false` | Also return (and bill) homes no longer found, once a run completes a full scan. Incremental mode only. |
| `ignoreFieldsForChanges` | array | `[]` | Field names (matched at any depth) that do not count as a change. Incremental mode only. |
| `proxy` | object | Apify Proxy enabled | Connection settings. |
| `mcpConnectors` | array | (none) | Optional: send a summary of each home to apps you authorized under Integrations. |
| `notionParentPageUrl` | string | (none) | Notion connector only: page under which home pages are created. |
| `maxNotifyListings` | integer | `50` | Cap on items written to each connector per run. |

### Output Example

> Sample shape: values are illustrative placeholders, not from a live record.

```json
{
  "homeId": 2787050,
  "planId": 145201,
  "specId": null,
  "floorPlan": "The Pearson",
  "bedrooms": 4,
  "bathrooms": 3,
  "halfBathrooms": 1,
  "garageCount": 2,
  "stories": 2,
  "homeSizeSqft": 2450,
  "homePrice": 385990,
  "status": "Active",
  "homeType": "Single Family",
  "isSpec": false,
  "moveInDate": "2025-06-01",
  "address": "123 Example Lane",
  "city": "Example City",
  "county": "Example County",
  "state": "TX",
  "zip": "75001",
  "latitude": "32.7767",
  "longitude": "-96.7970",
  "communityId": 202479,
  "communityName": "Sample Community",
  "communityMinHomePrice": 320000,
  "communityMaxHomePrice": 450000,
  "totalFloorPlans": 8,
  "qmiCount": 3,
  "builderId": 5501,
  "builderName": "Sample Builder Homes",
  "phone": "555-0100",
  "brandId": 12,
  "brandLogo": "https://example.com/logo.png",
  "homeUrl": "https://www.newhomesource.com/plan-detail/2787050",
  "communityUrl": "https://www.newhomesource.com/community/tx/example-city/sample-community/202479",
  "searchMode": "search",
  "schoolDistricts": [{ "id": null, "name": "Example County Schools" }]
}
```

### Plan Requirement

Keep **Apify Proxy** enabled under Proxy & connection; it is on by default and no extra proxy group is needed. The listing data is served by a separate data service, so every link is resolved through its numeric id instead of the bot-protected public pages. A blocked request is retried on a fresh connection, and if every attempt fails the run ends with a clear message rather than an empty success. If your account is not permitted to use the requested connection, the actor logs a warning and continues on a backup gateway for the rest of the run, where coverage may be limited; enable Apify Proxy or upgrade your plan to avoid that. An explicit proxy group you choose is always honored.

### FAQ

#### How much does it cost?

You are charged per home returned in the dataset, plus a smaller per-home charge only for homes returned with full detail extraction enabled, plus a small per-run start charge. The **Pricing** tab on the actor page shows the current rates. Use **Max items** to cap the cost of any run.

#### Is it legal to scrape NewHomeSource?

This actor collects only publicly available new-construction listing data. You are responsible for how you use it: follow NewHomeSource's terms and the laws that apply to you, and get legal advice if you plan commercial redistribution. Listing facts like price, specs and address are generally not protected, but photos, floor-plan renderings and marketing copy may be subject to third-party rights.

#### Can I get only new or changed homes on a schedule?

Yes. Schedule the actor from the **Schedules** tab and turn on **Incremental mode**. Later runs then return only new and updated homes, and unchanged homes are not billed unless you also turn on **Emit unchanged**.

#### Do pasted single-home links always come back with full detail?

Yes, and this is the most common source of confusion. A pasted plan, specdetail or basichome link only exists as a detail record on the storefront, so the actor always fetches and returns its full detail and community context for that link, and always applies the detail-enrichment surcharge, no matter how **Fetch full home details** is set. That toggle only controls whether homes found by a state or city search, or by a pasted community link, also get the extra fetch.

#### Why does a run sometimes fail instead of returning an empty dataset?

If every attempt to reach the listing service was blocked this run and no homes were scanned, the actor fails the run with a clear message instead of reporting a false empty success, so a saved incremental baseline is never corrupted by a single outage. Try again shortly, or switch the Proxy configuration. If the account's connection specifically was refused, the message says so; that points to a plan or connection-access limit, not an empty result.

#### Can I use it with AI agents or MCP?

Yes. Call it from any Apify integration or MCP client, and use the connector field to push a summary of results into Notion, Linear or Airtable.

### 🔗 Want more real estate data?

Pair this actor with these related scrapers from the same team:

<table>
<tr><td>🏠 <a href="https://apify.com/abotapi/drhorton-scraper"><b>DR Horton</b></a><br>From $1/1K. Extract new-home data from drhorton.com, America’s largest homebuilder. Pull...</td><td>🏠 <a href="https://apify.com/abotapi/lennar-scraper"><b>Lennar Homes, Communities &amp; Floor Plans Scraper</b></a><br>Scrape Lennar new-home communities, move-in-ready homes and floor plans. Extract prices...</td></tr>
<tr><td>🏠 <a href="https://apify.com/abotapi/redfin-scraper"><b>Redfin Scraper</b></a><br>Scrape redfin.com home listings: price, beds, baths, sqft, lot, year built, coordinates...</td><td>🏠 <a href="https://apify.com/abotapi/rent-com-scraper"><b>Rent.com Scraper</b></a><br>Extract rental listings from rent.com. Get comprehensive data including monthly rent...</td></tr>
<tr><td>🧩 <a href="https://apify.com/abotapi/homes-com-scraper"><b>Homes.com Scraper</b></a><br>Scrape US property records from Homes.com. Pick a city, state or ZIP and a channel (for...</td><td>🏠 <a href="https://apify.com/abotapi/properstar-scraper"><b>Properstar</b></a><br>Extract property listings from Properstar across global domains like .com, .co.uk, .ch...</td></tr>
</table>

👉 [Browse all abotapi scrapers](https://apify.com/abotapi)

### 💬 Support

- 🐞 **Found a bug or a missing field?** Open a ticket on the [Issues tab](https://apify.com/abotapi/newhomesource-scraper/issues/open). We usually reply within hours.
- 🛠️ **Need another site, extra fields or a private build?** Email <contact@abotapi.com>.
- ⭐ **Enjoying it?** A quick review on the actor page helps other users find it.

# Actor input Schema

## `mode` (type: `string`):

search = pick a US state (and optionally a city) and get every matching new home, floor plan and community in one flat row per home. url = paste specific NewHomeSource links and scrape only those.

## `state` (type: `string`):

US state to walk. The actor lists the state's market areas, every community in them, and every new home / floor plan inside each community. Big states (Texas, Florida, California) can produce tens of thousands of rows — use the Max items knob below to cap cost.

## `city` (type: `string`):

Optional. Narrow the search to a single city inside the selected state, by plain name (for example 'Birmingham' or 'Columbiana'). Case-insensitive. A name that matches nothing logs a clear warning. Leave empty to cover the whole state.

## `urls` (type: `array`):

Only used when mode = url. Paste NewHomeSource community, home, state or market links. Community, state and market links expand to every home inside. Leaving this field untouched scrapes the four example links.

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

Alias of NewHomeSource links, merged with it. Accepts plain strings or {"url": ...} objects. When you fill this field and leave the NewHomeSource links field untouched, only your Start URLs run (the four example links are NOT scraped or billed), and the run switches to URL mode automatically even if Mode says search.

## `homeTypes` (type: `array`):

Which kinds of listings to include in the output. Both on by default, uncheck whatever you don't need. Floor plans are the builder's catalog of plans you can order. QMI / Spec homes are Quick Move-In homes, already built or under construction. In search mode and for a pasted community link the filter is applied upstream, so the other type's pages are never fetched. A pasted single-home link (plan, specdetail or basichome) is checked after its page is read: an excluded home is still never returned and never charged.

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

Optional. Only keep homes priced at or above this amount. Leave empty for no lower bound.

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

Optional. Only keep homes priced at or below this amount. Leave empty for no upper bound.

## `minBedrooms` (type: `integer`):

Optional. Only keep homes with at least this many bedrooms.

## `minBathrooms` (type: `integer`):

Optional. Only keep homes with at least this many bathrooms.

## `minSqft` (type: `integer`):

Optional. Only keep homes at least this many square feet.

## `maxSqft` (type: `integer`):

Optional. Only keep homes at most this many square feet.

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

Adds the complete specification (all room areas, options, fees, utilities, amenities), the full photo gallery, videos and tours, builder and brand objects, sales-office address / email, school districts, and community marketing copy. Adds one request per home and bills a per-home detail-enrichment surcharge only for homes actually returned.

## `maxItems` (type: `integer`):

The single cap on the run: stop after this many home rows across all searches / URLs. Defaults to 20 so a run stays small unless you raise it. 0 = unlimited, bounded only by the natural end of results (or Max pages, if set).

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

Optional hard cap on the number of result pages walked per state / city / URL. 0 (default) means no page limit — the walk stops naturally when a page comes back empty or repeats already-collected homes, or sooner once Max items is reached.

## `proxy` (type: `object`):

The storefront serves its listing data only to US connections. Apify Proxy works on every plan; leave it enabled for the most reliable results.

## `resumeFromRunId` (type: `string`):

Paste a previous run ID or dataset ID to continue a large crawl without returning or charging for homes already collected there. For recurring daily monitoring of the same search, use Incremental mode below instead.

## `incrementalMode` (type: `boolean`):

Turn this on for daily or recurring monitoring. The first run returns all matching homes as NEW. Later runs normally return only NEW, UPDATED, and REAPPEARED homes. A home is UPDATED when any output field differs from the stored copy (price, beds/baths, size, status, incentives, plans, specs and so on, including nested values); the scrape timestamp (scrapedAt) and any field you list in 'Ignore fields when detecting changes' are never compared, though they stay in the output. Turn on 'Emit unchanged' or 'Emit expired' only when you also want those homes returned (and billed). State is kept separately for each state / city / URL and detail-mode setup; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from a previous run above.

## `stateKey` (type: `string`):

Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the state / city / URLs / filters and detail settings — different searches then never mix state with each other.

## `emitUnchanged` (type: `boolean`):

Off by default. Turn on to also return homes that have not changed since the last run, marked UNCHANGED. This returns — and bills — extra rows you already have, so leave it off unless you specifically want the full snapshot every run.

## `emitExpired` (type: `boolean`):

Off by default. Turn on to also return homes that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search — not when Max items capped it or when Resume was used. This returns — and bills — extra synthetic rows, so leave it off unless you need expiry tracking.

## `ignoreFieldsForChanges` (type: `array`):

Incremental mode only. Field names that must NOT count as a change, for example a gallery or URL field you do not care about. A name matches that field at any depth, including inside nested objects and lists. Ignored fields stay in the output; they are only left out of the NEW/UPDATED comparison and of changedFields. Leave empty to compare everything except the scrape timestamp.

## `mcpConnectors` (type: `array`):

Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify > Settings > Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON — the complete record stays in the dataset. Leave empty to skip.

## `notionParentPageUrl` (type: `string`):

URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors.

## `maxNotifyListings` (type: `integer`):

Cap on items written to each connector per run. Does not affect the dataset.

## Actor input object example

```json
{
  "mode": "search",
  "state": "Alabama",
  "urls": [
    "https://www.newhomesource.com/community/tx/austin/parten-65ft-lots-highland-homes/159524",
    "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050",
    "https://www.newhomesource.com/specdetail/595-bird-hollow-austin-tx-78737/3317367",
    "https://www.newhomesource.com/communities/tx/austin-area"
  ],
  "startUrls": [],
  "homeTypes": [
    "floorplan",
    "qmi"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "proxy": {
    "useApifyProxy": true
  },
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "ignoreFieldsForChanges": [],
  "maxNotifyListings": 50
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `detail` (type: `string`):

No description

## `changes` (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 = {
    "mode": "search",
    "state": "Alabama",
    "urls": [
        "https://www.newhomesource.com/community/tx/austin/parten-65ft-lots-highland-homes/159524",
        "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050",
        "https://www.newhomesource.com/specdetail/595-bird-hollow-austin-tx-78737/3317367",
        "https://www.newhomesource.com/communities/tx/austin-area"
    ],
    "homeTypes": [
        "floorplan",
        "qmi"
    ],
    "fetchDetails": false,
    "maxItems": 20,
    "maxPages": 0,
    "proxy": {
        "useApifyProxy": true
    },
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": false,
    "ignoreFieldsForChanges": [],
    "maxNotifyListings": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("abotapi/newhomesource-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 = {
    "mode": "search",
    "state": "Alabama",
    "urls": [
        "https://www.newhomesource.com/community/tx/austin/parten-65ft-lots-highland-homes/159524",
        "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050",
        "https://www.newhomesource.com/specdetail/595-bird-hollow-austin-tx-78737/3317367",
        "https://www.newhomesource.com/communities/tx/austin-area",
    ],
    "homeTypes": [
        "floorplan",
        "qmi",
    ],
    "fetchDetails": False,
    "maxItems": 20,
    "maxPages": 0,
    "proxy": { "useApifyProxy": True },
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": False,
    "ignoreFieldsForChanges": [],
    "maxNotifyListings": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("abotapi/newhomesource-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 '{
  "mode": "search",
  "state": "Alabama",
  "urls": [
    "https://www.newhomesource.com/community/tx/austin/parten-65ft-lots-highland-homes/159524",
    "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050",
    "https://www.newhomesource.com/specdetail/595-bird-hollow-austin-tx-78737/3317367",
    "https://www.newhomesource.com/communities/tx/austin-area"
  ],
  "homeTypes": [
    "floorplan",
    "qmi"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "proxy": {
    "useApifyProxy": true
  },
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "ignoreFieldsForChanges": [],
  "maxNotifyListings": 50
}' |
apify call abotapi/newhomesource-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,abotapi/newhomesource-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/YqE7oNbC1oenGc0oT/builds/gal4fLHQSeaS6oQRC/openapi.json