{
  "openapi": "3.0.1",
  "info": {
    "title": "Trade Me Property Scraper - NZ Listings, Rentals & Agents",
    "description": "Scrape trademe.co.nz property: houses for sale, rentals, lifestyle, rural and commercial listings across New Zealand, with agent contacts and rateable values.",
    "version": "1.0",
    "x-build-id": "Ga2824cFf6qZyUTbm"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~trademe-property-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-trademe-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~trademe-property-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-trademe-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~trademe-property-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-trademe-property-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "operation": {
            "title": "🎯 What do you want to scrape?",
            "enum": [
              "search",
              "detail",
              "agents"
            ],
            "type": "string",
            "description": "Pick one per run. Property Search returns every live listing in the section you choose - houses for sale, rentals, lifestyle blocks, rural, new homes, commercial or retirement - filtered by place, price, bedrooms and size. Listing Detail takes trademe.co.nz listing addresses and returns the full record, including the written description, every photo, the view count and the recent comparable sales Trade Me shows beside it. Agent Directory returns licensed New Zealand agents with their office…",
            "default": "search"
          },
          "listingType": {
            "title": "🏘️ Property section",
            "enum": [
              "residential",
              "rental",
              "lifestyle",
              "rural",
              "newhomes",
              "commercialsale",
              "commerciallease",
              "retirement",
              "openhomes"
            ],
            "type": "string",
            "description": "Which part of Trade Me Property to search. These are the site's own sections, and each one has its own index: Houses for sale holds about 44,000 live listings, Rentals about 12,000, Lifestyle blocks about 5,200 and Commercial for lease about 29,000. Rentals price in dollars per week rather than a sale price. Used by Property Search only.",
            "default": "residential"
          },
          "location": {
            "title": "📍 Place in New Zealand",
            "type": "string",
            "description": "Where to search. Type it the way you would on Trade Me: a region (Auckland, Wellington, Canterbury, Otago), a district (Franklin, Queenstown-Lakes, Tauranga) or a suburb (Ponsonby, Mount Maunganui, Riccarton). The name is matched against Trade Me's own place index, so nothing has to be looked up by hand. Leave it empty to search the whole country. The Agent Directory uses this field too, at region level.",
            "default": "Auckland"
          },
          "propertyType": {
            "title": "🏠 Property type",
            "enum": [
              "any",
              "House",
              "Apartment",
              "Townhouse",
              "Unit",
              "Dwelling",
              "Section",
              "BareLand"
            ],
            "type": "string",
            "description": "Narrow the search to one kind of property. These are Trade Me's own categories and only these values are recognised - anything else is quietly ignored by the site and you get the unfiltered list back, which is why this is a fixed list rather than a text box. Applies to the for-sale sections; Rentals uses the same names but has fewer of them.",
            "default": "any"
          },
          "priceMin": {
            "title": "💵 Min price (NZD)",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest price to include, in New Zealand dollars. On the Rentals section this is dollars per week, not a sale price, because that is how Trade Me prices rentals. 0 means no lower bound. Listings advertised as auction, tender or price-by-negotiation carry no number, so a price floor drops them.",
            "default": 0
          },
          "priceMax": {
            "title": "💰 Max price (NZD)",
            "minimum": 0,
            "type": "integer",
            "description": "Highest price to include, in New Zealand dollars - dollars per week on the Rentals section. 0 means no upper bound.",
            "default": 0
          },
          "bedroomsMin": {
            "title": "🛏️ Min bedrooms",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Fewest bedrooms to include. 0 means no lower bound. Sections, bare land and most commercial listings have no bedroom count and are dropped by any bedroom floor.",
            "default": 0
          },
          "bedroomsMax": {
            "title": "🛏️ Max bedrooms",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Most bedrooms to include. 0 means no upper bound.",
            "default": 0
          },
          "bathroomsMin": {
            "title": "🛁 Min bathrooms",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Fewest bathrooms to include. 0 means no lower bound.",
            "default": 0
          },
          "floorAreaMinSqm": {
            "title": "📐 Min floor area (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Smallest building floor area in square metres. 0 means no lower bound. Many private listings leave floor area blank and are dropped by any floor-area floor.",
            "default": 0
          },
          "landAreaMinSqm": {
            "title": "🌱 Min land area (m²)",
            "minimum": 0,
            "type": "integer",
            "description": "Smallest section size in square metres - 600 for a standard quarter-acre-ish suburban section, 10000 for a hectare. Trade Me itself measures this filter in hectares; the conversion is done for you so both this field and the landAreaSqm column in your results are in square metres. 0 means no lower bound.",
            "default": 0
          },
          "keywords": {
            "title": "🔤 Keywords",
            "type": "string",
            "description": "Free text matched against the listing title and description, the same box as Trade Me's own keyword search. Useful for the things that are not filters: villa, do-up, north facing, subdividable, motivated vendor.",
            "default": ""
          },
          "listedSince": {
            "title": "🗓️ Listed within",
            "enum": [
              "any",
              "1",
              "3",
              "7",
              "14",
              "30"
            ],
            "type": "string",
            "description": "Only return listings that went live in this window. This is the field to set when the actor runs on a schedule: you pay for what is new since your last run instead of re-buying the same market every morning.",
            "default": "any"
          },
          "openHomesOnly": {
            "title": "🚪 Only listings with an open home",
            "type": "boolean",
            "description": "Keep only listings that have an open home scheduled. The open-home times come back on every row that has them, so this is about narrowing the list rather than unlocking a field.",
            "default": false
          },
          "includeAdjacentSuburbs": {
            "title": "🗺️ Include neighbouring suburbs",
            "type": "boolean",
            "description": "Widen a suburb search to the suburbs Trade Me considers adjacent to it. Only does anything when the place you typed resolved to a suburb - a region or district search already covers everything inside it.",
            "default": false
          },
          "petsAllowed": {
            "title": "🐕 Pets allowed",
            "type": "boolean",
            "description": "Rentals only: keep only tenancies that accept pets. It is ignored on the sale sections, where the site has no such filter, so leave it off unless you are searching Rentals.",
            "default": false
          },
          "sort": {
            "title": "↕️ Sort by",
            "enum": [
              "newest",
              "featured",
              "closingSoonest",
              "priceAsc",
              "priceDesc",
              "earliestOpenHome"
            ],
            "type": "string",
            "description": "Newest first is what you want for monitoring a market on a schedule, and it is the default here even though the site's own default is featured first - featured means the agent paid for placement, which is not an ordering you want in a dataset.",
            "default": "newest"
          },
          "maxResults": {
            "title": "🔢 Max results",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Stop after this many rows. Each request returns up to 500 rows, so the run stops at the first request that crosses your limit. Trade Me sets no ceiling of its own - the whole for-sale index of roughly 44,000 listings is reachable in one run - so this number is your budget, not a technical limit.",
            "default": 100
          },
          "includeDetails": {
            "title": "📄 Add descriptions, all photos and nearby sold prices",
            "type": "boolean",
            "description": "Expand every listing with what the search results do not carry: the full written description, every full-size photo rather than the thumbnails, the view count, the open-home schedule, the named agents on the listing, and the recent nearby sale prices Trade Me publishes beside it. Costs one extra request per listing and is billed as one Listing Detail event per expanded row, so turn it on for a shortlist rather than a whole city.",
            "default": false
          },
          "listingUrls": {
            "title": "🔗 Listing URLs",
            "type": "array",
            "description": "Used by the Listing Detail operation: trademe.co.nz listing addresses to expand, for example https://www.trademe.co.nz/a/listing/6119038125. Paste the full address - Apify validates this field as URLs and rejects a bare listing number before the run starts. Long addresses that carry the region and suburb in the path are fine; the number at the end is what is read.",
            "default": [],
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}