{
  "openapi": "3.0.1",
  "info": {
    "title": "Houzz Pro Scraper",
    "description": "Scrape Houzz professional directory listings by category, location, keyword, or URL across all 14 Houzz country sites: ratings, reviews, contact info, services, and photos. Export to JSON, CSV, or Excel.",
    "version": "1.1",
    "x-build-id": "R50RBmK6eGMxdkZrK"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/parsebird~houzz-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-parsebird-houzz-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/parsebird~houzz-scraper/runs": {
      "post": {
        "operationId": "runs-sync-parsebird-houzz-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/parsebird~houzz-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-parsebird-houzz-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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "keyword",
              "review",
              "url"
            ],
            "type": "string",
            "description": "search: browse a category + location. keyword: free-text search within a category/location. review: deep-fetch specific pros by URL or username. url: scrape any pasted Houzz directory URL.",
            "default": "search"
          },
          "site": {
            "title": "Country site",
            "enum": [
              "houzz.com",
              "houzz.com.au",
              "houzz.co.nz",
              "houzz.co.uk",
              "houzz.ie",
              "houzz.de",
              "houzz.fr",
              "houzz.it",
              "houzz.es",
              "houzz.dk",
              "houzz.se",
              "houzz.com.sg",
              "houzz.in",
              "houzz.jp"
            ],
            "type": "string",
            "description": "Which Houzz country site to search. All 14 work on the default proxy setting.",
            "default": "houzz.com"
          },
          "category": {
            "title": "Category",
            "type": "string",
            "description": "Service category, mapped to that country site's own Houzz category (used in modes search and keyword). Bathroom remodels are under kitchen-and-bath-remodelers. Asking for a category a site does not have stops the run and lists the ones it does.",
            "default": "interior-designers"
          },
          "locations": {
            "title": "Locations",
            "type": "array",
            "description": "Format: City--State, City--Country, or just a State/Region (e.g. New-York--NY, Sydney--NSW). Empty = all locations for the category.",
            "items": {
              "type": "string"
            }
          },
          "queries": {
            "title": "Keywords",
            "type": "array",
            "description": "Free-text keywords for mode 'keyword'. Each one runs as its own search, matched client-side against each pro's name, about-me text, and category (Houzz has no server-side keyword search for the directory, so this narrows results after fetching — a broad category/location with a high Max pages gives keyword matching more to search through).",
            "items": {
              "type": "string"
            }
          },
          "proUrls": {
            "title": "Pro profile URLs or usernames",
            "type": "array",
            "description": "For mode 'review': full Houzz pro profile URLs, or bare Houzz usernames (the part after houzz.com/pro/ in a profile's public link). Fetches full profile details for each.",
            "items": {
              "type": "string"
            }
          },
          "urls": {
            "title": "Houzz URLs",
            "type": "array",
            "description": "For mode 'url': any Houzz professional-directory search URL, or a single pro profile URL.",
            "items": {
              "type": "string"
            }
          },
          "maxPages": {
            "title": "Max pages per search",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of result pages to fetch per search/location/keyword combination. 15 pros per page.",
            "default": 5
          },
          "maxListings": {
            "title": "Max listings",
            "minimum": 0,
            "type": "integer",
            "description": "Total cap across all searches (still bounded by Max pages too). 0 = unlimited. This is the number of billed 'Result' events.",
            "default": 0
          },
          "minRating": {
            "title": "Min rating",
            "minimum": 0,
            "maximum": 5,
            "type": "integer",
            "description": "Only keep pros with a review rating at or above this (0-5). Applied after fetching, since Houzz's directory has no server-side rating filter.",
            "default": 0
          },
          "minReviewCount": {
            "title": "Min review count",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep pros with at least this many reviews. Applied after fetching.",
            "default": 0
          },
          "verifiedOnly": {
            "title": "Verified only",
            "type": "boolean",
            "description": "Only keep pros with a paid/claimed Houzz business profile.",
            "default": false
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "default",
              "rating-desc",
              "review-count-desc",
              "newest",
              "name-asc"
            ],
            "type": "string",
            "description": "Reorders results after a full scan of Max pages (applied client-side; Houzz's own result order is used when left as default).",
            "default": "default"
          },
          "fetchDetails": {
            "title": "Fetch pro detail pages",
            "type": "boolean",
            "description": "Visit each pro's own profile page for richer fields: services provided, areas served, cost estimate, and rating breakdown by aspect. Always on in Review mode. Triggers the optional Enrichment billing event per pro.",
            "default": false
          },
          "resumeFromRunId": {
            "title": "Resume from run ID",
            "type": "string",
            "description": "Paste a previous run's ID (or its dataset ID) to continue it — this run skips every pro already collected there and only fetches what's still missing."
          },
          "incrementalMode": {
            "title": "Incremental mode",
            "type": "boolean",
            "description": "For a search you run on a schedule against the same category/location/query: remembers what the search returned last time and classifies each pro as NEW, UPDATED, UNCHANGED, REAPPEARED, or EXPIRED. Off by default, so existing scheduled runs are unaffected.",
            "default": false
          },
          "stateKey": {
            "title": "Incremental mode baseline name",
            "type": "string",
            "description": "Optional name for the Incremental mode baseline. Leave empty to auto-derive one from mode/site/category/locations/queries/filters, so two differently-configured searches never share a baseline by accident."
          },
          "emitUnchanged": {
            "title": "Emit unchanged rows",
            "type": "boolean",
            "description": "Also push rows for pros that are unchanged since the last Incremental mode run. Bills an extra Result event (plus Enrichment if Fetch pro detail pages is on) per unchanged row pushed.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit expired rows",
            "type": "boolean",
            "description": "Push a synthetic row for pros that dropped out of a fully-scanned search (only possible after a run that scanned every page of every search with nothing capping or interrupting it). Bills an extra Result event per expired row pushed.",
            "default": false
          },
          "requestDelayMs": {
            "title": "Request delay (ms)",
            "minimum": 0,
            "type": "integer",
            "description": "Delay between requests, in milliseconds.",
            "default": 300
          },
          "maxRequestRetries": {
            "title": "Max retries",
            "minimum": 0,
            "type": "integer",
            "description": "Retries per request on network errors.",
            "default": 5
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "The default works on any plan for all 14 country sites. Residential is optional and recommended only for very large runs.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}