# realestate.co.nz Locations API Documentation

List every New Zealand region with its districts and suburbs and their numeric ids. Pass the ids as region, district and suburb to the search endpoints. The list is large and changes rarely, so Scrappa serves it from a 24 hour cache.

- **Documentation:** [https://scrappa.co/docs/realestate-co-nz-api/realestate_co_nz_locations](https://scrappa.co/docs/realestate-co-nz-api/realestate_co_nz_locations)
- **API group:** realestate.co.nz API
- **Endpoint:** `GET https://scrappa.co/api/realestate-co-nz/locations`

## 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.

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/realestate-co-nz/locations"
```

## Example response

```json
{
    "success": true,
    "data": {
        "regions": [
            {
                "id": 34,
                "name": "Northland",
                "slug": "northland",
                "districts": [
                    {
                        "id": 220,
                        "name": "Far North",
                        "slug": "far-north",
                        "suburbs": [
                            {
                                "id": 1419,
                                "name": "Ahipara",
                                "slug": "ahipara"
                            },
                            {
                                "id": 3826,
                                "name": "Awanui",
                                "slug": "awanui"
                            }
                        ]
                    },
                    {
                        "id": 221,
                        "name": "Kaipara",
                        "slug": "kaipara",
                        "suburbs": [
                            {
                                "id": 1858,
                                "name": "Arapohue",
                                "slug": "arapohue"
                            },
                            {
                                "id": 3846,
                                "name": "Dargaville",
                                "slug": "dargaville"
                            }
                        ]
                    }
                ]
            },
            {
                "id": 35,
                "name": "Auckland",
                "slug": "auckland",
                "districts": [
                    {
                        "id": 225,
                        "name": "Auckland City",
                        "slug": "auckland-city",
                        "suburbs": [
                            {
                                "id": 3095,
                                "name": "Auckland Central",
                                "slug": "auckland-central"
                            },
                            {
                                "id": 153,
                                "name": "Avondale",
                                "slug": "avondale"
                            }
                        ]
                    },
                    {
                        "id": 224,
                        "name": "Franklin",
                        "slug": "franklin",
                        "suburbs": [
                            {
                                "id": 499,
                                "name": "Aka Aka",
                                "slug": "aka-aka"
                            },
                            {
                                "id": 783,
                                "name": "Ararimu",
                                "slug": "ararimu"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "meta": {
        "endpoint_family": "locations",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | Error | page times rows is above 10000. Narrow the search. Not billed. |
|  | Error | The listing, agent or office does not exist. Not billed. |
|  | Error | realestate.co.nz could not be reached. Not billed. |
|  | Error | realestate.co.nz refused the request. Not billed. |
|  | Error | The upstream service is temporarily unavailable. Please retry shortly. |
|  | Error | realestate.co.nz returned an unexpected payload shape. Not billed. |
|  | Error | realestate.co.nz rejected the request parameters. Not billed. |

## 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)