# HomeGuide Scraper (`crawlerbros/homeguide-scraper`) Actor Scrape public HomeGuide.com home-services professional directory and provider profile pages. Extract business name, address, geo, ratings, reviews, services, payment methods, and operating hours from US local home-service pros (cleaning, plumbing, HVAC, contractors, electricians, landscaping, etc.). - **URL**: https://apify.com/crawlerbros/homeguide-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 22 bookmarks - **User rating**: 5.00 out of 5 stars ## 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ## HomeGuide Scraper Scrape **HomeGuide.com** — the public US home-services pro directory — for business profiles, ratings, reviews, contact info, services offered, and operating hours. Built for marketers, lead-gen analysts, real-estate teams, and home-services aggregators who need clean, structured data on local contractors and service pros. > **Coverage**: 50 US states + DC, 80+ home-service categories > (cleaning, plumbing, HVAC, electricians, landscaping, contractors, > roofing, etc.), thousands of cities. Public data only — no login, > no cookies, no auth. ### What this actor does This scraper visits HomeGuide listing pages (national category, or state/city-scoped) and individual provider profile pages, then emits a flat dataset of pros with their structured business data. It uses HomeGuide's own JSON-LD `LocalBusiness` and `ItemList` schema markup as the primary source of truth, plus the embedded `app-page-state` JSON for richer details (lat/lng, operating hours, listed services). ### Input modes | Mode | What you provide | What you get | |---|---|---| | **By URLs** | A list of HomeGuide URLs (provider profiles, category pages, or city pages) | Records for each URL — full provider profile if it's a profile URL, paginated listings if it's a directory page | | **By category** | A category slug (e.g. `house-cleaning`); optionally a state + city | Top providers for that category nationally, or filtered to a city | | **By location** | A US state code (e.g. `ca`); optionally a city slug and category | All pros listed for that location | ### Input fields - **mode** — `byUrls`, `byCategory`, or `byLocation` - **urls** — direct HomeGuide URLs (used when `mode=byUrls`) - **category** — one of 80+ predefined service category slugs - **stateCode** — two-letter US state code (50 states + DC) - **city** — lowercase, hyphenated city slug (e.g. `los-angeles`, `new-york`) - **maxItems** — global cap on emitted records (default 25, max 1000) - **maxPagesPerListing** — paginated listing pages to crawl per seed URL (HomeGuide returns ~10 pros per page) - **fetchProfileDetails** — when on, visits each provider's profile page for richer data (full address, hours, reviews, services) - **maxReviewsPerProfile** — cap on reviews kept per provider - **useProxy** — route through Apify proxy (HomeGuide is normally reachable from datacenter IPs without a proxy) - **autoEscalateOnBlock** — automatically retry with exponential backoff on 503/Cloudflare challenges - **proxyConfiguration** — Apify proxy configuration object (only used when `useProxy=true`); leave at the default to let Apify pick groups ### Output fields Every record includes (when available — empty fields are dropped): | Field | Type | Description | |---|---|---| | `title` | string | Business name | | `category` | string | HomeGuide category slug (from URL) | | `city`, `state` | string | Listing geography (from URL) | | `streetAddress`, `postalCode`, `fullAddress` | string | Mailing address | | `latitude`, `longitude` | number | Geo coordinates | | `phoneNumber` | string | Public business phone | | `websiteUrl` | string | Provider website (when published) | | `ratingValue`, `reviewCount` | number | Aggregate rating + count | | `numberOfEmployees` | number | Self-reported team size | | `paymentAccepted` | array | Listed payment methods | | `servicesOffered` | array | Listed service offerings | | `socialLinks` | array | Linked social-profile URLs | | `imageUrl` | string | Profile image | | `hours` | array | Per-day open/close blocks; `openHHMM`/`closeHHMM` are HHMM ints (e.g. `1700` = 17:00) | | `reviews` | array | Up to `maxReviewsPerProfile` reviews with rating, text, author, date | | `breadcrumb` | array | HomeGuide breadcrumb names | | `canonicalUrl`, `profileUrl`, `sourceUrl` | string | Canonical URLs | | `providerSlug` | string | Last URL-path segment of the profile | | `siteName` | string | Always `HomeGuide` | | `recordType` | string | Always `pro` | | `scrapedAt` | string | ISO-8601 UTC timestamp | ### FAQs **Does this scraper require login or cookies?** No. HomeGuide profiles and category listings are fully public. **Will it work without a proxy?** Yes. HomeGuide does not aggressively block datacenter IPs. You can enable Apify proxy via the input switch if you do see 503s. **How many pros per listing page?** ~10 LocalBusiness items per page. Use `maxPagesPerListing` to deepen coverage for a given category/location. **Why are some fields missing on some pros?** Different providers fill in different optional fields on their HomeGuide profiles. The scraper drops empty fields rather than emitting `null`/`""`. **Does the actor scrape costs/articles pages?** No. This actor focuses on the pro directory. Cost-guide URLs under `/costs/` will be ignored. **Is this scraper compliant with HomeGuide's robots.txt?** HomeGuide's robots.txt disallows internal-only paths (`/pros`, `/admin/`, `/lead`, etc.). The directory and profile URLs this actor crawls are **explicitly allowed**. ### Daily test prefill The default `INPUT.json` runs a small `byCategory` scrape (`house-cleaning` in NY/Brooklyn, max 5 records, 1 listing page) which reliably returns ≥1 record on Apify's daily test runs. # Actor input Schema ## `mode` (type: `string`): Which discovery axis to use. byUrls: direct URLs. byCategory: a category page (national or state/city scoped). byLocation: a US state or state+city, optionally narrowed by category. ## `urls` (type: `array`): Direct HomeGuide URLs (category, location, or provider profile). ## `category` (type: `string`): Home-service category slug. Required for byCategory; optional for byLocation. ## `stateCode` (type: `string`): Two-letter US state code; required when mode=byLocation. ## `city` (type: `string`): Lowercase, hyphenated city slug (e.g. 'new-york', 'los-angeles', 'brooklyn'). Optional; if blank, scrapes the state-level page. ## `maxItems` (type: `integer`): Hard cap on emitted records. ## `maxPagesPerListing` (type: `integer`): Maximum paginated listing pages (?page=N) to crawl per category/location URL. HomeGuide returns ~10 pros per page. ## `fetchProfileDetails` (type: `boolean`): Fetch each provider's profile page for richer data (address, hours, services, full reviews). Adds 1 HTTP request per provider. ## `maxReviewsPerProfile` (type: `integer`): Max reviews to keep on each provider record (when fetchProfileDetails=true). ## `useProxy` (type: `boolean`): Route HTTP requests through Apify proxy. HomeGuide is generally accessible without a proxy from datacenter IPs; enable only if you see 503s. ## `autoEscalateOnBlock` (type: `boolean`): If a 503/Cloudflare challenge appears, automatically retry with a fresh proxy session and a delay. ## `proxyConfiguration` (type: `object`): Apify proxy configuration. Used only when useProxy is enabled. ## Actor input object example ```json { "mode": "byCategory", "urls": [ "https://homeguide.com/ny/brooklyn/carpet-cleaning/jayway-carpet--upholstery-cleaning-services" ], "category": "house-cleaning", "stateCode": "ny", "city": "brooklyn", "maxItems": 5, "maxPagesPerListing": 3, "fetchProfileDetails": true, "maxReviewsPerProfile": 20, "useProxy": false, "autoEscalateOnBlock": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [] } } ```` # Actor output Schema ## `pros` (type: `string`): Dataset containing HomeGuide pro records. # 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 = { "mode": "byCategory", "urls": [ "https://homeguide.com/ny/brooklyn/carpet-cleaning/jayway-carpet--upholstery-cleaning-services" ], "category": "house-cleaning", "stateCode": "ny", "city": "brooklyn", "maxItems": 5, "maxPagesPerListing": 3, "fetchProfileDetails": true, "maxReviewsPerProfile": 20, "useProxy": false, "autoEscalateOnBlock": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [] } }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/homeguide-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 = { "mode": "byCategory", "urls": ["https://homeguide.com/ny/brooklyn/carpet-cleaning/jayway-carpet--upholstery-cleaning-services"], "category": "house-cleaning", "stateCode": "ny", "city": "brooklyn", "maxItems": 5, "maxPagesPerListing": 3, "fetchProfileDetails": True, "maxReviewsPerProfile": 20, "useProxy": False, "autoEscalateOnBlock": True, "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": [], }, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/homeguide-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 '{ "mode": "byCategory", "urls": [ "https://homeguide.com/ny/brooklyn/carpet-cleaning/jayway-carpet--upholstery-cleaning-services" ], "category": "house-cleaning", "stateCode": "ny", "city": "brooklyn", "maxItems": 5, "maxPagesPerListing": 3, "fetchProfileDetails": true, "maxReviewsPerProfile": 20, "useProxy": false, "autoEscalateOnBlock": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [] } }' | apify call crawlerbros/homeguide-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/homeguide-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "HomeGuide Scraper", "description": "Scrape public HomeGuide.com home-services professional directory and provider profile pages. Extract business name, address, geo, ratings, reviews, services, payment methods, and operating hours from US local home-service pros (cleaning, plumbing, HVAC, contractors, electricians, landscaping, etc.).", "version": "1.0", "x-build-id": "cct74yHJ5fgYjG44p" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~homeguide-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-homeguide-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/crawlerbros~homeguide-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-homeguide-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/crawlerbros~homeguide-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-homeguide-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": "Scrape mode", "enum": [ "byUrls", "byCategory", "byLocation" ], "type": "string", "description": "Which discovery axis to use. byUrls: direct URLs. byCategory: a category page (national or state/city scoped). byLocation: a US state or state+city, optionally narrowed by category.", "default": "byCategory" }, "urls": { "title": "URLs (byUrls mode)", "type": "array", "description": "Direct HomeGuide URLs (category, location, or provider profile).", "default": [], "items": { "type": "string" } }, "category": { "title": "Category (byCategory / byLocation modes)", "enum": [ "", "appliance-repair", "architects", "artificial-turf-installation", "asphalt-pavers", "basement-remodeling", "bathroom-remodeling", "cabinet-makers", "carpenters", "carpet-cleaning", "central-air-conditioning-installation", "central-air-conditioning-repair", "chimney-cleaning", "cleaning-services", "computer-repair", "concrete-contractors", "construction-companies", "countertop-installation", "deck-and-porch-build", "dog-boarding", "dog-grooming", "dog-training", "door-installation", "dryer-repair", "dryer-vent-cleaning", "drywall-repair", "duct-cleaning", "electrical-repair", "electricians", "excavating-contractors", "exterior-painting", "fence-installation", "fence-repair", "flooring-installation", "furnace-repair", "furniture-repair", "garage-door-repair", "general-contractors", "gutter-cleaning", "gutter-installation", "handyman", "hardwood-floor-installation", "hardwood-floor-refinishing", "home-improvement", "home-inspectors", "home-remodeling", "home-repair", "house-cleaning", "house-foundation-repair-contractors", "hvac-companies", "hvac-installation", "hvac-repair", "insulation-contractors", "interior-designers", "interior-painting", "kitchen-remodeling", "land-surveyors", "landscaping", "lawn-care", "lawn-mowing", "locksmiths", "masonry-contractors", "moving-companies", "new-home-building", "painting-contractors", "patios", "pest-control", "plumbers", "plumbing-repair", "pressure-washing", "roof-repair", "roofing", "septic-tank-cleaning", "siding-contractors", "solar-panel-installation", "sprinkler-systems-repair", "swimming-pool-cleaning", "swimming-pool-repair", "tile-installation", "tree-removal", "tree-trimming", "waste-and-junk-removal", "window-cleaning", "window-installation", "window-repair" ], "type": "string", "description": "Home-service category slug. Required for byCategory; optional for byLocation.", "default": "house-cleaning" }, "stateCode": { "title": "US state (byLocation mode)", "enum": [ "", "ak", "al", "ar", "az", "ca", "co", "ct", "dc", "de", "fl", "ga", "hi", "ia", "id", "il", "in", "ks", "ky", "la", "ma", "md", "me", "mi", "mn", "mo", "ms", "mt", "nc", "nd", "ne", "nh", "nj", "nm", "nv", "ny", "oh", "ok", "or", "pa", "ri", "sc", "sd", "tn", "tx", "ut", "va", "vt", "wa", "wi", "wv", "wy" ], "type": "string", "description": "Two-letter US state code; required when mode=byLocation.", "default": "ny" }, "city": { "title": "City slug (byLocation mode)", "type": "string", "description": "Lowercase, hyphenated city slug (e.g. 'new-york', 'los-angeles', 'brooklyn'). Optional; if blank, scrapes the state-level page.", "default": "brooklyn" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on emitted records.", "default": 25 }, "maxPagesPerListing": { "title": "Max listing pages", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum paginated listing pages (?page=N) to crawl per category/location URL. HomeGuide returns ~10 pros per page.", "default": 3 }, "fetchProfileDetails": { "title": "Fetch profile details", "type": "boolean", "description": "Fetch each provider's profile page for richer data (address, hours, services, full reviews). Adds 1 HTTP request per provider.", "default": true }, "maxReviewsPerProfile": { "title": "Max reviews per profile", "minimum": 0, "maximum": 200, "type": "integer", "description": "Max reviews to keep on each provider record (when fetchProfileDetails=true).", "default": 20 }, "useProxy": { "title": "Use Apify proxy", "type": "boolean", "description": "Route HTTP requests through Apify proxy. HomeGuide is generally accessible without a proxy from datacenter IPs; enable only if you see 503s.", "default": false }, "autoEscalateOnBlock": { "title": "Auto-escalate on block", "type": "boolean", "description": "If a 503/Cloudflare challenge appears, automatically retry with a fresh proxy session and a delay.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy configuration. Used only when useProxy is enabled.", "default": { "useApifyProxy": true, "apifyProxyGroups": [] } } } }, "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 } } } } } } } } } } ```