{ "openapi": "3.0.1", "info": { "title": "Realestate.co.nz Scraper [Just ๐Ÿ’ฐ$0.4] โ€” NZ property portal", "description": "๐Ÿ’ฐ $0.4 per 1,000 listings. Scrape realestate.co.nz โ€” council valuation & sales history per address ยท school zones with open homes ยท each property's price plus full details. Incremental mode tracks new and changed listings across scheduled runs.", "version": "0.1", "x-build-id": "Js0rSfnRlWPIchFVU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/blackfalcondata~realestate-co-nz-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-blackfalcondata-realestate-co-nz-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/blackfalcondata~realestate-co-nz-scraper/runs": { "post": { "operationId": "runs-sync-blackfalcondata-realestate-co-nz-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/blackfalcondata~realestate-co-nz-scraper/run-sync": { "post": { "operationId": "run-sync-blackfalcondata-realestate-co-nz-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": { "category": { "title": "๐Ÿท๏ธ Listing type", "enum": [ "res_sale", "res_rent", "lifestyle_sale", "lifestyle_lease", "rural_sale", "com_sale", "com_lease", "biz_sale" ], "type": "string", "description": "What kind of listings to collect. Use a JSON array for several at once, e.g. [\"res_sale\",\"res_rent\"].", "default": "res_sale" }, "region": { "title": "๐Ÿ—บ๏ธ Region", "type": "string", "description": "Region name, e.g. \"Auckland\" or \"Otago\". Pass a JSON array to cover several at once, e.g. [\"Auckland\",\"Waikato\"]. Leave every location field empty to search all of New Zealand." }, "district": { "title": "๐Ÿ™๏ธ District", "type": "string", "description": "District name, e.g. \"Auckland City\" or \"Christchurch City\". A JSON array covers several districts in one run." }, "suburb": { "title": "๐Ÿ“ Suburb", "type": "string", "description": "Suburb name, e.g. \"Ponsonby\". Pass a JSON array to cover a shortlist. Some suburb names repeat around the country โ€” every match is searched." }, "query": { "title": "๐Ÿ” Keyword", "type": "string", "description": "Optional free-text keyword, e.g. \"waterfront\" or \"renovated\". Leave empty to browse everything in the selected area." }, "startUrls": { "title": "๐Ÿ”— Start URLs", "type": "array", "description": "Paste search URLs from the site, e.g. https://www.realestate.co.nz/residential/sale/auckland/auckland-city. Each becomes its own search; results are merged and deduplicated. A listing page URL (e.g. https://www.realestate.co.nz/43147216/residential/sale/1-tomas-street-wellsford) returns just that listing. When provided, these replace the fields above.", "items": { "type": "string" }, "default": [] }, "minPrice": { "title": "๐Ÿ’ฐ Min price", "minimum": 0, "type": "integer", "description": "Minimum price in NZD โ€” weekly rent when the listing type is a rental." }, "maxPrice": { "title": "๐Ÿ’ฐ Max price", "minimum": 0, "type": "integer", "description": "Maximum price in NZD (weekly rent for rentals). Listings advertised as \"Auction\", \"Tender\" or \"Deadline Sale\" are matched by realestate.co.nz against the price the agent gave it privately, so some of them appear; their priceValue stays empty because no price is published." }, "propertyType": { "title": "๐Ÿ  Property type", "type": "string", "description": "e.g. \"House\", \"Apartment\", \"Townhouse\", \"Unit\", \"Section\". A JSON array selects more than one. Which types exist depends on the listing type selected above." }, "minBedrooms": { "title": "๐Ÿ›๏ธ Min bedrooms", "minimum": 0, "maximum": 20, "type": "integer", "description": "Only listings with at least this many bedrooms." }, "maxBedrooms": { "title": "๐Ÿ›๏ธ Max bedrooms", "minimum": 0, "maximum": 20, "type": "integer", "description": "Only listings with at most this many bedrooms." }, "minBathrooms": { "title": "๐Ÿ› Min bathrooms", "minimum": 0, "maximum": 20, "type": "integer", "description": "Only listings with at least this many bathrooms." }, "maxBathrooms": { "title": "๐Ÿ› Max bathrooms", "minimum": 0, "maximum": 20, "type": "integer", "description": "Only listings with at most this many bathrooms." }, "minCarparks": { "title": "๐Ÿš— Min carparks", "minimum": 0, "maximum": 20, "type": "integer", "description": "Only listings with at least this many carparks, counting garages, carports and open spaces." }, "minLandArea": { "title": "๐ŸŒณ Min land area", "minimum": 0, "type": "integer", "description": "Minimum land area in square metres." }, "maxLandArea": { "title": "๐ŸŒณ Max land area", "minimum": 0, "type": "integer", "description": "Maximum land area in square metres." }, "minFloorArea": { "title": "๐Ÿ“ Min floor area", "minimum": 0, "type": "integer", "description": "Minimum floor area in square metres." }, "maxFloorArea": { "title": "๐Ÿ“ Max floor area", "minimum": 0, "type": "integer", "description": "Maximum floor area in square metres." }, "hasSwimmingPool": { "title": "๐ŸŠ Swimming pool only", "type": "boolean", "description": "Only listings with a swimming pool.", "default": false }, "isNewConstruction": { "title": "๐Ÿ—๏ธ New builds only", "type": "boolean", "description": "Only newly built properties.", "default": false }, "isCoastalWaterfront": { "title": "๐ŸŒŠ Coastal / waterfront only", "type": "boolean", "description": "Only properties on the coast or waterfront.", "default": false }, "isMortgageeSale": { "title": "โš–๏ธ Mortgagee sales only", "type": "boolean", "description": "Forced sales by a lender โ€” often priced below market.", "default": false }, "isOpenHome": { "title": "๐Ÿšช Open home scheduled only", "type": "boolean", "description": "Only listings with an open home coming up.", "default": false }, "petsAllowed": { "title": "๐Ÿ• Pets allowed only", "type": "boolean", "description": "Rentals only.", "default": false }, "includeNearbySuburbs": { "title": "โž• Include nearby suburbs", "type": "boolean", "description": "Widen a suburb search to neighbouring suburbs.", "default": false }, "priceChangedSince": { "title": "๐Ÿ“‰ Price changed since", "type": "string", "description": "Only listings whose asking price changed on or after this date (YYYY-MM-DD). Use it to track price drops." }, "listedWithinDays": { "title": "๐Ÿ†• Listed within (days)", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Only listings first published within the last N days, e.g. 7 for the past week. Leave blank for all listings." }, "saleMethod": { "title": "๐Ÿ”จ Sale method", "type": "array", "description": "Listings for sale only: keep listings sold by these methods (e.g. auction, tender, deadline sale). Leave empty for every method. Has no effect on rentals.", "items": { "type": "string", "enum": [ "price", "negotiation", "auction", "tender", "poa", "offers", "deadline-sale", "asking-price", "buyer-budget", "buyer-enquiry", "buyer-interest", "enquiries-over" ], "enumTitles": [ "Fixed / asking price", "By negotiation", "Auction", "Tender", "Price on application", "Offers", "Deadline sale", "Asking price", "Buyer budget from", "Buyer enquiry over", "Buyer interest from", "Enquiries over" ] } }, "schoolZone": { "title": "๐Ÿซ School zone", "type": "array", "description": "Only listings inside the enrolment zone of these schools, e.g. \"Auckland Grammar\" or \"Glenavon School\". Several schools = listings in any of their zones. A school name that is not found stops the run with a message.", "items": { "type": "string" } }, "agent": { "title": "๐Ÿง‘โ€๐Ÿ’ผ Agent", "type": "array", "description": "Only listings by these agents, by name (e.g. \"Avinesh Prasad\"), agent page URL or agent id. A name that is not found stops the run with a message.", "items": { "type": "string" } }, "office": { "title": "๐Ÿข Agency office", "type": "array", "description": "Only listings by these agency offices, by name (e.g. \"Barfoot & Thompson Blockhouse Bay\"), office page URL or office id. A brand name alone (e.g. \"Barfoot\") matches every branch of it.", "items": { "type": "string" } }, "geoBoundingBox": { "title": "๐Ÿ—บ๏ธ Map area", "type": "string", "description": "Search inside a map rectangle: \"lat,lng|lat,lng\" giving the north-west corner then the south-east corner, e.g. \"-36.8,174.7|-36.9,174.9\"." }, "sort": { "title": "โ†•๏ธ Sort order", "enum": [ "best-match", "featured", "latest", "oldest", "lowest-price", "highest-price", "lowest-land-area", "highest-land-area" ], "type": "string", "description": "How results are ordered. Listings advertised without a number (\"Auction\", \"Deadline Sale\") group together when sorting by price." }, "maxResults": { "title": "๐Ÿ’ฏ Max results", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum listings to return (0 = as many as possible).", "default": 100 }, "includeValuation": { "title": "๐Ÿฆ Include valuation & sales history", "type": "boolean", "description": "Add the council valuation (RV/CV), the estimated value, past sales and building age to each listing. Adds roughly a minute per 1,000 listings, and costs extra only for listings that come back with valuation data. Turn it off for the fastest, cheapest run.", "default": true }, "includeBroadband": { "title": "๐ŸŒ Include fibre broadband", "type": "boolean", "description": "Add fibre broadband availability at each address: whether fibre is available, the fastest download speed, whether a fibre box is installed, and the plans with speeds and indicative monthly prices. Adds a few seconds per 100 listings and costs nothing extra.", "default": true }, "descriptionMaxLength": { "title": "โœ‚๏ธ Description max length", "minimum": 0, "type": "integer", "description": "Truncate the description to N characters. 0 = no truncation.", "default": 0 }, "compact": { "title": "๐Ÿ“ฆ Compact output", "type": "boolean", "description": "Core fields only (for AI-agent/MCP workflows).", "default": false }, "descriptionFormat": { "title": "Description format", "enum": [ "all", "text", "html", "markdown" ], "type": "string", "description": "Pick a single description representation. `all` keeps every variant; `text` / `html` / `markdown` drop the others.", "default": "all" }, "excludeEmptyFields": { "title": "Exclude empty fields from output", "type": "boolean", "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.", "default": false }, "incrementalMode": { "title": "โ™ป๏ธ Incremental mode", "type": "boolean", "description": "Compare against the previous run and label each listing NEW, UPDATED, UNCHANGED or EXPIRED. The state key is optional โ€” it is derived from your search settings, so different filters never share state.", "default": false }, "stateKey": { "title": "๐Ÿ”‘ State key", "type": "string", "description": "Optional. Stable identifier for the tracked search. Leave empty to generate one from the search inputs." }, "emitUnchanged": { "title": "๐Ÿ“ค Include unchanged listings", "type": "boolean", "description": "When incremental mode is on, also return listings that have not changed since the last run.", "default": false }, "emitExpired": { "title": "๐Ÿ“ค Include gone listings", "type": "boolean", "description": "When incremental mode is on, also return listings that have disappeared since the last run, marked EXPIRED.", "default": false }, "skipReposts": { "title": "๐Ÿšซ Skip re-listed properties", "type": "boolean", "description": "When incremental mode is on, drop properties that were withdrawn and listed again under a new ID. Every record is flagged either way, so leave this off to see them.", "default": false }, "telegramToken": { "title": "๐Ÿ”‘ Telegram Bot Token", "type": "string", "description": "Telegram bot token (from @BotFather). Required for Telegram notifications." }, "telegramChatId": { "title": "๐Ÿ’ฌ Telegram Chat ID", "type": "string", "description": "Telegram chat or channel ID (e.g. \"-100123456789\"). Required when telegramToken is set." }, "discordWebhookUrl": { "title": "๐ŸŽฎ Discord Webhook URL", "type": "string", "description": "Discord incoming webhook URL. Server Settings โ†’ Integrations โ†’ Webhooks โ†’ New Webhook." }, "slackWebhookUrl": { "title": "๐Ÿ’ผ Slack Webhook URL", "type": "string", "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks." }, "notificationLimit": { "title": "๐Ÿ“Š Max listings per notification", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of listings included in each notification message (1โ€“20).", "default": 5 }, "notifyOnlyChanges": { "title": "๐Ÿ”„ Notify only new/updated", "type": "boolean", "description": "When incremental mode is on, only send notifications for NEW and UPDATED listings. Has no effect otherwise.", "default": false }, "whatsappAccessToken": { "title": "๐Ÿ“ฑ WhatsApp Access Token", "type": "string", "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window โ€” free since Nov 2024)." }, "whatsappPhoneNumberId": { "title": "๐Ÿ“ž WhatsApp Phone Number ID", "type": "string", "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set." }, "whatsappTo": { "title": "๐Ÿ“ฒ WhatsApp Recipient", "type": "string", "description": "Recipient phone in E.164 format without + (e.g. \"6421234567\"). Recipient must have messaged your business number within last 24h." }, "webhookUrl": { "title": "๐Ÿช Generic Webhook URL", "type": "string", "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends." }, "webhookHeaders": { "title": "๐Ÿ“‹ Webhook Headers", "type": "object", "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})." }, "appConnector": { "title": "Send results to a connected app", "type": "string", "description": "Optional. Pick a connected app under Settings โ†’ API & Integrations to receive your results (including any contact details). Best-effort across MCP connectors as Apify expands its catalog." }, "mcpIssueTeam": { "title": "Issue tracker team", "type": "string", "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one." }, "cityName": { "title": "๐Ÿ™๏ธ City Name", "type": "string", "description": "City, town or area name (e.g. \"Auckland\", \"Ponsonby\"). Matched against regions, districts and suburbs โ€” use this when you do not know which tier the place belongs to." }, "lat": { "title": "๐ŸŒ Centre latitude", "minimum": -90, "maximum": 90, "type": "number", "description": "Latitude of a search centre. Pair with lon and radiusKm to search around a point: the radius is searched directly, with or without a region, and every returned listing is stamped with its distance from this point." }, "lon": { "title": "๐ŸŒ Centre longitude", "minimum": -180, "maximum": 180, "type": "number", "description": "Longitude of the search centre. Pair with lat." }, "radiusKm": { "title": "๐Ÿ“ Search radius (km)", "minimum": 0, "maximum": 500, "type": "integer", "description": "Search only within this many kilometres of the centre (lat, lon); works on its own, no region needed. Leave lat/lon blank to disable. Each returned listing carries its distance from the centre in the distanceKm field." } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }