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?zip=10001&page=1&limit=5&query=plumbing&category_slug=plumbing' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace homeadvisor-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: HomeAdvisor SDK — find pros, browse categories, view photos."""
from parse_apis.homeadvisor_api import HomeAdvisor, OptionType, ProfileNotFound
client = HomeAdvisor()
# Search for plumbing professionals — limit caps total items fetched.
for pro in client.professionals.search(query="plumbing", limit=3):
print(pro.business_name, pro.city, pro.state, f"rating={pro.average_rating}")
# Drill into one professional's photo albums via sub-resource navigation.
pro = client.professionals.search(category_slug="plumbing", limit=1).first()
if pro:
for album in pro.photos.list(limit=2):
print(album.album_name, f"images={album.image_count}")
# Browse all service categories from the directory.
for cat in client.categories.list(limit=5):
print(cat.slug, cat.name)
# Autocomplete search for category suggestions — filter by type enum.
for suggestion in client.categorysuggestions.search(query="roof", limit=5):
if suggestion.option_type == OptionType.CATEGORY:
print(f"Category: {suggestion.name}")
else:
print(f"Task: {suggestion.name}")
# Typed error handling — catch ProfileNotFound on a bad URL.
try:
detail_pro = client.professional(legacy_id="27223123")
for album in detail_pro.photos.list(limit=1):
print(album.album_name, album.image_count)
except ProfileNotFound as exc:
print(f"Profile gone: {exc.profile_url}")
print("exercised: professionals.search / photos.list / categories.list / categorysuggestions.search")Search for home service professionals by category. Resolves a free-text query to a HomeAdvisor category via autocomplete, then returns paginated professional listings with business info, ratings, reviews, and contact details. Either query or category_slug must be provided. Results are server-paginated via page/limit.
| 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. |
| category_slug | string | Category slug to search directly without autocomplete resolution (e.g. 'plumbing'). 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, reviewCount, averageOverallRating, isSponsored, and more",
"search_id": "unique search session identifier",
"zip_codes": "array of ZIP codes for the search area",
"result_count": "total number of matching professionals"
},
"sample": {
"data": {
"page": 1,
"limit": 5,
"results": [
{
"id": "005211d2-b2ef-1583-e063-3383030a2c13",
"city": "West Jordan",
"state": "UT",
"legacyId": "27223123",
"postalCode": "84081",
"profileUrl": "/rated.ValleyPlumbingandDrain.27223123.html",
"isSponsored": true,
"reviewCount": 688,
"businessName": "Valley Plumbing Heating & Cooling",
"logoPhotoUrl": "https://cdn.homeadvisor.com/files/eid/27220000/27223123/2963604_logo.jpg",
"freeEstimates": true,
"yearsInBusiness": 15,
"emergencyServices": true,
"businessDescription": "Valley Plumbing and Drain, Inc...",
"averageOverallRating": 4.4
}
],
"search_id": "abc123",
"zip_codes": [
"84057",
"84059"
],
"result_count": 379
},
"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 | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. 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.