# Homes.co.nz Search API Documentation

Homes.co.nz Search API returns up to 40 listings per page (20 by default) for sale, rent, sold or off market in New Zealand. Name the area with q (a place such as Ponsonby), a map box bbox or an encoded polygon polyline. A suburb name uses the suburb boundary; a city, street or address uses a box around the place, and search_area tells which one was used. Filter by bedrooms, bathrooms and price, and for sold by sale date. Every item satisfies the filters you sent; items that break a filter are never returned and are counted in excluded_by_filters. Sale prices are often words such as Auction, so the item shows display_price as text and price null; a price filter cannot judge a text without an amount, so such items are kept with price_known false. Bedrooms, bathrooms and areas that the site does not know are null, never 0. The site has no property type, floor area, land area or keyword filter: these parameters are refused with a 422. pagination.total is the number of matches the site reports. A page past the last returns an empty list with the true total. Results are served up to page x per_page = 10000. Failed requests are not billable. A search by q reads the place first and then the listings, and is billed once.

- **Documentation:** [https://scrappa.co/docs/homes-co-nz-api/homes_co_nz_search](https://scrappa.co/docs/homes-co-nz-api/homes_co_nz_search) - **API group:** Homes.co.nz API - **Endpoint:** `GET https://scrappa.co/api/homes-co-nz/search` ## 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 | | --- | --- | --- | --- | | `type` | string | Yes | Required. sale, rent, sold or off_market. For rent the price is per week. An off_market item is a home that is not for sale; price is null and estimate holds the site's estimate. | | `q` | string | No | Place name, 2 to 100 characters, for example Ponsonby or Mt Eden. One of q, bbox or polyline is required. A text no place matches gives a 422. | | `bbox` | string | No | Search area as nw_lat,nw_long,se_lat,se_long, for example -36.83,174.72,-36.87,174.78. The north-west corner lies above and left of the south-east corner. | | `polyline` | string | No | Search area as an encoded polyline (precision 1e5) of a closed polygon. | | `bedrooms_min` | integer | No | Minimum number of bedrooms. Items with unknown bedrooms (null) are kept. | | `bedrooms_max` | integer | No | Maximum number of bedrooms. | | `bathrooms_min` | integer | No | Minimum number of bathrooms. Items with unknown bathrooms (null) are kept. | | `bathrooms_max` | integer | No | Maximum number of bathrooms. | | `price_min` | number | No | Minimum price in NZD (per week for rent). For off_market and sold it filters the sold price or estimate. Items whose price text has no amount, such as Auction, are kept with price_known false. | | `price_max` | number | No | Maximum price in NZD (per week for rent). Same rule as the minimum price. | | `date_min` | string | No | Sold only. First sale day, YYYY-MM-DD, included. | | `date_max` | string | No | Sold only. Last sale day, YYYY-MM-DD, included. | | `sort` | string | No | date lists the newest first. Leave empty for the site order. | | `page` | integer | No | Page number, starting at 1. page x per_page may not pass 10000. | | `per_page` | integer | No | 1 to 40. Default 20. | ## Example response ```json { "data": { "items": [ { "id": "c6bc91fd-e3c9-4ad2-b244-f5f3984d06e6", "url": "https://homes.co.nz/auckland/ponsonby/33-summer-street/zQge8", "date": "2026-10-20T04:04:29.453Z", "price": null, "agency": { "id": "5861fe7e-bbf8-4289-ba5d-cbda27145262", "url": "https://homes.co.nz/branch/5861fe7e-bbf8-4289-ba5d-cbda27145262", "logo": "https://trademe.tmcdn.co.nz/tm/property/agent_logos/4938899-11.jpg", "name": "Ponsonby", "brand": "Bayleys", "phone": "+64-9-3758494", "banner": null }, "agents": [ { "id": "14a4d5d1-7e70-4b22-9152-39db01b9b7b8", "url": "https://homes.co.nz/agent/14a4d5d1-7e70-4b22-9152-39db01b9b7b8", "name": "Dominique Donaghy", "photo": "https://trademe.tmcdn.co.nz/tm/property/agent_individual_profile/agent_individual_profile8133861v2.jpg", "is_team": false, "agency_id": "5861fe7e-bbf8-4289-ba5d-cbda27145262", "mobile_phone": "027 370 0000", "office_phone": "027 3700000" }, { "id": "14a28337-1152-4be1-a465-b0ff23364f81", "url": "https://homes.co.nz/agent/14a28337-1152-4be1-a465-b0ff23364f81", "name": "Sayesha Mehta", "photo": "https://trademe.tmcdn.co.nz/tm/property/agent_individual_profile/agent_individual_profile5990509v1.jpg", "is_team": false, "agency_id": "5861fe7e-bbf8-4289-ba5d-cbda27145262", "mobile_phone": "022 064 8019", "office_phone": "022 064 8019" } ], "images": [ "https://s3-ap-southeast-2.amazonaws.com/homes-listing-images/4289166162229627320", "https://s3-ap-southeast-2.amazonaws.com/homes-listing-images/3323000369903260374", "https://s3-ap-southeast-2.amazonaws.com/homes-listing-images/12109085761073885388" ], "values": { "as_of": "2024-05-01", "land_value": 1625000, "capital_value": 1925000, "improvement_value": 300000 }, "address": { "city": "Auckland", "full": "33 Summer Street, Ponsonby, Auckland City, Auckland", "unit": null, "street": "Summer Street", "suburb": "Ponsonby", "street_number": "33" }, "city_id": 100004, "bedrooms": 4, "currency": "NZD", "estimate": { "as_of": "2026-10-15", "value": null, "low_text": "1.92M", "high_text": "2.16M", "value_text": "2.04M" }, "headline": "Summer starts on Summer Street", "bathrooms": 1, "suburb_id": 1279, "car_spaces": 2, "listing_id": "c6bc91fd-e3c9-4ad2-b244-f5f3984d06e6", "coordinates": { "latitude": -36.851906, "longitude": 174.742615 }, "featured_at": "2026-10-20T04:04:29.453Z", "price_known": false, "property_id": "0ac2316e-7219-4ad7-9238-1bdefcf45eef", "decade_built": "1910", "listing_type": "sale", "price_period": null, "display_price": "Auction on 11 Nov, 2:00\u202fpm", "land_area_sqm": 202, "floor_area_sqm": 126, "ownership_type": "Freehold", "rental_estimate": { "as_of": "2026-10-02", "yield": "2.4%", "low_text": "850", "high_text": "1,020" }, "legal_description": "PT LOT 52 ALLOT 29 SEC 8 SUBURBS AUCKLAND 202M2, PT LOT 55 ALLOT 29 SEC 8 SU" } ], "pagination": { "page": 1, "total": 23, "has_more": true, "per_page": 2 }, "search_area": { "name": "Ponsonby, Auckland", "source": "suburb_boundary" }, "excluded_by_filters": 0 }, "meta": { "billable": true, "endpoint_family": "search" }, "success": true } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Validation Error | A parameter is missing or invalid. This response is not billable. | | 422 | No Place Matched | q matched no place. Send another name or a bbox. 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)