HomeAdvisor APIhomeadvisor.com ↗
Search HomeAdvisor contractors by category, retrieve detailed profiles with ratings and reviews, and fetch project photo albums via 5 structured endpoints.
What is the HomeAdvisor API?
The HomeAdvisor API exposes 5 endpoints for discovering and evaluating home service professionals. Starting with search_pros, you can query by free-text or category slug and receive paginated listings that include business names, locations, review counts, average ratings, and sponsorship status. From there, drill into individual profiles for structured business data, full review text, and project photo albums.
curl -X GET 'https://api.parse.bot/scraper/6b97d8f1-e78d-47b0-a453-5837fa1c7bac/search_pros?page=1&limit=5&query=plumbing&zip_code=90210&category_slug=plumbing' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for home service professionals by category, optionally scoped to a US ZIP code. A free-text query is resolved to a HomeAdvisor category via autocomplete; alternatively a category_slug from get_categories is resolved via its directory page (one extra page fetch). Either query or category_slug must be provided; an unknown slug returns stale_input. Results are server-paginated via page/limit (one request per page). When zip_code is omitted the site chooses the search area itself (reported in zip_codes); when supplied, results are the professionals serving that ZIP and zip_codes echoes it. A ZIP the site does not recognize returns an empty results array with result_count 0.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| limit | integer | Maximum number of results per page. |
| query | string | Free-text search for a service category (e.g. 'plumbing', 'HVAC', 'roofing'). Either query or category_slug is required. |
| zip_code | string | 5-digit US ZIP code (leading zeros preserved) to scope results to professionals serving that location. Omit to let the site pick the search area. |
| category_slug | string | Category slug from get_categories categories[*].slug (e.g. 'plumbing'), used directly without autocomplete resolution. Either query or category_slug is required. |
{
"type": "object",
"fields": {
"page": "current page number",
"limit": "results per page",
"results": "array of professional listings with id, legacyId, profileUrl, businessName, city, state, postalCode, reviewCount, averageOverallRating, isSponsored, and more",
"search_id": "unique search session identifier",
"zip_codes": "array of ZIP codes defining the search area (the supplied zip_code when given, otherwise the site's default area)",
"result_count": "total number of matching professionals"
},
"sample": {
"data": {
"page": 1,
"limit": 5,
"results": [
{
"id": "005211d4-0f61-1583-e063-3383030a2c13",
"city": "Van Nuys",
"state": "CA",
"legacyId": "95507597",
"postalCode": "91411",
"profileUrl": "/rated.GMCPlumbingInc.95507597.html",
"isSponsored": true,
"reviewCount": 86,
"businessName": "G M C Plumbing, Inc.",
"logoPhotoUrl": "https://cdn.homeadvisor.com/files/eid/95500000/95507597/12008941_logo.jpg",
"freeEstimates": true,
"yearsInBusiness": 7,
"emergencyServices": true,
"businessDescription": "We re dedicated to providing our clients with the very best in service, installation, and repair for all phases of your plumbing needs.",
"averageOverallRating": 4.889534884
}
],
"search_id": "03cdacff-3e72-4a57-a5bb-617bcc319cd4",
"zip_codes": [
"90210"
],
"result_count": 1147
},
"status": "success"
}
}About the HomeAdvisor API
Search and Discovery
The search_pros endpoint accepts either a query string (resolved through autocomplete) or a direct category_slug. Responses include an array of professional listings, each carrying fields such as id, legacyId, profileUrl, businessName, city, state, reviewCount, averageOverallRating, and a sponsorship flag. Pagination is controlled via page and limit parameters. The search_id and zip_codes fields in the response identify the search session and geographic scope.
Category Navigation
Before searching, you can enumerate all available service categories with get_categories, which returns slug and name pairs suitable for passing directly to search_pros as category_slug. For more targeted lookups, search_categories accepts a free-text query and returns autocomplete suggestions typed as either CATEGORY or TASK, each with an id, name, and srPathUrl for service request routing.
Professional Profiles and Reviews
get_pro_details takes a profile_url from search_pros results and returns structured data including a business_info object (schema.org LocalBusiness format with name, address, and aggregateRating) plus an array of reviews, each with reviewBody, reviewRating, datePublished, and author. This is the endpoint to use when you need full review text rather than just aggregate scores.
Project Photos
get_pro_photos accepts the legacyId from search results and returns an albums array. Each album object includes albumId, albumName, imageCount, featuredImage, and an images array of individual photo URLs. This lets you surface a contractor's past project portfolio alongside their ratings and business information.
The HomeAdvisor API is a managed, monitored endpoint for homeadvisor.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when homeadvisor.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official homeadvisor.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a contractor comparison tool that ranks pros by
averageOverallRatingandreviewCountwithin a specific category slug. - Aggregate full review text from
get_pro_detailsto run sentiment analysis on home service professionals in a given city and state. - Populate a local services directory with business names, addresses, and aggregate ratings sourced from
search_prosandget_pro_details. - Display project photo galleries using
get_pro_photosalbum data alongside contractor profiles in a home renovation app. - Map contractor coverage areas by extracting
zip_codesandcity/statefields returned bysearch_pros. - Generate a category taxonomy for a home services platform by enumerating all slugs and display names from
get_categories. - Monitor review volume changes over time for specific pros by periodically calling
get_pro_detailsand trackingreviewCountanddatePublishedvalues.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does HomeAdvisor have an official developer API?+
What does `search_pros` return beyond basic business listings?+
search_pros returns a results array where each entry includes id, legacyId, profileUrl, businessName, city, state, reviewCount, averageOverallRating, and a sponsorship indicator. The response also includes a search_id, a zip_codes array scoping the results geographically, and a result_count for the total match set. It does not return full review text — use get_pro_details with the profileUrl for that.Can I filter `search_pros` results by location or ZIP code?+
search_pros endpoint accepts query or category_slug for filtering, along with page and limit for pagination. It does not expose a direct ZIP code or radius filter parameter. The zip_codes field in the response reflects the search area inferred from the query, but cannot be set explicitly. You can fork the API on Parse and revise it to add a location parameter to the endpoint.Does the API return contractor pricing or cost estimates?+
How are reviews structured in `get_pro_details`, and are all reviews returned?+
get_pro_details returns a reviews array where each object contains reviewBody, reviewRating, datePublished, and author. The data reflects what is available on the profile page. The endpoint does not currently expose pagination for reviews, so very prolific profiles may return a capped set rather than every historical review.