{
  "openapi": "3.0.1",
  "info": {
    "title": "Houzz Scraper & API - Professionals & Contractor Leads, Phones",
    "description": "Houzz scraper and API: contractor, designer and home-service leads from houzz.com/professionals by category and city or ZIP. One result = one business: name, rating, reviews, phone, address, lat/lng, price level, verified license; website with details. $0.60 per 1,000, the cheapest.",
    "version": "1.0",
    "x-build-id": "4uoHGq33rDK0pcVa9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/rel8ble~houzz-professionals-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-rel8ble-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/rel8ble~houzz-professionals-scraper/runs": {
      "post": {
        "operationId": "runs-sync-rel8ble-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/rel8ble~houzz-professionals-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-rel8ble-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": {
          "categories": {
            "title": "Professional categories",
            "type": "array",
            "description": "Optional. Houzz professional categories, one search per line: \"general contractors\", \"architects\", \"interior designers\", \"kitchen and bath designers\", \"landscape contractors\", \"plumbers\", \"electricians\", \"roofing and gutters\", \"painters\", \"cabinet makers\", \"pool builders\", \"home builders\", \"tile and countertops\", \"tree services\"… Houzz maps close synonyms itself (\"plumber\" -> Plumbers); a name it does not know is skipped and reported, not charged. Empty = all professionals (then give a location or keyword). Every category is searched in every location. Typical: 1-10 lines.",
            "items": {
              "type": "string"
            }
          },
          "locations": {
            "title": "Locations (US and Canada)",
            "type": "array",
            "description": "Optional. Where to search, one per line: \"City, ST\" (\"Charlotte, NC\", \"Austin, TX\"), a US ZIP code (\"28277\") or a Canadian city (\"Toronto, ON\", \"Vancouver, BC\"). Houzz searches a 50-mile radius around the place (its default; not adjustable by URL). Every category is searched in every location (2 categories x 3 cities = 6 searches). Empty = Houzz's nationwide list. A place Houzz does not recognise is skipped and reported, never charged.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "Keywords (optional)",
            "type": "array",
            "description": "Optional. Free-text search inside each category + location, one search per line: \"kitchen remodel\", \"water heater\", \"ADU\", \"pool deck\", a business name. Houzz matches it against the business name, description and services. Empty = everyone in the category. Several keywords multiply the number of searches (2 categories x 2 cities x 3 keywords = 12 searches); duplicates across searches are saved once.",
            "items": {
              "type": "string"
            }
          },
          "minRating": {
            "title": "Minimum star rating",
            "enum": [
              "0",
              "3",
              "4",
              "5"
            ],
            "type": "string",
            "description": "Optional. Keep only businesses rated at least this many stars on Houzz: \"0\" = any (default, includes businesses with no reviews), \"3\", \"4\" or \"5\" (a number works too). Houzz's own filter, so fewer pages are fetched; unrated businesses are left out whenever this is set.",
            "default": "0"
          },
          "priceLevels": {
            "title": "Price levels",
            "type": "array",
            "description": "Optional. Keep only businesses that list one of these price levels ($ = minimise costs … $$$$ = best results). Houzz allows one level per search, so several values run one search each and are merged (any of them). Empty = all, including businesses that list no price level. Every row carries priceLevels either way.",
            "items": {
              "type": "string",
              "enum": [
                "$",
                "$$",
                "$$$",
                "$$$$"
              ],
              "enumTitles": [
                "$ - budget",
                "$$ - low to mid",
                "$$$ - mid to high",
                "$$$$ - high end"
              ]
            }
          },
          "standouts": {
            "title": "Highlights (verified license, hired on Houzz, …)",
            "type": "array",
            "description": "Optional. Keep only businesses with one of these Houzz highlights: \"verifiedLicense\" (Houzz checked the trade licence), \"hiredOnHouzz\", \"locallyOwned\", \"familyOwned\", \"freeConsultation\", \"onlineConsultation\", \"customWork\". One highlight per search on Houzz, so several values run one search each and are merged (any of them). Empty = all. Each row carries highlights and verifiedLicense either way.",
            "items": {
              "type": "string",
              "enum": [
                "verifiedLicense",
                "hiredOnHouzz",
                "locallyOwned",
                "familyOwned",
                "freeConsultation",
                "onlineConsultation",
                "customWork"
              ],
              "enumTitles": [
                "Verified license",
                "Hired on Houzz",
                "Locally owned",
                "Family owned",
                "Free consultation",
                "Online consultation",
                "Offers custom work"
              ]
            }
          },
          "spanishSpeaking": {
            "title": "Spanish-speaking only",
            "type": "boolean",
            "description": "Optional. true = only businesses Houzz marks as \"Speaks Spanish\". Default false.",
            "default": false
          },
          "includeSponsored": {
            "title": "Include sponsored listings",
            "type": "boolean",
            "description": "Optional. Houzz mixes paid \"sponsored\" listings into every results page (the same handful on each page). true (default) = keep them once, with sponsored: true on the row. false = organic results only; sponsored rows are not saved and not charged.",
            "default": true
          },
          "includeDetails": {
            "title": "Include profile details (website, licence number, services)",
            "type": "boolean",
            "description": "Optional. true = also open each business's Houzz profile page and add: website (website, websiteDomain), licenceNumber, servicesProvided, areasServed, awards, estimateDetails, additionalAddresses and profileSuspended. One extra request per business (about 3 a second, pages are large), no extra charge. Default false = directory data only (fast: 15 businesses per request). Turn it on when you need the website for outreach.",
            "default": false
          },
          "maxResults": {
            "title": "Max businesses per search",
            "minimum": 0,
            "type": "integer",
            "description": "Optional. Maximum businesses saved per search (one category in one location, with one keyword), integer >= 0. Default 100; 0 = every business the search can reach. You pay per business saved ($0.0006 each), so 100 businesses = $0.06. Use 10-20 for a quick answer.",
            "default": 100
          },
          "deepSearch": {
            "title": "Deep search past Houzz's 1,499 limit",
            "type": "boolean",
            "description": "Optional. Houzz shows at most 1,499 results (100 pages of 15) for any one search, even when it has more. With deepSearch on (default) and maxResults above 1,499, the actor also runs the same search per rating band, price level, highlight and Spanish-speaking and merges the results without duplicates. Off = at most 1,499 per search.",
            "default": true
          },
          "startUrls": {
            "title": "Houzz URLs",
            "type": "array",
            "description": "Optional. URLs copied from houzz.com, one per line. A category / city page (\"https://www.houzz.com/professionals/general-contractors/c/Charlotte--NC\") is scraped with the filters above. A browse URL with its options (\"…/charlotte-nc-us-rating-4-probr1-bo~t_11786~r_4460243~rg_40\") keeps the category, place, rating, price level and highlight in the URL. A professional's profile URL (\"…/building-impact-llc-pfvwus-pf~96917289\") gives one row with full details.",
            "items": {
              "type": "string"
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Optional, advanced. Number of parallel requests, integer 1-10. Default 4. Requests are also spaced at most 4 a second whatever this is set to. Leave unset.",
            "default": 4
          },
          "maxRequestRetries": {
            "title": "Max retries per request",
            "minimum": 0,
            "maximum": 20,
            "type": "integer",
            "description": "Optional, advanced. How many times a failed request is retried on a new session, integer 0-20. Default 8. Leave unset.",
            "default": 8
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional, advanced. Apify Proxy settings object. Default {\"useApifyProxy\": false}: Houzz answers direct requests, so no proxy is needed. Switch on datacenter proxy only if the run log shows repeated blocks. Leave unset.",
            "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}