Homes.co.nz Listing API returns one sale or rental listing: headline, full description, price text, rooms, floor and land area, address with coordinates, photos with captions, the site's estimate and rental estimate, council values, agents, agency, council zone and fibre status. Send the id from a search item or the url of the listing page. Sale prices are often words such as Auction: display_price holds the text and price is null. Values the site does not know are null, never 0. Sold and off market properties have no listing: use the property route with their property_id. An unknown listing is a 404. Failed requests are not billable.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
2 optional filters available.
string
Optional
Listing id (UUID) from a search item. One of id or url is required.
1234567890
string
Optional
Address or path of the listing page, for example /auckland/auckland-central/15i-16-gore-street/V8rAq. Only homes.co.nz addresses are accepted.
https://example.com/product
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
data
meta
success
{
"data": {
"id": "c06b7c16-aaa6-401b-804b-6b69a10aaf94",
"url": "https://homes.co.nz/auckland/auckland-central/15i-16-gore-street/V8rAq",
"pets": null,
"fibre": {
"stage": "P3 UFB",
"status": "Complete"
},
"price": null,
"agency": {
"id": "645814a2-983b-49ae-9372-7f58729a7dce",
"url": "https://homes.co.nz/branch/645814a2-983b-49ae-9372-7f58729a7dce",
"logo": "https://trademe.tmcdn.co.nz/tm/property/agent_logos/2436274-8.jpg",
"name": "City",
"brand": "Barfoot & Thompson",
"phone": "+64-9-3076340",
"banner": "https://trademe.tmcdn.co.nz/tm/property/agent_logos/office_branding/2436274-office_branding-1.jpg"
},
"agents": [
{
"id": "a77e78d2-fc9a-4c56-8857-85439405b744",
"url": "https://homes.co.nz/agent/a77e78d2-fc9a-4c56-8857-85439405b744",
"name": "Livia Li",
"photo": "https://trademe.tmcdn.co.nz/tm/property/agent_individual_profile/agent_individual_profile7183277v1.jpg",
"is_team": false,
"agency_id": "645814a2-983b-49ae-9372-7f58729a7dce",
"mobile_phone": "027 560 9668",
"office_phone": "09 377 8810"
},
{
"id": "c70b20ad-d505-44a1-a855-84137e28b810",
"url": "https://homes.co.nz/agent/c70b20ad-d505-44a1-a855-84137e28b810",
"name": "Alan Guo",
"photo": "http://blobmedia.barfoot.co.nz/exporter/r3/images/6v201.jpg",
"is_team": false,
"agency_id": "645814a2-983b-49ae-9372-7f58729a7dce",
"mobile_phone": "021 609 668",
"office_phone": "09 307 9278"
}
],
"images": [
{
"url": "https://s3-ap-southeast-2.amazonaws.com/homes-listing-images/10856235613838489947",
"caption": null
},
{
"url": "https://s3-ap-southeast-2.amazonaws.com/homes-listing-images/16294004191975335895",
"caption": null
},
{
"url": "https://s3-ap-southeast-2.amazonaws.com/homes-listing-images/1707874309907757046",
"caption": null
}
],
"values": {
"as_of": "2024-05-01",
"land_value": 60000,
"capital_value": 85000,
"improvement_value": 25000
},
"videos": [],
"address": {
"city": "Auckland",
"full": "15i/16 Gore Street, City Centre, Auckland City, Auckland",
"unit": "15I",
"street": "Gore Street",
"suburb": "Auckland Central",
"street_number": "16"
},
"parking": null,
"bedrooms": 1,
"currency": "NZD",
"estimate": {
"as_of": "2026-10-15",
"value": null,
"low_text": "85K",
"high_text": "95K",
"value_text": "90K"
},
"headline": "Cash Cow in Britomart",
"bathrooms": 1,
"listed_at": "2026-10-25T19:30:53.193Z",
"car_spaces": null,
"open_homes": [],
"updated_at": "2026-10-25T19:31:02.26391Z",
"coordinates": {
"latitude": -36.846027,
"longitude": 174.768845
},
"description": "Auction: 34 Shortland Street, City on Wednesday 18 November 2026 at 10:00AM (unless sold prior)\r\n\r\nAttention Cash Buyers & Equity Investors: The vendor's instructions are clear\u2014this property must be sold, and she is ...",
"furnishings": null,
"max_tenants": null,
"price_known": false,
"property_id": "9bbfc9b9-9103-42d0-a119-30fcdca3f40e",
"available_at": null,
"council_zone": "Business - City Centre Zone",
"decade_built": "2000",
"listing_type": "sale",
"price_period": null,
"display_price": "Auction on 18 Nov, 10:00\u202fam",
"land_area_sqm": null,
"property_type": "Apartment",
"floor_area_sqm": 26,
"ownership_type": "Unit Title",
"rental_estimate": {
"as_of": "2026-10-02",
"yield": "19.6%",
"low_text": "310",
"high_text": "370"
},
"smokers_allowed": null
},
"meta": {
"billable": true,
"endpoint_family": "listing"
},
"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": {
"id": [
"The id field is required when url is not present."
]
},
"message": "The request validation failed"
}Not Found
The listing does not exist or is not on the market any more. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "listing"
},
"error": {
"code": "NOT_FOUND",
"message": "The requested record was not found."
},
"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": "listing"
},
"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.