# 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
- **Stats:** 2 total users, 1 monthly users, 100.0% 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?

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

## NewHomeSource.com New Homes Scraper

All-in-one scraper for [NewHomeSource.com](https://www.newhomesource.com) — the US new-construction
site covering new homes, floor plans, builders and communities. Pick a US state (optionally a
city), or paste specific community / home links, and get **one flat row per new home** — home specs,
price, address, geo coordinates, community context, builder and phone in a single JSON / CSV row.

### What you get

- **Every new home / floor plan across a state.** Pick `Texas` once and the actor walks the state's
  market areas, every community in each, and every new home / floor plan inside — all in one run.
- **Community + builder context on every row.** Each row carries the home's own price, size, beds,
  baths, stories and garage count, plus the community's price band, floor-plan count, QMI (quick
  move-in) count, address and description, and the builder / brand name, ID and phone.
- **Geo-ready.** Latitude and longitude on every row, plus street address, city, county, state, zip.
- **JSON or CSV out.** No glue code — connect to your warehouse, BI tool or spreadsheet in one step.

### How to use

#### 1. Search mode — pick a state (and optional city)

Choose a state, optionally narrow to one city:

| Field | What it does |
|---|---|
| State | The state to walk (market areas → communities → homes). |
| City | Optional. Narrow the search to a single city inside the state. |

#### 2. URL mode — paste specific links

Paste one or more NewHomeSource links. Accepted kinds:

- **Community URLs** — `https://www.newhomesource.com/community/{state}/{city}/{slug}/{id}` or
  `https://www.newhomesource.com/basiccommunity/community-{id}/...` — each expands to every home /
  floor plan in that community.
- **Home URLs** — `https://www.newhomesource.com/plan/...`, `/specdetail/...` or `/basichome/...` —
  each produces one row for that home / plan.

#### 3. Filters (apply to both modes)

These narrow the results whichever mode you run, Search mode or a pasted community / home URL:

| Field | What it does |
|---|---|
| Home types | Floor plans, QMI / spec homes, or both. |
| Minimum / maximum price | USD price bounds. |
| Minimum bedrooms / bathrooms | Room-count bounds. |
| Minimum / maximum size | Square-foot bounds. |

#### 4. Detail enrichment (optional)

Turn on **Fetch full home details** to add, per home: the full specification (all room areas,
options, fees, rates, utilities, amenities), the complete photo gallery, videos and virtual tours,
the builder and brand objects, the sales-office address / email / phone, school districts and
schools, and the community's marketing copy. Each home enriched **and returned** is billed a small
detail-enrichment surcharge on top of the result price.

#### 5. Resume & recurring updates

- **Resume from a previous run** — continue one interrupted run without re-collecting or re-charging
  homes already returned there.
- **Incremental changes for scheduled runs** — run this same search daily / weekly and get only the
  changes: the first run returns everything as `NEW`; later runs return `NEW`, `UPDATED` and
  `REAPPEARED` homes by default. Optionally emit `UNCHANGED` or `EXPIRED` rows too (each returned
  row is billed). State is kept per search setup, or use a **State key** to name / share a
  monitoring campaign.

### Output fields (one row per home)

| Group | Fields |
|---|---|
| **Home specs** | `homeId`, `planId`, `specId`, `listingId`, `listingNumber`, `floorPlan`, `bedrooms`, `bathrooms`, `halfBathrooms`, `garageCount`, `stories`, `homeSizeSqft`, `homePrice`, `moveInDate`, `dateFirstPublished`, `status`, `homeType`, `isSpec`, `specNumber`, `isHotHome`, `isLuxury`, `masterBedroomLocation`, `numLivingAreas` |
| **Community context** | `communityId`, `communityName`, `communityStatus`, `communityType`, `projectType`, `communityAddress`, `communityMinHomePrice`, `communityMaxHomePrice`, `communityMinHomeSize`, `communityMaxHomeSize`, `totalFloorPlans`, `qmiCount`, `secondaryCount`, `totalHomes`, `notes` |
| **Location** | `latitude`, `longitude`, `address`, `city`, `county`, `state`, `zip` |
| **Builder / brand** | `builderId`, `builderName`, `builderUrl`, `brandId`, `brandLogo`, `brandSiteUrl`, `phone` |
| **Source URLs** | `imageUrl`, `imageUrl2`, `communityUrl`, `homeUrl` |
| **Detail enrichment (optional)** | `description`, `marketingDescription`, `lotSqft`, `planTypeId`, `images`, `imagesCount`, `videos`, `tourUrl`, `planViewerUrl`, `selfGuidedTour`, `salesOfficeAddress`, `salesOfficeEmail`, `salesOfficePhone`, `schoolDistricts`, `schools`, `agents`, `homeOptions`, `feesAndRates`, `utilities`, `amenities`, `customAmenities`, `planAmenities`, `communityImages`, `communityImagesCount`, `communityVideos`, `communityHours`, `communityDirections`, `communitySalesOfficeEmail`, `communitySchoolDistricts`, `communitySchools`, `communityAgents`, `communityMapUrl` |
| **Incremental mode** | `changeType`, `changedFields`, `firstSeenAt`, `lastSeenAt` |

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

Optionally pipe results into the tools you already use via Model Context Protocol (MCP)
connectors (Notion, Linear, Airtable, Apify). Authorize a connector once under Apify > Settings >
Integrations, then select it in the input. The connector receives a condensed, human-readable
summary per home (title + key fields), not the full JSON: the complete record always stays in the
dataset, and this never changes the dataset output.

| Field | What it does |
|---|---|
| `mcpConnectors` | MCP connectors to export results to (Notion, Linear, Airtable, Apify). Leave empty to skip. |
| `notionParentPageUrl` | Notion parent page URL (or id) under which item pages are created. Required for the Notion connector; ignored by others. |
| `maxNotifyListings` | Cap on items written to each connector per run (default 50). Does not affect the dataset. |

### Connection

Results are served only to US connections. Apify Proxy is used by default and works on every plan; leave it enabled (or supply your own US exit) for runs outside the US.

### Limits

- **Max items** — the single cap on the run (default 20; `0` = unlimited). The run stops at this
  many home rows across all searches / URLs.
- **Max pages per scope** — optional per-scope page cap (`0` = no limit; the walk stops at the
  natural end of results or at Max items).

### FAQ

**What is a QMI / spec home?** A Quick Move-In home — already built or under construction and ready
to close soon. Floor plans are the builder's catalog of plans you can order. The **Home types**
toggle controls which appear.

**Can I scrape multiple states?** One state per run (plus optional city). To cover multiple states,
schedule the actor with different State values, or paste community links from each state into one
URL-mode run.

**Do pasted single-home links include community context?** Yes when **Fetch full home details** is
on — the actor also reads the home's community record. With details off, a single home link returns
the row with community rollup fields (price band, floor-plan count) left empty, because those live
on the community page.

# 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 (for example 'Birmingham' or 'Columbiana'). Leave empty to cover the whole state. Case-insensitive.

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

Only used when mode = url. Paste one or more NewHomeSource community or home links. Community links expand to every home inside them.

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

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

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

## `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/id/kuna/medallion-at-valor-by-tresidio-homes/202479",
    "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050"
  ],
  "homeTypes": [
    "floorplan",
    "qmi"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "proxy": {
    "useApifyProxy": true
  },
  "maxNotifyListings": 50
}
```

# Actor output Schema

## `overview` (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/id/kuna/medallion-at-valor-by-tresidio-homes/202479",
        "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050"
    ],
    "homeTypes": [
        "floorplan",
        "qmi"
    ],
    "fetchDetails": false,
    "maxItems": 20,
    "maxPages": 0,
    "incrementalMode": false,
    "emitUnchanged": false,
    "emitExpired": false,
    "proxy": {
        "useApifyProxy": true
    },
    "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/id/kuna/medallion-at-valor-by-tresidio-homes/202479",
        "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050",
    ],
    "homeTypes": [
        "floorplan",
        "qmi",
    ],
    "fetchDetails": False,
    "maxItems": 20,
    "maxPages": 0,
    "incrementalMode": False,
    "emitUnchanged": False,
    "emitExpired": False,
    "proxy": { "useApifyProxy": True },
    "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/id/kuna/medallion-at-valor-by-tresidio-homes/202479",
    "https://www.newhomesource.com/plan/the-pearson-smith-douglas-homes-columbiana-al/2787050"
  ],
  "homeTypes": [
    "floorplan",
    "qmi"
  ],
  "fetchDetails": false,
  "maxItems": 20,
  "maxPages": 0,
  "incrementalMode": false,
  "emitUnchanged": false,
  "emitExpired": false,
  "proxy": {
    "useApifyProxy": true
  },
  "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/6SnR47eklyJvAU0ep/openapi.json