# Homes.co.nz Autocomplete API Documentation

<p><strong>Homes.co.nz Autocomplete API</strong> finds cities, suburbs, streets and addresses by name. Each location has a type (city, suburb, street or address), title, ids, coordinates and, for addresses, the <code>property_id</code> for the property route. <code>search_params</code> holds the parameter that searches the place: <code>q</code> for a suburb, <code>bbox</code> for the others. The box is an approximate area around the point. A text that matches no place returns an empty list. Failed requests are not billable.</p>

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

## 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 |
| --- | --- | --- | --- |
| `q` | string | Yes | Required. Place or address text, 2 to 100 characters. |

## Example response

```json
{
    "data": {
        "locations": [
            {
                "city": "Auckland",
                "type": "suburb",
                "unit": null,
                "title": "Ponsonby, Auckland",
                "street": null,
                "suburb": "Ponsonby",
                "city_id": 100004,
                "latitude": -36.85071676573275,
                "longitude": 174.7405510648527,
                "suburb_id": 1279,
                "property_id": null,
                "search_params": {
                    "q": "Ponsonby, Auckland"
                },
                "street_number": null
            },
            {
                "city": "Auckland",
                "type": "street",
                "unit": null,
                "title": "Ponsonby Road, Ponsonby, Auckland",
                "street": "Ponsonby Road",
                "suburb": "Ponsonby",
                "city_id": 100004,
                "latitude": -36.8521886789864,
                "longitude": 174.74511952436453,
                "suburb_id": 1279,
                "property_id": null,
                "search_params": {
                    "bbox": "-36.8486,174.74063,-36.85578,174.74961"
                },
                "street_number": null
            },
            {
                "city": "Auckland",
                "type": "street",
                "unit": null,
                "title": "Ponsonby Road, Grey Lynn, Auckland",
                "street": "Ponsonby Road",
                "suburb": "Grey Lynn",
                "city_id": 100004,
                "latitude": -36.85764329170246,
                "longitude": 174.7488146529926,
                "suburb_id": 475,
                "property_id": null,
                "search_params": {
                    "bbox": "-36.85405,174.74432,-36.86124,174.75331"
                },
                "street_number": null
            }
        ]
    },
    "meta": {
        "billable": true,
        "endpoint_family": "autocomplete"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. 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)