# Homeadvisor — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and discover home service professionals on HomeAdvisor, browse their reviews and project photos, and explore available service categories to find the right contractor for your needs. Get detailed information about specific pros including their expertise, ratings, and past work samples.

**Category:** Business Directories | **Website:** [homeadvisor.com/](https://homeadvisor.com/) | **Docs:** [parse.bot/marketplace/585e3918-b0b3-40e7-a0a5-4edbf2e3ebd6/homeadvisor-com-api](https://parse.bot/marketplace/585e3918-b0b3-40e7-a0a5-4edbf2e3ebd6/homeadvisor-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/homeadvisor/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get categories

Get all service categories from the HomeAdvisor near-me directory. Returns category slugs and display names for use with search_pros category_slug parameter.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/homeadvisor/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get pro details

Get detailed information about a professional including business info, address, aggregate rating, and individual reviews. Data is extracted from the profile page's structured JSON-LD. Use the profileUrl value returned by search_pros.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `profile_url` | string | Yes | Profile URL path from search_pros results[*].profileUrl (e.g. '/rated.ValleyPlumbingandDrain.27223123.html'). Can be a relative path or full URL. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/homeadvisor/get-pro-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"profile_url":"<string>"}'
```

### Get pro photos

Get photo albums and images for a professional. Each album contains metadata and a list of image URLs. Use the legacyId value returned by search_pros.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `legacy_id` | string | Yes | Legacy numeric ID of the professional from search_pros results[*].legacyId (e.g. '27223123'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/homeadvisor/get-pro-photos \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"legacy_id":"<string>"}'
```

### Search categories

Search for service categories and tasks using autocomplete. Returns matching categories (optionType CATEGORY) and tasks (optionType TASK) with IDs and service request paths.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query for category autocomplete (e.g. 'plumbing', 'roof', 'electric'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/homeadvisor/search-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Search pros

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | No | Category slug to search directly without autocomplete resolution (e.g. 'plumbing'). Either query or category_slug is required. |
| `limit` | integer | No | Maximum number of results per page. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Free-text search for a service category (e.g. 'plumbing', 'HVAC', 'roofing'). Either query or category_slug is required. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/homeadvisor/search-pros \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_slug":"<string>","limit":"<integer>","page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.