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.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
1 required parameter needed before sending a request.
14 optional filters available.
string
Required
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.
example
string
Optional
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.
coffee shops
string
Optional
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.
example
string
Optional
Search area as an encoded polyline (precision 1e5) of a closed polygon.
example
integer
Optional
Minimum number of bedrooms. Items with unknown bedrooms (null) are kept.
10
integer
Optional
Maximum number of bedrooms.
10
integer
Optional
Minimum number of bathrooms. Items with unknown bathrooms (null) are kept.
10
integer
Optional
Maximum number of bathrooms.
10
number
Optional
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.
10
number
Optional
Maximum price in NZD (per week for rent). Same rule as the minimum price.
10
string
Optional
Sold only. First sale day, YYYY-MM-DD, included.
2026-06-15
string
Optional
Sold only. Last sale day, YYYY-MM-DD, included.
2026-06-15
string
Optional
date lists the newest first. Leave empty for the site order.
relevance
integer
Optional
Page number, starting at 1. page x per_page may not pass 10000.
1
integer
Optional
1 to 40. Default 20.
10
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"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
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A parameter is missing or invalid. This response is not billable.
{
"errors": {
"type": [
"The type field is required."
]
},
"message": "The request validation failed"
}No Place Matched
q matched no place. Send another name or a bbox. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "search"
},
"error": {
"code": "VALIDATION_ERROR",
"message": "No place matched q. Try another name or send a bbox."
},
"success": false
}Upstream Unavailable
Homes.co.nz could not be reached. This response is not billable and is retryable.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "Homes.co.nz could not be reached. Please retry shortly."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.