# Houzz Pro Scraper (`nathancblack/houzz-pro-scraper`) Actor Scrapes Houzz professional listings into a clean lead dataset (name, phone, address; optional rating/reviews/website/license). Two-tier crawl. Pay-Per-Result: priced per record (use maxResults to cap spend). - **URL**: https://apify.com/nathancblack/houzz-pro-scraper.md - **Developed by:** [Nathan Black](https://apify.com/nathancblack) (community) - **Categories:** Real estate, Jobs, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results 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/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 ## Houzz Pro Scraper An [Apify](https://apify.com) actor that turns the **Houzz professional directory** into a clean, deduplicated lead dataset: business **name, phone, and address** for every listed pro, plus optional **rating, full review text, website, license, services and cost estimates**. Built to be reliable, current, and *honestly specified* — every field rate below is measured from a real run, not claimed. Two crawl tiers: - **Tier 1 (listing)** — one request returns ~15–20 pros from the page's structured JSON-LD. This is the base lead record (name / phone / address). - **Tier 2 (enrichment)** — opt-in (`enrich: true`); fetches each pro's profile to add rating, reviews, website, license, services, cost estimate and badges. --- ### Output fields & measured fill rates > **Honesty note.** Nulls are kept in the output — a null is an honest signal that Houzz > didn't expose that field for that pro, not a dropped field. Fill rates below come from > the real runs described under [Coverage & caveats](#coverage--caveats). Your numbers > will vary by category and location. #### Tier 1 — base record *Measured on **500 records**, general-contractor + architects across Austin/Dallas/Houston (TX) plus a few IL/NC, 2026-06-22.* | Field | Fill | Notes | |---|---|---| | `profile_id` | **100%** | The `pf~`; stable dedup key. | | `profile_url` | **100%** | Canonical Houzz profile URL (from JSON-LD `sameAs`). | | `name` | **100%** | Business name. | | `telephone` | **98%** | The field that makes this a lead list. | | `locality` (city) | **99%** | | | `region` (state) | **98%** | | | `postal_code` | **91%** | | | `country` | **100%** | | | `street_address` | **72%** | Many pros list city/region only, no street. | | `latitude` / `longitude` | **80%** | Geo present for ~4 of 5 pros. | | `image` | **100%** | Primary photo URL. | | `area_served` | **100%** | | Dedup verified clean: **500 unique `profile_id`s out of 500 pushed** (546 overlapping/ sponsored duplicates were dropped before push). #### Tier 2 — enrichment (`enrich: true`) *Measured on **20 enriched records**, general-contractor / Austin TX, full review history, 2026-06-22.* | Field | Fill | Notes | |---|---|---| | `full_address` | **100%** | Full street address from the profile. | | `about` | **100%** | Profile description. | | `services` | **100%** | Service list. | | `rating` | **90%** | Star rating (×10 on Houzz, normalized to e.g. 5.0). | | `rating_count` | **90%** | Number of reviews behind the rating. | | `reviews` | **90%** | Full review objects (see below). | | `sub_ratings` | **85%** | Quality / responsiveness / value aspect ratings. | | `website` | **85%** | The pro's own site (`rawDomain`); junk `http://` dropped. | | `badges` | **85%** | Houzz merit / standout badges. | | `cost_estimate` | **75%** | Typical project cost string. | | `awards` | **40%** | Best-of-Houzz etc. | | `estimate_details` | **35%** | | | `license_number` / `license_status` / `license_verified_status` | **0% (in this sample)** | **Texas issues no state general-contractor license, so this is a true null, not a parse miss.** The parser extracts license number/status where Houzz exposes it; fill in a licensed trade/state has not been separately measured — don't advertise it as guaranteed. | The 10% of pros with no `rating`/`reviews` are simply **new pros with zero reviews** — an honest null, not a gap. **Review objects** (`reviews[]`, measured over 407 real reviews): `body`, `rating`, `author`, `created` all **100%** filled; `review_id`, `relationship`, `project_date`, `modified`, `num_likes`, `status` present; `project_price` only **~21%** (Houzz's "Choose one" placeholder is dropped to null). Full review history is fetched by default in **one request per pro** (up to Houzz's 1024-review cap); use `maxReviews` to cap it. See [`samples/sample_dataset.json`](samples/sample_dataset.json) (20 real enriched records) and [`samples/sample_record_enriched.json`](samples/sample_record_enriched.json) (one record, trimmed to 2 reviews, for a quick look). --- ### Coverage & caveats - **Fill rates are sample-specific.** The Tier-1 numbers are TX-heavy: with a `maxResults` cap, the run fills from the first seeds, so Austin/Dallas dominated before later cities were reached. Different categories/regions will differ — re-measure for your slice. - **Location resolution depends on Houzz's in-page region links.** Locations are resolved by matching the slug against the region links Houzz renders on the category page. If a slug doesn't appear (e.g. `san-antonio-tx-us` did not resolve in testing), it's reported in `unresolved_locations` and skipped — it does not crash the run. Prefer major metros, or pass an explicit listing URL via `startUrls`. - **`totalResults` is a pagination ceiling, not a true count.** Houzz reports ~1499 for a category regardless of region. The crawl **early-stops when a page yields no new pros** rather than paginating to the ceiling, so a single city yields its real unique count (a few hundred), not 1499. - **No "complete national database" claim.** Coverage is whatever the crawl + dedup actually yields for the categories/locations you request, stated plainly. - **License/awards/estimate fields are genuinely partial.** They reflect what each pro filled in on Houzz; treat the rates above as the expectation, not a guarantee. --- ### Reliability & volume (what was actually exercised) Recon (R4) found **no rate-limit / anti-bot infrastructure** (Fastly + Envoy; no Cloudflare, no `x-ratelimit-*`, no `429`). Build 6 validated this with a **gradual real volume ramp**, watching for the first non-200: | Run | Scope | Pages | Pushed | Result | |---|---|---|---|---| | 50 | GC / Austin | 4 | 50 | clean — 0 failures, 0 non-200 | | 200 | GC / Austin+Dallas+Houston | 15 | 200 | clean — 0 failures, 0 non-200 | | 500 | GC + architects / 5 metros (8 seeds) | 39 | 500 | clean — 0 failures, 0 non-200 | | 20 (enrich) | GC / Austin, full reviews | 2 + 40 | 20 | clean — 407 reviews, 0 failures | **Honest limit of this validation:** the largest clean run exercised here was **500 Tier-1 records / 39 pages** and a 20-pro full enrichment. Sustained tens-of-thousands / full multi-geo crawls were **not** exercised (respectful-volume guardrail) — do not assume 10k+ works untested. Ramp gradually and watch for the first non-200. **Resilience built in** (Builds 4): jittered ~1–3s pacing (configurable), exponential backoff + retry on transient errors / 429 / 5xx, per-seed isolation (one bad seed doesn't kill the run), and an **optional proxy-rotation fallback** for IP blocks (`proxyConfiguration`). Proxy is *not* required at modest volume — it's a tested contingency. --- ### Pricing — Pay-Per-Result The actor is monetized **per result**: one price per unique record written to the dataset, via Apify's built-in `apify-default-dataset-item` event. There is no per-event accounting — you pay per lead. - **`maxResults` is your spend cap.** The run stops after that many unique pros. - Only **clean, unique, non-junk** records are pushed (dedup by `profile_id`; records with no profile id are skipped), so you're never billed for duplicates or junk. - `enrich: true` yields **richer rows at the same per-result price** (it costs ~2 extra requests/pro behind the scenes; the per-result price is set at publish time). --- ### Usage #### Input | Field | Type | Default | Meaning | |---|---|---|---| | `categories` | string[] | `["general-contractor"]` | Houzz category slugs. Resolved to the canonical `probr0-bo~t_` listing URL. | | `locations` | string[] | — | Location slugs (e.g. `austin-tx-us`). Empty = national listing. | | `startUrls` | url[] | — | Explicit Houzz listing URLs, instead of / in addition to categories+locations. | | `enrich` | bool | `false` | Fetch profiles for Tier-2 fields. | | `maxReviews` | int | `0` | Per-pro review cap; `0` = full history. | | `maxResults` | int | `0` | Spend cap (unique pros); `0` = until exhausted. | | `minDelaySecs` / `maxDelaySecs` | int | `1` / `3` | Jittered pacing bounds. Keep `min ≥ 1` to be a good citizen. | | `proxyConfiguration` | object | off | Optional proxy / IP-block contingency. | Example (`inputs/example.json`): ```json { "categories": ["general-contractor"], "locations": ["austin-tx-us"], "enrich": false, "maxResults": 30, "minDelaySecs": 1, "maxDelaySecs": 3 } ```` #### Run locally (without the Apify platform) ```bash pip install -r requirements.txt # ideally in a venv (Python 3.13) scripts/run_local.sh # uses inputs/example.json scripts/run_local.sh inputs/enrich_smoke.json # an enrichment example ``` Results land in `storage/datasets/default/` (gitignored); logs print a per-run summary (`pages_fetched`, `records_seen`, `duplicates`, `pushed`, `failed_seeds`, `enriched`, `reviews_fetched`). #### Tests ```bash pip install -r requirements-dev.txt python -m pytest -q # 41 tests, fixture-based, no network ``` *** ### Legal / Terms note Houzz's Terms of Use prohibit scraping and commercial reuse of listings; `robots.txt` allowing the paths does not override that contract (CA jurisdiction). Publishing this as a paid public actor is a deliberate, owner-accepted business-risk decision (see `docs/PLAN.md` §7). The actor is built to be a good citizen — polite pacing, gradual ramp, honest spec — to reduce both ethical and enforcement risk. *** ### How this project is built LLM-driven, multi-session project. **GitHub Issues are the source of truth.** See `CLAUDE.md` (operating rules), `docs/PLAN.md` (the approved plan), `docs/WORKFLOW.md` (conventions), and pinned **issue #1** (state & handoff log). # Actor input Schema ## `categories` (type: `array`): Houzz category slugs to crawl, e.g. "general-contractor". The actor resolves each to its canonical "probr0-bo~t\_" listing URL. Leave empty to crawl only the explicit "startUrls". ## `locations` (type: `array`): Location slugs to scope each category to, e.g. "austin-tx-us". Empty = national listing for the category. ## `startUrls` (type: `array`): Optional explicit Houzz listing-page URLs to crawl directly, instead of (or in addition to) categories+locations. ## `enrich` (type: `boolean`): Fetch each pro's profile page to add street address, star rating, review count + full review text, website, license, services, cost estimate, badges. Same per-result price, richer rows. (Adds ~2 requests per pro behind the scenes: the profile plus its full review history.) ## `maxReviews` (type: `integer`): Cap on reviews fetched per enriched pro. 0 = unlimited (full review history, the default). Only relevant when enrich is on. ## `maxResults` (type: `integer`): Stop after collecting this many unique pros across the whole run. Since the actor is priced per result, this is your spend cap. 0 = no cap (crawl until the category is exhausted). ## `minDelaySecs` (type: `integer`): Lower bound of the jittered delay applied between requests (polite pacing, validated in R4). Keep >= 1 to be a good citizen. ## `maxDelaySecs` (type: `integer`): Upper bound of the jittered delay applied between requests. ## `proxyConfiguration` (type: `object`): Optional proxy. Not required at modest volume (R4 found no rate limiting); use as an IP-block contingency for larger crawls. ## Actor input object example ```json { "categories": [ "general-contractor" ], "enrich": false, "maxReviews": 0, "maxResults": 0, "minDelaySecs": 1, "maxDelaySecs": 3, "proxyConfiguration": { "useApifyProxy": false } } ``` # 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 = { "categories": [ "general-contractor" ] }; // Run the Actor and wait for it to finish const run = await client.actor("nathancblack/houzz-pro-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "categories": ["general-contractor"] } # Run the Actor and wait for it to finish run = client.actor("nathancblack/houzz-pro-scraper").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 '{ "categories": [ "general-contractor" ] }' | apify call nathancblack/houzz-pro-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=nathancblack/houzz-pro-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Houzz Pro Scraper", "description": "Scrapes Houzz professional listings into a clean lead dataset (name, phone, address; optional rating/reviews/website/license). Two-tier crawl. Pay-Per-Result: priced per record (use maxResults to cap spend).", "version": "0.0", "x-build-id": "feuCjWxUPqe6BQljd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nathancblack~houzz-pro-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nathancblack-houzz-pro-scraper", "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/nathancblack~houzz-pro-scraper/runs": { "post": { "operationId": "runs-sync-nathancblack-houzz-pro-scraper", "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/nathancblack~houzz-pro-scraper/run-sync": { "post": { "operationId": "run-sync-nathancblack-houzz-pro-scraper", "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", "properties": { "categories": { "title": "Categories", "type": "array", "description": "Houzz category slugs to crawl, e.g. \"general-contractor\". The actor resolves each to its canonical \"probr0-bo~t_\" listing URL. Leave empty to crawl only the explicit \"startUrls\".", "items": { "type": "string" } }, "locations": { "title": "Locations", "type": "array", "description": "Location slugs to scope each category to, e.g. \"austin-tx-us\". Empty = national listing for the category.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Optional explicit Houzz listing-page URLs to crawl directly, instead of (or in addition to) categories+locations.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "enrich": { "title": "Enrich profiles (Tier-2)", "type": "boolean", "description": "Fetch each pro's profile page to add street address, star rating, review count + full review text, website, license, services, cost estimate, badges. Same per-result price, richer rows. (Adds ~2 requests per pro behind the scenes: the profile plus its full review history.)", "default": false }, "maxReviews": { "title": "Max reviews per pro", "minimum": 0, "type": "integer", "description": "Cap on reviews fetched per enriched pro. 0 = unlimited (full review history, the default). Only relevant when enrich is on.", "default": 0 }, "maxResults": { "title": "Max results", "minimum": 0, "type": "integer", "description": "Stop after collecting this many unique pros across the whole run. Since the actor is priced per result, this is your spend cap. 0 = no cap (crawl until the category is exhausted).", "default": 0 }, "minDelaySecs": { "title": "Min delay between requests (s)", "minimum": 0, "type": "integer", "description": "Lower bound of the jittered delay applied between requests (polite pacing, validated in R4). Keep >= 1 to be a good citizen.", "default": 1 }, "maxDelaySecs": { "title": "Max delay between requests (s)", "minimum": 0, "type": "integer", "description": "Upper bound of the jittered delay applied between requests.", "default": 3 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional proxy. Not required at modest volume (R4 found no rate limiting); use as an IP-block contingency for larger crawls.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } } ```