---
name: property-data
description: "Given a UK postcode plus property attributes (type, bedrooms, area), return structured market data — comparable sold prices, asking-price baselines, demand index, rental yield, and growth signals — for valuation and negotiation workflows."
---

# Property Data

Outcome: given a UK postcode and property attributes, return structured market evidence — comparables, asking prices, sold prices, demand, yield, growth — so the valuer composes a valuation brief and the negotiator backs an offer position with numbers, not prose.

## When to use

Trigger phrases:
- "comps for [address|postcode]"
- "what are properties going for in [postcode]"
- "demand in [postcode]"
- "yield on [bedrooms]-bed in [postcode]"
- "asking prices around [postcode]"
- "what's it worth — [postcode], [type], [beds]"
- "sold prices on [street|postcode]"
- "growth in [postcode]"
- "£/sqft in [postcode]" / "price per square foot in [postcode]"
- "£/sqft growth in [postcode]"
- "crime in [postcode|town]"
- "flood risk for [postcode]"
- "council tax band for [postcode]"
- "planning applications near [postcode]"
- "what's the UPRN of [address]"
- "rental demand in [postcode]"
- "property-type mix in [postcode]"

## Inputs required

- **Postcode** — UK outcode (e.g. `SN7`) or full postcode (e.g. `SN7 8AA`). The PropertyData endpoints accept either; outcode broadens the sample, full postcode tightens it.
- **Property type** — one of: `detached`, `semi-detached`, `terraced`, `flat`. Required for valuation and price-distribution endpoints.
- **Bedrooms** — integer. Required for valuation and yield endpoints.
- **Internal area (sq ft)** — required for `valuation-sale` and `valuation-rent` point estimates. If unknown, fall back to `prices` / `prices-rent` for a distribution and state the area assumption.

## Tools

| Tool | Use for | Required inputs |
|---|---|---|
| `property-data-valuation-sale` | Point sale-price estimate | postcode, type, bedrooms, bathrooms, internal_area |
| `property-data-valuation-rent` | Point rent estimate | postcode, type, bedrooms, bathrooms, internal_area |
| `property-data-prices` | Asking-price distribution (mean / median / 80th pct) | postcode, type, bedrooms |
| `property-data-prices-rent` | Rent asking-price distribution | postcode, type, bedrooms |
| `property-data-sold-prices` | Land Registry sold transactions | postcode (max_age, type, bedrooms optional) |
| `property-data-demand` | Supply count + days to sell-STC | postcode |
| `property-data-yields` | Gross rental yield | postcode, bedrooms |
| `property-data-growth` | Short and long-term price growth | postcode |
| `property-data-national-hpi` | UK national HPI series | (none) |
| `property-data-prices-per-sqf` | Asking £/sqft distribution | postcode (type, bedrooms optional) |
| `property-data-sold-prices-per-sqf` | Achieved £/sqft distribution | postcode (type, bedrooms, max_age optional) |
| `property-data-growth-psf` | 7-year £/sqft series with YoY% | postcode (type optional) |
| `property-data-crime` | Crime rate + breakdown | postcode, or location, or town |
| `property-data-flood-risk` | River + sea flood rating | full postcode |
| `property-data-council-tax` | Council + A–H band charges | full postcode |
| `property-data-planning-applications` | Planning precedent (2 credits/call) | postcode (decision_rating, category, max_age_decision, results optional) |
| `property-data-address-match-uprn` | Address → UPRN (10 credits/call) | address |
| `property-data-demand-rent` | Rental demand signals | postcode (bedrooms, type optional) |
| `property-data-property-types` | Output-area type distribution | postcode |

## Output

Return the structured `data` payload directly to the caller (valuer / negotiator). Do not collapse it to prose — downstream skills (`comparable-finder`, `local-market-stats`, `pricing-scenario-builder`) consume the fields.

## Failure modes

- `Error: key-not-registered` — surface the registration prompt: "PropertyData API key not registered. Register it with `property-data-key-register`."
- `Error: http-4xx` — bad input (usually invalid postcode or unsupported type). Restate the inputs the operator gave; do not retry blindly.
- `Error: http-5xx` — PropertyData upstream outage. Surface the failure and fall back to Loop sold-prices (`loop-property-sold`) if available.
- Empty `data` — the postcode has insufficient comparables. Broaden the postcode (full → outcode) and retry once; if still empty, surface "no PropertyData comparables for this postcode" and let the agent fall back.

## Do not

- Do not compose a valuation figure or asking-price range in this skill — that is the valuer's output contract, composed downstream from the structured data returned here.
- Do not call any endpoint without a postcode argument (except `national-hpi`).
- Do not invent fields not returned by PropertyData. If a field is absent, name it as a gap.
