# Houzz Professionals Scraper (`devilscrapes/houzz-professionals-scraper`) Actor

Scrape Houzz's public professional directory into home-services leads — contractors, architects, and designers — with license number, project/photo count, and years-in-business pulled from Houzz's own embedded data that other Houzz scrapers leave out.

- **URL**: https://apify.com/devilscrapes/houzz-professionals-scraper.md
- **Developed by:** [DevilScrapes](https://apify.com/devilscrapes) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

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

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

<div align="center">
  <img src=".actor/icon.svg" width="160" alt="Devil Scrapes mark" />

## Houzz Professionals Scraper

**💰 $2.52 / 1 000 results**  ·  pay only for results  ·  no credit card to try

*We do the dirty work so your dataset stays clean.* 😈

Scrape Houzz's public professional directory into home-services leads — contractors, architects, and designers — with license number, project/photo count, and years-in-business pulled from Houzz's own embedded data that other Houzz scrapers leave out.

</div>

***

### 🎯 What this scrapes

Houzz's professional directory (`houzz.com/professionals/`) is the go-to shortlist for architects, general contractors, interior designers, landscapers, and 70+ other home-services trades. This Actor turns each category-browse listing page (and, optionally, each pro's profile page) into structured leads — name, category, city/state, phone, rating, and review count from the listing, plus license number, project/photo count, clean website URL, and a self-reported years-in-business badge from the profile — fields the incumbent Houzz scrapers skip because they scrape the visible DOM instead of Houzz's own embedded JSON record.

### 🔥 What we handle for you

- 🛡️ **Browser fingerprint rotation** — `curl-cffi` impersonates real Chrome / Firefox / Safari TLS handshakes so the target sees a browser, not Python.
- 🌐 **Residential proxy rotation** via Apify Proxy — fresh session and exit IP on every block.
- 🔁 **Retries with exponential backoff** on `408 / 429 / 5xx` — up to 5 attempts per page, `Retry-After` honoured.
- 🧱 **Rate-limit-aware pacing** — when the target pushes back, we slow down instead of getting banned.
- 🧊 **Clean, typed dataset rows** — Pydantic-validated, ISO-8601 timestamps, stable IDs, JSON / CSV / Excel export straight from the Apify Console.
- 💰 **Pay-Per-Event pricing** — you only pay for results that hit your dataset. No data, no charge.

### 💡 Use cases

- Franchise and vendor prospecting — build a call list of licensed contractors/designers by category and city.
- Sales prospecting — target pros with verified license numbers and strong review counts.
- Market research — track years-in-business and portfolio size distribution across a trade category.
- Lead scoring — filter by rating, review count, and license presence before outreach.

### ⚙️ How to use it

1. Click **Try for free** at the top of the page.
2. Fill in the input form — most fields have sensible defaults.
3. Click **Start**. Output streams into the run's dataset.
4. Export from **Storage → Dataset** as JSON, CSV, or Excel — or fetch via the API.

### 📥 Input

| Field | Type | Required | Default | Notes |
|---|---|:--:|---|---|
| `category` | `string` | **yes** | 'general-contractor' | Houzz professional category slug to scrape, e.g. "general-contractor". |
| `location` | `string` | no | '—' | Optional "City, ST" free text. Applied as a post-scrape city/state match against nationwide category results. Leave… |
| `maxResults` | `integer` | no | 200 | Stop once this many unique (deduped by Houzz professional ID) leads are collected. |
| `maxPages` | `integer` | no | 20 | Hard cap on listing pages fetched (15 rows/page), independent of Max results. |
| `fetchProfileDetails` | `boolean` | no | True | When true, fetch each pro's profile page for license number, project/photo count, and a clean website URL. |
| `proxyConfiguration` | `object` | no | {'useApifyProxy': False} | Apify Proxy settings. Optional — Houzz clears via curl-cffi browser impersonation alone (live-confirmed, no proxy).… |

#### Example input

```json
{
  "category": "general-contractor",
  "maxResults": 5,
  "maxPages": 1,
  "fetchProfileDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

### 📤 Output

Every row is one dataset item.

| Field | Type | Notes |
|---|---|---|
| `houzz_professional_id` | `integer` | Stable Houzz professional ID — dedup/identity key. |
| `name` | `string` | Business/pro display name. |
| `category` | `string` | Houzz category display name, e.g. "General Contractors". |
| `city` | `['string', 'null']` | City. |
| `region` | `['string', 'null']` | State. |
| `phone` | `['string', 'null']` | Formatted phone number, verbatim. |
| `website` | `['string', 'null']` | Clean, un-tracked website URL. Null unless Fetch profile details is on. |
| `review_count` | `integer` | Review count. Never null. |
| `average_rating` | `['number', 'null']` | Rating on a 0-5 scale. Null when review\_count is 0. |
| `project_or_photo_count` | `['integer', 'null']` | Aggregate portfolio photo count. Null unless Fetch profile details is on. |
| `years_in_business` | `['integer', 'null']` | Self-reported years-in-business badge, when present. Never estimated. |
| `license_number` | `['string', 'null']` | License number string. Null unless Fetch profile details is on, and even then present on roughly half of profiles. |
| `houzz_profile_url` | `string` | Canonical Houzz profile URL. |
| `scraped_at` | `string` | ISO-8601 UTC timestamp when this row was recorded. |

#### Example output

```json
{
  "houzz_professional_id": 752464,
  "name": "Full Service USA",
  "category": "General Contractors",
  "city": "Hallandale",
  "region": "FL",
  "phone": "(305) 487-8485",
  "website": "http://www.fullserviceusa.com",
  "review_count": 94,
  "average_rating": 4.8,
  "project_or_photo_count": 710,
  "years_in_business": null,
  "license_number": "CG 1516022",
  "houzz_profile_url": "https://www.houzz.com/professionals/general-contractors/full-service-usa-pfvwus-pf~1830092161",
  "scraped_at": "2026-08-06T12:00:00Z"
}
```

### 💰 Pricing

Pay-Per-Event — you pay only when these events fire:

| Event | USD | What it is |
|---|---:|---|
| `actor-start` | $0.02 | One-off warm-up charge per run |
| `result-emitted` | $0.002 | Per unique dataset item |
| `profile-page-scraped` | $0.0005 | Per upstream page or API call |

Example: 1 000 results at the rates above ≈ **$2.52**. No subscription, no minimum, no card to start — Apify gives every new account $5 of free credit.

### 🚧 Limitations

Location filtering is a post-scrape city/state match against nationwide category results, not a native Houzz geo-radius query — small/rural cities may need a higher Max pages to find enough matches. license\_number and years\_in\_business are opt-in Houzz fields with partial coverage by design, never fabricated. No email addresses (Houzz doesn't expose them) and no non-US Houzz sites in v1.

### ❓ FAQ

**Is this legal?**

We only fetch content Houzz makes publicly available on its professional directory pages. Respect Houzz's terms of service before using output commercially.

**Do I need a proxy?**

No — Houzz's listing and profile pages clear with curl-cffi browser impersonation alone (no proxy required). Enable a proxy group only if you start seeing blocks.

**Why is license\_number often null?**

Houzz only exposes the license number string on profile pages, and only around half of pros have one on file. We never fabricate it to raise the fill rate.

**Why is years\_in\_business usually null?**

It's a self-reported, opt-in Houzz badge — most pros haven't enabled it. We parse it only when Houzz explicitly shows it, never estimate it from reviews or project count.

**Does location filter to an exact radius?**

Not natively — Houzz's radius search needs an internal region ID we can't resolve from a plain city/state string, so location is applied as a post-scrape city/state match against nationwide results.

### 💬 Your feedback

Spotted a bug, hit a weird edge case, or need a new field? Open an
issue on the Actor's **Issues** tab on Apify Console — we ship
fixes weekly and we read every report.

***

<div align="center">

Built by **[Devil Scrapes](https://apify.com/DevilScrapes)** 😈 — a small fleet of
opinionated public-data Actors. Honest pricing, real engineering, zero fine print.

</div>

# Actor input Schema

## `category` (type: `string`):

Houzz professional category slug to scrape, e.g. "general-contractor". This is a confirmed-live subset of the ~78 categories Houzz supports; the full slug->topicId table lives in src/categories.py.

## `location` (type: `string`):

Optional "City, ST" free text. Applied as a post-scrape city/state match against nationwide category results (Houzz's native geo query needs an internal region ID we can't resolve — see README Limitations). Leave empty for nationwide results.

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

Stop once this many unique (deduped by Houzz professional ID) leads are collected.

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

Hard cap on listing pages fetched (15 rows/page), independent of Max results — the safety valve against Houzz's totalCount display-cap quirk.

## `fetchProfileDetails` (type: `boolean`):

When true, fetch each pro's profile page for license number, project/photo count, and a clean website URL. Set false for a faster/cheaper listing-only run (those three fields stay null).

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Optional — Houzz listing and profile pages clear via curl-cffi browser impersonation alone (live-confirmed, no proxy). Enable a proxy group only if you see blocks.

## Actor input object example

```json
{
  "category": "general-contractor",
  "maxResults": 5,
  "maxPages": 1,
  "fetchProfileDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

All dataset items as JSON.

## `datasetItemsCsv` (type: `string`):

Same data exported to CSV.

## `datasetView` (type: `string`):

Open the run dataset in the Console.

# 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 = {
    "category": "general-contractor",
    "maxResults": 5,
    "maxPages": 1,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("devilscrapes/houzz-professionals-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 = {
    "category": "general-contractor",
    "maxResults": 5,
    "maxPages": 1,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("devilscrapes/houzz-professionals-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 '{
  "category": "general-contractor",
  "maxResults": 5,
  "maxPages": 1,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call devilscrapes/houzz-professionals-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=devilscrapes/houzz-professionals-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/qFeWzMmnA2awiVc0X/builds/voqqxP8l7HZ3CKvAg/openapi.json