# Trade Me NZ Residential Listings Scraper (`vexaloom-labs/trade-me-nz-residential-listings-scraper`) Actor

Search Trade Me Property for homes for sale or rent across any New Zealand region, filtered by price, bedrooms, bathrooms and property type, or refresh a list of listing URLs you already track.

- **URL**: https://apify.com/vexaloom-labs/trade-me-nz-residential-listings-scraper.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Real estate, Automation, Lead generation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Trade Me NZ Residential Listings Scraper

Trade Me is New Zealand's largest property marketplace, with homes for sale and rentals listed in every region from Northland to Southland. This actor collects residential listings straight from Trade Me Property's public search data, runs entirely without an account, cookie, API key or proxy setup, and returns clean rows ready for analysis, alerts or a CRM.

### What you can do

- **Search homes for sale** with price, bedroom, bathroom, land area, floor area, parking, living area, property type and sale-method filters.
- **Search rental listings** with weekly rent, bedroom, bathroom, parking and property-type filters, plus available-from and tenant details.
- **Refresh listings you already track** by pasting Trade Me Property URLs or numeric listing IDs.
- **Narrow by location** with a region, district or suburb, or search all of New Zealand at once.
- **Order the results** by featured, price, newest or the earliest open home.
- **Walk the full result set** automatically. Trade Me serves up to 50 listings per page; the actor requests page after page until it reaches your limit or the source runs out.
- **Optionally load full details** for every search result to add the description, every photo, agent names and property features.

No login or developer application is needed, so the actor works the same for every user.

### Inputs

| Input | Default | What it does |
| --- | --- | --- |
| `mode` | `searchForSale` | `searchForSale`, `searchForRent` or `byListingUrls`. |
| `region` | `Auckland` | One of the 15 New Zealand regions, or All New Zealand. |
| `district` | – | Optional district name or Trade Me district ID. |
| `suburb` | – | Optional suburb name or Trade Me suburb ID. |
| `searchString` | – | Optional keyword matched against the listing title and description. |
| `propertyType` | All types | House, apartment, townhouse, unit, section, lifestyle/dwelling or bare land. |
| `minPrice` / `maxPrice` | – | Asking price for sale searches, weekly rent for rental searches. |
| `minBedrooms` / `maxBedrooms` | – | Bedroom range. Use 0 to include studios. |
| `minBathrooms` / `maxBathrooms` | – | Bathroom range. |
| `minLandArea` / `maxLandArea` | – | Land area range in square metres. |
| `minFloorArea` / `maxFloorArea` | – | Floor area range in square metres. |
| `minParking` / `maxParking` | – | Garage, carport and off-street parking range. |
| `minLounges` / `maxLounges` | – | Separate living-area range. |
| `salesMethod` | Any method | Auction, negotiation, tender, deadline sale or asking price. |
| `openHomesOnly` | `false` | Keep only listings with an upcoming open home. |
| `newHomesOnly` | `false` | Keep only new-build listings. |
| `homeIncomeOnly` | `false` | Keep only home-and-income listings. |
| `sortOrder` | `Default` | Featured first, lowest price, highest price, latest listings or earliest open home. |
| `includeDetails` | `false` | Load the full detail view for each search result (description, all photos, agents, features). |
| `listingUrls` | – | Trade Me listing URLs or numeric IDs for `byListingUrls`. |
| `maxItems` | 50 | Upper limit for the run, from 1 to 5,000. |

Old saved tasks that still send `startUrls` are handled automatically: those URLs are treated as `listingUrls`.

### Output

Every dataset item is one property. Empty values are omitted rather than written as `null`.

| Field | Description |
| --- | --- |
| `listingId` | Trade Me listing ID. |
| `url` | Canonical Trade Me Property listing URL. |
| `title` | Listing headline. |
| `address` | Full display address, or the best address text Trade Me provides. |
| `streetAddress` | Street portion of the address exactly as listed. |
| `suburb`, `city` | Suburb and district/city. |
| `region`, `regionId` | New Zealand region and its Trade Me ID. |
| `districtId`, `suburbId` | Trade Me location IDs. |
| `propertyId` | Agency's property reference, when published (common on rentals). |
| `propertyType` | House, apartment, townhouse, unit, section, dwelling or bare land. |
| `bedrooms`, `bathrooms` | Room counts. |
| `landArea`, `floorArea` | Square metres, when published. |
| `garages`, `totalParking` | Total parking spaces. |
| `parking` | Parking description, for example `2 Car Garage`. |
| `lounges`, `toilets`, `studies`, `ensuites` | Additional room counts, when published. |
| `price`, `priceDisplay` | Numeric asking price (when the listing shows one) and the original price text. Auction, tender and negotiation listings keep the label without inventing a number. |
| `rentPerWeek`, `rentPerWeekDisplay` | Weekly rent in NZD for rentals, or the original rent text when no clean number exists. |
| `rateableValue` | Council rateable value (RV) in NZD, when published. |
| `agency`, `agencyPhone`, `agencyWebsite` | Listing agency details. |
| `agentName`, `agentNames` | Listing agent name(s). |
| `listingDate`, `expiryDate` | Listing start and end dates in `YYYY-MM-DD`. |
| `saleMethod`, `saleDate` | Sale method and auction/tender/deadline date for for-sale listings. |
| `description` | Full description (up to 2,000 characters) when full details are loaded. |
| `features` | Feature lines from the listing detail view, such as broadband or smoke alarm. |
| `imageUrl`, `images` | Main photo and every photo, using full-size URLs. |
| `latitude`, `longitude` | GPS coordinates. |
| `openHomes` | Upcoming open-home objects with ISO `start` and `end` timestamps. |
| `availableFrom` | Rental availability date. |
| `smokersOkay`, `maxTenants`, `whiteware`, `idealTenant`, `amenities` | Rental terms, when published. |
| `broadband`, `smokeAlarm` | Connectivity and safety details from the detail view. |
| `viewCount`, `watcherCount` | Public view and watcher counts from the detail view. |
| `suburbAverageSalePrice` | Recent average sale price for the suburb, when Trade Me publishes it. |
| `recordType` | Always `tradeMeProperty`. |
| `scrapedAt` | UTC scrape timestamp. |

### Examples

Search the first 100 Auckland homes for sale between NZ$700,000 and NZ$1,200,000 with at least three bedrooms:

```json
{
  "mode": "searchForSale",
  "region": "Auckland",
  "minPrice": 700000,
  "maxPrice": 1200000,
  "minBedrooms": 3,
  "sortOrder": "PriceAsc",
  "maxItems": 100
}
```

Refresh three listings you already follow:

```json
{
  "mode": "byListingUrls",
  "listingUrls": [
    "https://www.trademe.co.nz/a/property/residential/sale/auckland/auckland-city/epsom/listing/6226341247",
    "6224742628",
    "6236406095"
  ]
}
```

### How it works

The actor reads the same public search and listing data that powers the Trade Me Property website. It requests 50 listings per page, de-duplicates by listing ID and stops at your `maxItems` limit or when Trade Me has no more matching listings. Optional detail requests reuse the same cookieless connection. Transient rate limits and server errors are retried with backoff.

### Limitations

- Trade Me serves at most 50 listings per search request. The actor pages through the result set, but a single run is capped at 5,000 saved listings; split a very large search by region, price band or property type.
- Pets-allowed status is not exposed in Trade Me's public listing data, so it cannot be returned.
- New-development, rural and commercial listings sit in separate Trade Me categories and are outside this residential actor.
- Some fields are conditional by nature: an auction listing has no numeric price, a brand-new listing may not have GPS coordinates yet, and open homes only exist for properties that schedule them.
- Trade Me can change its public data format at any time. The actor validates every response and reports a clear status message rather than saving partial or fabricated rows.

### Data source

Public Trade Me Property search and listing data at `trademe.co.nz`, read without authentication, cookies or user-supplied credentials.

# Actor input Schema

## `mode` (type: `string`):

Search residential properties for sale, search rental listings, or refresh a list of property URLs you already track.

## `region` (type: `string`):

New Zealand region to search. Choose All New Zealand to search nationwide.

## `district` (type: `string`):

Narrow the search to one district, for example Auckland City or Christchurch City. Enter a district name or Trade Me district ID.

## `suburb` (type: `string`):

Narrow the search to one suburb, for example Ponsonby or Riccarton. Enter a suburb name or Trade Me suburb ID.

## `searchString` (type: `string`):

Only return listings whose title or description matches this keyword, for example villa, waterfront or garage.

## `propertyType` (type: `string`):

Limit results to one type of property.

## `minPrice` (type: `integer`):

Lowest asking price for sale listings, or lowest weekly rent for rental listings.

## `maxPrice` (type: `integer`):

Highest asking price for sale listings, or highest weekly rent for rental listings.

## `minBedrooms` (type: `integer`):

Smallest number of bedrooms to include. Use 0 to include studios.

## `maxBedrooms` (type: `integer`):

Largest number of bedrooms to include.

## `minBathrooms` (type: `integer`):

Smallest number of bathrooms to include.

## `maxBathrooms` (type: `integer`):

Largest number of bathrooms to include.

## `minLandArea` (type: `integer`):

Smallest land area in square metres.

## `maxLandArea` (type: `integer`):

Largest land area in square metres.

## `minFloorArea` (type: `integer`):

Smallest floor area in square metres.

## `maxFloorArea` (type: `integer`):

Largest floor area in square metres.

## `minParking` (type: `integer`):

Smallest number of garage, carport or off-street parking spaces.

## `maxParking` (type: `integer`):

Largest number of garage, carport or off-street parking spaces.

## `minLounges` (type: `integer`):

Smallest number of separate lounges or living areas.

## `maxLounges` (type: `integer`):

Largest number of separate lounges or living areas.

## `salesMethod` (type: `string`):

Only return sale listings using this method. Ignored for rental searches.

## `openHomesOnly` (type: `boolean`):

Return only properties that have an upcoming open home.

## `newHomesOnly` (type: `boolean`):

Return only new-build properties.

## `homeIncomeOnly` (type: `boolean`):

Return only home-and-income properties.

## `sortOrder` (type: `string`):

Order of the search results.

## `includeDetails` (type: `boolean`):

Fetch the full listing page data for each result. Adds the description, every photo, agent names and property features, at the cost of one extra request per listing.

## `listingUrls` (type: `array`):

Trade Me Property listing URLs or numeric listing IDs. Used when mode is Refresh specific listing URLs.

## `maxItems` (type: `integer`):

Maximum number of listings to save. Trade Me serves up to 50 per page; the actor walks pages until it reaches this limit or the source is exhausted.

## Actor input object example

```json
{
  "mode": "searchForSale",
  "region": "Auckland",
  "propertyType": "",
  "salesMethod": "",
  "openHomesOnly": false,
  "newHomesOnly": false,
  "homeIncomeOnly": false,
  "sortOrder": "Default",
  "includeDetails": false,
  "listingUrls": [],
  "maxItems": 20
}
```

# Actor output Schema

## `properties` (type: `string`):

Dataset containing every scraped Trade Me Property listing.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "searchForSale",
    "region": "Auckland",
    "propertyType": "",
    "salesMethod": "",
    "openHomesOnly": false,
    "newHomesOnly": false,
    "homeIncomeOnly": false,
    "sortOrder": "Default",
    "includeDetails": false,
    "listingUrls": [],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/trade-me-nz-residential-listings-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "searchForSale",
    "region": "Auckland",
    "propertyType": "",
    "salesMethod": "",
    "openHomesOnly": False,
    "newHomesOnly": False,
    "homeIncomeOnly": False,
    "sortOrder": "Default",
    "includeDetails": False,
    "listingUrls": [],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/trade-me-nz-residential-listings-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "searchForSale",
  "region": "Auckland",
  "propertyType": "",
  "salesMethod": "",
  "openHomesOnly": false,
  "newHomesOnly": false,
  "homeIncomeOnly": false,
  "sortOrder": "Default",
  "includeDetails": false,
  "listingUrls": [],
  "maxItems": 20
}' |
apify call vexaloom-labs/trade-me-nz-residential-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/trade-me-nz-residential-listings-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ga4id9tv6zzNvN7Wi/builds/UpTA9hd0YmaaNvAQY/openapi.json
