> ## Documentation Index
> Fetch the complete documentation index at: https://docs.propaideals.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Price growth endpoint

> Year-on-year price growth for a UK postcode or outcode, computed as the change in median sold price from HM Land Registry data. Required scope areas:read.

# Price growth

Returns year-on-year price growth for a UK postcode or outcode, computed from **HM Land Registry sold prices**. Growth is the percentage change in the median sold price over the last 12 months versus the prior 12 months.

**Required scope:** `areas:read` · **Cost:** 1 request

```http theme={null}
GET /api/v1/growth
```

Authenticate with a paid API key (`Authorization: Bearer paid_your_key`). The endpoint also accepts a logged-in Clerk session when called from the dashboard. Anonymous requests are rejected.

## Query parameters

| Param      | Type   | Default | Description                                                    |
| ---------- | ------ | ------- | -------------------------------------------------------------- |
| `postcode` | string | —       | **Required.** Full postcode or outcode, e.g. `M1` or `M1 4WP`. |

## Request

```bash theme={null}
curl "https://api.propaideals.co.uk/api/v1/growth?postcode=M1" \
  -H "Authorization: Bearer paid_your_key"
```

```python theme={null}
import requests

res = requests.get(
    "https://api.propaideals.co.uk/api/v1/growth",
    params={"postcode": "M1"},
    headers={"Authorization": "Bearer paid_your_key"},
)
growth = res.json()["data"]
print(f"{growth['area']}: {growth['yoy_growth_pct']:+.1f}% YoY")
```

```javascript theme={null}
const res = await fetch(
  "https://api.propaideals.co.uk/api/v1/growth?postcode=M1",
  { headers: { Authorization: "Bearer paid_your_key" } }
);
const { data } = await res.json();
console.log(`${data.area}: ${data.yoy_growth_pct}% YoY`);
```

## Response

```json theme={null}
{
  "data": {
    "area": "M1",
    "yoy_growth_pct": 5.7,
    "median_last_12m": 198500,
    "median_prior_12m": 187800,
    "sample_size": 268,
    "source": "Land Registry sold prices (median, YoY)"
  },
  "meta": {
    "usage": {
      "request_cost": 1,
      "monthly_used": 1435,
      "monthly_limit": 20000
    }
  }
}
```

### Response fields

| Field              | Type    | Description                                                                |
| ------------------ | ------- | -------------------------------------------------------------------------- |
| `area`             | string  | The postcode or outcode the figure was computed for.                       |
| `yoy_growth_pct`   | number  | Percentage change in median sold price, last 12 months vs prior 12 months. |
| `median_last_12m`  | number  | Median sold price over the last 12 months, in £.                           |
| `median_prior_12m` | number  | Median sold price over the preceding 12 months, in £.                      |
| `sample_size`      | integer | Total transactions across both windows.                                    |
| `source`           | string  | Always `Land Registry sold prices (median, YoY)`.                          |

## Methodology & caveats

This figure is the year-on-year change in the **median** sold price for the outcode, not a hedonic or repeat-sales index. Because an outcode median is sensitive to the **mix** of properties that happened to sell in each window, treat single-outcode figures as indicative rather than precise — a quarter heavy with larger detached sales can lift the median without any underlying price movement. Aggregate areas with a low `sample_size` are noisier; widen to the outcode and lean on a longer-running area index where you need a robust trend.