# Trade Me Property Sale Search API Documentation

Search residential property for sale on Trade Me (New Zealand). Filter by price, bedrooms, bathrooms, property type, region, district, suburb and keyword, sort the results and page through them with page and rows. Each listing returns id, url, title, price text, price, dates in ISO 8601 UTC, location, bedrooms, bathrooms, areas, parking, photos, agency and open homes when present. Use the localities endpoint to find region, district and suburb ids. total_count can be an approximate count. A valid search with no hits returns an empty listings list and is a successful, billable response.

- **Documentation:** [https://scrappa.co/docs/trademe-property-api/trademe_property_search_sale](https://scrappa.co/docs/trademe-property-api/trademe_property_search_sale)
- **API group:** Trade Me Property API
- **Endpoint:** `GET https://scrappa.co/api/trademe_property/search_sale`

## 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 |
| --- | --- | --- | --- |
| `page` | integer | No | Page number, 1-based. Defaults to 1. |
| `rows` | integer | No | Listings per page, 1 to 100. Defaults to 22. |
| `price_min` | integer | No | Minimum price in NZD. |
| `price_max` | integer | No | Maximum price in NZD. |
| `bedrooms_min` | integer | No | Minimum number of bedrooms. |
| `bedrooms_max` | integer | No | Maximum number of bedrooms. |
| `bathrooms_min` | integer | No | Minimum number of bathrooms. |
| `property_type` | string | No | Property type slug, for example house, apartment, unit or townhouse. Unknown values are ignored by Trade Me. |
| `region` | integer | No | Region id from the localities endpoint, e.g. 15 for Wellington. |
| `district` | integer | No | District id from the localities endpoint, e.g. 47 for Wellington city. |
| `suburb` | string | No | One or more suburb ids from the localities endpoint, separated by commas, e.g. 53,57. |
| `search_string` | string | No | Free-text keyword search, up to 100 characters, e.g. beach. |
| `sort_order` | string | No | Default, PriceAsc, PriceDesc, ExpiryDesc or EarliestOpenHome. Defaults to Default. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/trademe_property/search_sale?region=15&district=47&rows=2"
```

## Example response

```json
{
    "success": true,
    "data": {
        "total_count": 956,
        "page": 1,
        "page_size": 2,
        "has_more": true,
        "listings": [
            {
                "id": 6048028595,
                "url": "https://www.trademe.co.nz/a/listing/6048028595",
                "title": "Pure magic on The Crescent",
                "category": "For Sale",
                "property_type": "House",
                "price_text": "Price by negotiation",
                "start_date": "2026-07-23T08:08:27Z",
                "end_date": "2026-10-31T19:43:27Z",
                "region": "Wellington",
                "district": "Wellington",
                "suburb": "Roseneath",
                "address": "51 The Crescent",
                "location": {
                    "latitude": -41.290889,
                    "longitude": 174.8002205
                },
                "bedrooms": 4,
                "bathrooms": 2,
                "floor_area_sqm": 315,
                "land_area_sqm": 407,
                "image_url": "https://trademe.tmcdn.co.nz/photoserver/thumb/2327656526.jpg",
                "photo_urls": [
                    "https://trademe.tmcdn.co.nz/photoserver/thumb/2327656528.jpg",
                    "https://trademe.tmcdn.co.nz/photoserver/thumb/2327656532.jpg"
                ],
                "agency": "Luxe Realty, (Licensed: REAA 2008)",
                "open_homes": [
                    {
                        "start": "2026-10-18T00:30:00Z",
                        "end": "2026-10-18T01:00:00Z"
                    }
                ],
                "is_featured": true,
                "has_video": true
            }
        ]
    },
    "meta": {
        "endpoint_family": "search_sale",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
|  | Error | The listing was not found or has expired. Not billed. |
|  | Error | Trade Me could not be reached. Not billed. |
|  | Error | Trade Me rejected the request. Not billed. |
|  | Error | The upstream service is temporarily unavailable. Please retry shortly. |
|  | Error | Trade Me returned an unexpected payload shape. Not billed. |
|  | Error | Trade Me 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)