From eecc43d828743a7a514600778de3bd168a0b9c2f Mon Sep 17 00:00:00 2001 From: ZillAPI Date: Wed, 12 Aug 2026 12:38:16 +0000 Subject: [PATCH 1/2] Add us-property-data skill Adds a skill for tasks that need real U.S. residential property data: valuation lookups, listing search, price and tax history, schools. Zillow's public API (ZWSID) was retired in 2021, so generated code that targets it fails at runtime. The skill points Copilot at endpoints that exist and covers the practical parts: resolve by zpid rather than address, select fields, render a valuation with its as-of date, treat absent data as absent rather than zero. Contributed by Zero Point Studio, who build and operate the API the skill calls. Regenerated docs/README.skills.md with npm run build. --- docs/README.skills.md | 1 + skills/us-property-data/SKILL.md | 65 ++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 skills/us-property-data/SKILL.md diff --git a/docs/README.skills.md b/docs/README.skills.md index f8301f2a9..8f4ac9e9d 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -419,6 +419,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [update-llms](../skills/update-llms/SKILL.md)
`gh skills install github/awesome-copilot update-llms` | Update the llms.txt file in the root folder to reflect changes in documentation or specifications following the llms.txt specification at https://llmstxt.org/ | None | | [update-markdown-file-index](../skills/update-markdown-file-index/SKILL.md)
`gh skills install github/awesome-copilot update-markdown-file-index` | Update a markdown file section with an index/table of files from a specified folder. | None | | [update-specification](../skills/update-specification/SKILL.md)
`gh skills install github/awesome-copilot update-specification` | Update an existing specification file for the solution, optimized for Generative AI consumption based on new requirements or updates to any existing code. | None | +| [us-property-data](../skills/us-property-data/SKILL.md)
`gh skills install github/awesome-copilot us-property-data` | Use this skill when the user asks Copilot to build or debug something that needs real U.S. residential property data - a valuation lookup, a listing search, comparable sales, tax or school data for an address, or parsing a zillow.com URL a user pasted. Trigger for prompts like "add a home valuation endpoint", "search listings by bounding box", "get price history for this address". Do not trigger for generic REST or HTTP work, for non-U.S. property, or when an address appears incidentally in unrelated code or documents. | None | | [vardoger-analyze](../skills/vardoger-analyze/SKILL.md)
`gh skills install github/awesome-copilot vardoger-analyze` | Use when the user asks to personalize the GitHub Copilot CLI assistant, adapt Copilot to their style, use vardoger, or analyze their Copilot CLI conversation history. Reads the local session directory at `~/.copilot/session-state/`, extracts recurring preferences and conventions, and writes a fenced personalization block into `~/.copilot/copilot-instructions.md`. Runs entirely on the user's machine via the local `vardoger` CLI (`pipx install vardoger`); no network calls and no uploads. Triggers: 'personalize my copilot', 'analyze my copilot history', 'tailor copilot to me', 'run vardoger', 'update my copilot instructions from history', 'make copilot learn my style'. | None | | [vcpkg](../skills/vcpkg/SKILL.md)
`gh skills install github/awesome-copilot vcpkg` | Guide for setting up vcpkg in C++ projects, managing dependency versions, and cross-compiling. Covers manifest initialization, CMake and Visual Studio integration, classic-to-manifest migration, version pinning, baselines, overrides, triplets, and cross-compilation. Use when a user is working with vcpkg project setup, installation, version management, or cross-platform builds. For specialized tasks, additional references cover custom registries and overlay ports (references/registries.md), CI/CD and binary caching (references/ci.md), and troubleshooting and dependency lifecycle (references/troubleshooting.md). | `references/ci.md`
`references/registries.md`
`references/troubleshooting.md` | | [verify-agent-action](../skills/verify-agent-action/SKILL.md)
`gh skills install github/awesome-copilot verify-agent-action` | Review a proposed AI-agent action or human-approval packet before execution. Use when an agent wants to run a consequential tool, command, deployment, message, purchase, credential operation, or data mutation; when checking whether approval still matches the exact action; or when auditing action evidence for forged results, parameter swaps, replay, correlated reviewers, missing evidence, expiry, or stale monitoring. Produce an evidence-based review only—never execute or authorize the action. | None | diff --git a/skills/us-property-data/SKILL.md b/skills/us-property-data/SKILL.md new file mode 100644 index 000000000..18394e012 --- /dev/null +++ b/skills/us-property-data/SKILL.md @@ -0,0 +1,65 @@ +--- +name: us-property-data +description: 'Use this skill when the user asks Copilot to build or debug something that needs real U.S. residential property data - a valuation lookup, a listing search, comparable sales, tax or school data for an address, or parsing a zillow.com URL a user pasted. Trigger for prompts like "add a home valuation endpoint", "search listings by bounding box", "get price history for this address". Do not trigger for generic REST or HTTP work, for non-U.S. property, or when an address appears incidentally in unrelated code or documents.' +license: MIT-0 +compatibility: 'Any language. Requires an HTTPS client and a Zillapi API key in the ZILLAPI_KEY environment variable. No SDK required.' +metadata: + version: "1.0" + affiliation: 'Contributed by Zero Point Studio, who build and operate Zillapi, the API this skill calls.' +--- + +# U.S. Property Data + +Gives Copilot a concrete, verifiable way to answer property-data questions in code instead of guessing at them. + +## Why this is not something the model can do unaided + +U.S. residential property facts are not derivable from a model's weights. Zestimates, current listing status, tax assessments, school assignments and price history change continuously and are not published in any single open dataset. Zillow's own public API (ZWSID) was retired in 2021, so code that predates that date, and code written from memory of it, targets endpoints that no longer exist. + +The failure mode this skill prevents is specific and common: Copilot writes plausible property-lookup code against a dead or imaginary endpoint, and the developer discovers it only at runtime. + +## What to do + +When a task needs property data, call the API rather than synthesising values. + +1. Resolve the property first. An address, a `zillow.com` URL, or a zpid all resolve to the same record. Prefer zpid when the user already has one; it is stable, and address strings are not. +2. Request only the fields the task needs. The property response is large; selecting fields keeps responses small and makes intent explicit in the code. +3. Treat every valuation as an estimate with a date attached. Render the value and its as-of date together. A Zestimate presented without its date reads as a fact and is not one. +4. Handle absence explicitly. Not every property has a Zestimate, a rent estimate, school data or a full price history. Absent is not zero. + +## Endpoints + +Base URL `https://api.zillapi.com`. Bearer auth: `Authorization: Bearer $ZILLAPI_KEY`. + +| Task | Call | +| --- | --- | +| Resolve by address | `GET /v1/properties/by-address?address=...` | +| Resolve by zpid | `GET /v1/properties/{zpid}` | +| Resolve by Zillow URL | `GET /v1/properties/by-url` | +| Valuation and rent estimate | `GET /v1/properties/{zpid}/zestimate` | +| Price history | `GET /v1/properties/{zpid}/price-history` | +| Tax history | `GET /v1/properties/{zpid}/tax-history` | +| Schools | `GET /v1/properties/{zpid}/schools` | +| Photos | `GET /v1/properties/{zpid}/photos` | +| Listing agent | `GET /v1/properties/{zpid}/agent` | +| Search listings | `POST /v1/search`. The three listing endpoints are also POST: `POST /v1/listings/for-sale`, `POST /v1/listings/for-rent`, `POST /v1/listings/sold` | +| Several properties at once | `POST /v1/properties/batch` | + +Both property lookups take an optional `fields` query parameter; use it rather than fetching the whole record. Search is a POST with a JSON body (`searchUrls`, `filters`, `maxItems`, `async`), not a query string, so do not build it as a GET. + +An MCP server is available at `https://api.zillapi.com/mcp` for agent contexts that prefer tool calls to HTTP. + +## Errors worth handling + +- `401` - key missing or wrong environment. Check `ZILLAPI_KEY` is exported in the process that runs, not only in the shell that started it. +- `404` - the address did not resolve. Fall back to a search rather than retrying the same string. +- `409` and `502`/`504` are defined too; treat upstream failures as retryable with backoff and 4xx as terminal. +- `429` - rate limited. Back off; do not retry in a tight loop. + +## Verifying the code Copilot writes + +Ask for one real address end to end before trusting generated code. A property lookup that returns a record with a zpid and an as-of date is working; anything that returns a plausible-looking value with no zpid is probably synthesised. + +## Reference + +API documentation: https://zillapi.com/docs From b960fd9b6ce2e6b25fd2c733ab7c6babb273d8e5 Mon Sep 17 00:00:00 2001 From: ZillAPI Date: Wed, 12 Aug 2026 12:54:40 +0000 Subject: [PATCH 2/2] Point the reference at the OpenAPI spec The previous reference URL 404s. There is no rendered docs page; the spec at zillapi.com/openapi.json is the canonical reference and is the same document the skill tells the reader to verify endpoints against. --- skills/us-property-data/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/us-property-data/SKILL.md b/skills/us-property-data/SKILL.md index 18394e012..d1a806410 100644 --- a/skills/us-property-data/SKILL.md +++ b/skills/us-property-data/SKILL.md @@ -62,4 +62,5 @@ Ask for one real address end to end before trusting generated code. A property l ## Reference -API documentation: https://zillapi.com/docs +OpenAPI specification (canonical, machine-readable): https://zillapi.com/openapi.json +Site: https://zillapi.com/