# Homes.co.nz Property History API Documentation

<p><strong>Homes.co.nz Property History API</strong> returns the record of one property: land use, legal description, rooms and areas, council valuation, the site's estimate and rental estimate, the timeline of past sales, council valuations and build date, and the estimate history of the property, its suburb and its city with a growth forecast. It works for sold and off market properties too. Get <code>property_id</code> from a search item or an address in the autocomplete route. <code>month_limit</code> sets how many months of estimate history are returned (36 by default). A property without estimate history returns empty lists. An unknown property is a 404. Failed requests are not billable.</p>

- **Documentation:** [https://scrappa.co/docs/homes-co-nz-api/homes_co_nz_property](https://scrappa.co/docs/homes-co-nz-api/homes_co_nz_property)
- **API group:** Homes.co.nz API
- **Endpoint:** `GET https://scrappa.co/api/homes-co-nz/property`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `property_id` | string | Yes | Required. Property id (UUID) from a search item or an autocomplete address. |
| `month_limit` | integer | No | Months of estimate history, 1 to 240. Default 36. |

## Example response

```json
{
    "data": {
        "record": {
            "city": {
                "id": 100004,
                "name": "Auckland"
            },
            "suburb": {
                "id": 2728,
                "name": "Auckland Central"
            },
            "bedrooms": 1,
            "estimate": {
                "low": 85000,
                "high": 95000,
                "as_of": "2026-10-15",
                "value": 90000
            },
            "has_deck": true,
            "land_use": "apartment",
            "bathrooms": 1,
            "car_spaces": null,
            "decade_built": 2000,
            "land_area_sqm": null,
            "floor_area_sqm": 26,
            "rental_estimate": {
                "low": 310,
                "high": 370,
                "as_of": "2026-10-02"
            },
            "council_valuation": {
                "as_of": "2024-05-01",
                "land_value": 60000,
                "capital_value": 85000,
                "improvement_value": 25000
            },
            "legal_description": "UNIT 15I UP 366567",
            "certificate_of_title": "269885"
        },
        "timeline": [
            {
                "date": "2024-05-01",
                "type": "valuation",
                "price": null,
                "agency": null,
                "source": "council",
                "land_value": 60000,
                "price_text": null,
                "decade_built": null,
                "capital_value": 85000,
                "improvement_value": 25000
            },
            {
                "date": "2021-06-01",
                "type": "valuation",
                "price": null,
                "agency": null,
                "source": "council",
                "land_value": 105000,
                "price_text": null,
                "decade_built": null,
                "capital_value": 150000,
                "improvement_value": 45000
            },
            {
                "date": "2017-07-01",
                "type": "valuation",
                "price": null,
                "agency": null,
                "source": "council",
                "land_value": 100000,
                "price_text": null,
                "decade_built": null,
                "capital_value": 260000,
                "improvement_value": 160000
            }
        ],
        "property_id": "9bbfc9b9-9103-42d0-a119-30fcdca3f40e",
        "estimate_history": {
            "city": [
                {
                    "low": null,
                    "date": "2023-10-05",
                    "high": null,
                    "estimate": 1106963,
                    "estimate_text": "1.11M"
                },
                {
                    "low": null,
                    "date": "2023-10-20",
                    "high": null,
                    "estimate": 1097177,
                    "estimate_text": "1.1M"
                },
                {
                    "low": null,
                    "date": "2023-11-02",
                    "high": null,
                    "estimate": 1115179,
                    "estimate_text": "1.12M"
                }
            ],
            "suburb": [
                {
                    "low": null,
                    "date": "2023-10-05",
                    "high": null,
                    "estimate": 438592,
                    "estimate_text": "440K"
                },
                {
                    "low": null,
                    "date": "2023-10-20",
                    "high": null,
                    "estimate": 441002,
                    "estimate_text": "440K"
                },
                {
                    "low": null,
                    "date": "2023-11-02",
                    "high": null,
                    "estimate": 448683,
                    "estimate_text": "450K"
                }
            ],
            "forecast": [
                {
                    "date": "2021-04-01",
                    "growth": 0.0067,
                    "growth_low": -0.066,
                    "growth_high": 0.0782
                },
                {
                    "date": "2021-05-01",
                    "growth": 0.0127,
                    "growth_low": -0.0712,
                    "growth_high": 0.094
                },
                {
                    "date": "2021-06-01",
                    "growth": 0.0181,
                    "growth_low": -0.077,
                    "growth_high": 0.1092
                }
            ],
            "property": [
                {
                    "low": 103341,
                    "date": "2023-10-05",
                    "high": 120773,
                    "estimate": 112057,
                    "estimate_text": "110K"
                },
                {
                    "low": 104021,
                    "date": "2023-10-20",
                    "high": 124624,
                    "estimate": 114322,
                    "estimate_text": "115K"
                },
                {
                    "low": 104875,
                    "date": "2023-11-02",
                    "high": 125726,
                    "estimate": 115300,
                    "estimate_text": "115K"
                }
            ]
        }
    },
    "meta": {
        "billable": true,
        "endpoint_family": "property"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable. |
| 404 | Not Found | The property does not exist. This response is not billable. |
| 503 | Upstream Unavailable | Homes.co.nz could not be reached. This response is not billable and is retryable. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)