{
  "openapi": "3.0.1",
  "info": {
    "title": "Houzz Pros [$2💰] Contractor & Designer Leads, Reviews, Emails",
    "description": "Houzz professionals scraper — find contractors, architects, designers and remodelers by trade and city. One row per pro: phone, website, address, rating, review count, services, areas served, license and cost estimate. Opt-in nested reviews and emails. Pure HTTP, no browser.",
    "version": "0.1",
    "x-build-id": "Jcr4K9clT0atKC6SS"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/memo23~houzz-professionals-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-memo23-houzz-professionals-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/memo23~houzz-professionals-scraper/runs": {
      "post": {
        "operationId": "runs-sync-memo23-houzz-professionals-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/memo23~houzz-professionals-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-memo23-houzz-professionals-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": {
          "searchQueries": {
            "title": "Search keywords / professions",
            "type": "array",
            "description": "Professions or keywords to search on Houzz, one per line. Each keyword is searched and paginated in every location below. Examples: `general contractor`, `architect`, `interior designer`, `kitchen remodeler`, `landscape architect`. Required — with an empty list the run produces no rows. Default: `general contractor`.",
            "items": {
              "type": "string"
            }
          },
          "locations": {
            "title": "Locations",
            "type": "array",
            "description": "Optional US cities / areas, one per line, in `City, ST` form — e.g. `New York, NY`, `Los Angeles, CA`, `Austin, TX`. Every search keyword is run once per location (keyword × location). Leave the list empty for a single nationwide US search per keyword. Default: `New York, NY`.",
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Max professionals (whole run)",
            "minimum": 1,
            "type": "integer",
            "description": "Hard cap on professional rows across the entire run, e.g. `250`. Each row is one paid `professional` event. Free Apify accounts are additionally capped at 100 rows per run. Default: 1000.",
            "default": 1000
          },
          "maxItemsPerQuery": {
            "title": "Max professionals per query × location",
            "minimum": 1,
            "type": "integer",
            "description": "Cap per (keyword × location) pair, e.g. `100` to spread a budget evenly across many cities. Houzz lists tens of thousands of professionals per trade in major metros, so leaving this high means one big city can consume the whole run. Default: 1000.",
            "default": 1000
          },
          "dedupe": {
            "title": "De-duplicate professionals",
            "type": "boolean",
            "description": "When true, a professional that appears under several keywords or locations is emitted (and billed) only once, keyed by their Houzz id. Set false to keep one row per keyword × location match instead. Default: true.",
            "default": true
          },
          "includeReviews": {
            "title": "Include reviews",
            "type": "boolean",
            "description": "When true, fetches each professional's Houzz reviews (reviewer, rating, date, review text, project relationship, photos, and the pro's reply if any) and nests them on that pro's row as `reviews`, plus `reviewsFetched` and `reviewsTotalAvailable`. No extra charge — reviews ride on the same professional row — but each pro costs one or more extra HTTP requests, so runs take longer. Default: false.",
            "default": false
          },
          "maxReviewsPerPro": {
            "title": "Max reviews per professional",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Only used when \"Include reviews\" is on. Caps how many of each professional's reviews (newest first) are fetched, e.g. `5` for a quick sample or `200` for a full history. Allowed range 1–500. Default: 20.",
            "default": 20
          },
          "enrichEmails": {
            "title": "Enrich with contact emails (experimental)",
            "type": "boolean",
            "description": "When true, looks for a contact email for each professional on that pro's own website (the website is already captured on every row). Adds `contactEmail` and `contactWebsite` columns plus a detailed `emailEnrichment` object. Best-effort — Houzz itself rarely publishes emails. Billed as one `additional-data` event per email found. Default: false.",
            "default": false
          },
          "maxConcurrency": {
            "title": "Max parallel tasks",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many (keyword × location) searches run in parallel, e.g. `2` to go gentler on rate limits or `8` to finish a wide sweep faster. Allowed range 1–10. Default: 4.",
            "default": 4
          },
          "maxRequestRetries": {
            "title": "Max request retries",
            "minimum": 0,
            "type": "integer",
            "description": "Per-page retry budget on rate-limit / network errors, e.g. `12` on a flaky proxy. Each retry rotates the proxy exit IP. Set `0` to fail a page on the first error. Default: 8.",
            "default": 8
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Defaults to Apify Proxy (datacenter) for cheap IP rotation — the Houzz mobile API has no WAF, so residential proxies are not needed. Override here to use a different Apify group or your own proxy URLs. Default: `{ \"useApifyProxy\": true }`.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}