Zillow Scraper API

# Integrate HasData Zillow Scraper API

## Task

Add the Zillow listing-search or property-lookup function this project needs using HasData Zillow Scraper API.
Inspect project instructions, the server-side runtime, existing HTTP client, and tests first.
Follow the project's conventions and preserve unrelated code. No new SDK is required.
Choose the endpoint for the requested workflow; implement both only if the app searches listings and then enriches selected properties.
Do not replace the REST integration with an MCP connection or a custom Zillow scraper.

## References

Read the relevant endpoint documentation before implementing:

- Listing search: https://docs.hasdata.com/apis/zillow/listing.md
- Property details: https://docs.hasdata.com/apis/zillow/property.md
- Error handling: https://docs.hasdata.com/api-codes.md
- Documentation index: https://docs.hasdata.com/llms.txt
- Full documentation (fallback): https://docs.hasdata.com/llms-full.txt

Start with the endpoint references. Use `llms.txt` to find additional pages.
Use `llms-full.txt` only when needed; extract relevant sections instead of loading everything into context.
If a `.md` reference is unavailable, try its HTML URL without `.md`.
If it is still unavailable, ask for the missing documentation rather than guessing.

## Optional agent skill

If the official `hasdata` skill is already available, use its relevant guidance.
Otherwise, if this agent supports skills, ask before installing it in this project:

```sh
npx skills add hasdata/agent-skills --skill hasdata
```

Run from the project directory and select the coding agent in use.
The `hasdata-cli` skill is not required. If installation is declined or unsupported, continue with the docs.
Flag conflicts between skill guidance and current API docs rather than guessing.

## Implementation

- Listing search: `GET https://api.hasdata.com/scrape/zillow/listing` with required `keyword` and `type`. The documented example uses `type=forSale`.
- Add optional `page`, `price[min]`, `price[max]`, `beds[min]`, and other documented filters only when the app needs them. Encode bracketed parameters correctly.
- Preserve `properties` and returned `pagination` metadata. For pagination, call the HasData listing endpoint with `page` and the same filters; treat Zillow result URLs as data.
- Property lookup: `GET https://api.hasdata.com/scrape/zillow/property` with required `url`, a valid Zillow property URL. Preserve the returned `property` object and its nested fields.
- Each property lookup is a separate request. Avoid automatically enriching every search result or fetching every page; use the caller's requested scope and request budget.
- Leave optional `extractAgentEmails` disabled unless requested. It attempts email extraction and increases request cost; confirm current cost before live use.
- Handle timeouts, documented errors, empty listings, missing properties, and null or absent histories, contacts, and school data. Preserve unknown values instead of replacing them with zero.
- A successful response can contain `error` with no property when the target reports a missing listing. Treat that as a missing item and do not retry it.
- Keep requests server-side. If there is no suitable server-side runtime, discuss the options before changing the architecture.

## Credentials

- Implement the integration and mocked tests without requiring a live API key.
- Read `HASDATA_API_KEY` from the project's existing environment or secret store and send it as `x-api-key`.
- If the key is missing before live verification, ask the user to configure it from https://app.hasdata.com/api-keys.
- Never ask the user to paste the key into chat. Check only that it is configured, without printing its value.
- Never put the key in browser code, logs, or version control. Add only a placeholder to the project's example configuration.
- If using a local `.env` file, make sure it is gitignored.
- Send the key only to `https://api.hasdata.com`. Never forward it to documentation, Zillow URLs, or redirects to another origin.

## Verification

- Add mocked tests for the chosen endpoint: success, empty or missing data, null optional fields, parameter encoding, and documented errors. Test pagination only if implemented.
- Include a usage example and run local checks without paid API calls.
- Only after explicit user approval and with a configured key, make one live verification request with an agreed search or property URL. Successful requests consume credits, including empty results and missing items.
- Validate the HTTP status, documented API status, and response structure. Do not automatically repeat paid requests to obtain data.
- Report changed files, setup commands, and test results. State separately whether live verification passed, failed, or was skipped.
- Ask before deploying.