{ "openapi": "3.0.1", "info": { "title": "The Warehouse NZ Scraper - Products, Prices, Stock & Reviews", "description": "Scrape The Warehouse New Zealand search results, category pages, and direct product URLs. Extract prices, availability, brand, images, breadcrumbs, attributes, product details, and optional customer reviews. Supports search mode, URL mode, sorting, pagination, and MCP connector export.", "version": "0.1", "x-build-id": "vUxY4BuJy57mwwtjf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~thewarehouse-co-nz-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-thewarehouse-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/abotapi~thewarehouse-co-nz-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-thewarehouse-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/abotapi~thewarehouse-co-nz-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-thewarehouse-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "url" ], "type": "string", "description": "Use search mode for keyword search. Use URL mode when you already have The Warehouse search, category, or product URLs.", "default": "search" }, "queries": { "title": "Search keywords", "type": "array", "description": "One or more keywords to search. Each query is searched separately.", "items": { "type": "string" } }, "specialsCategory": { "title": "Specials category", "enum": [ "", "specials", "specials_electronics_gaming", "specials_home_garden", "specials_health_beauty", "specials_food_pets_household", "mega_toy_sale" ], "type": "string", "description": "Optional. Browse one of The Warehouse's own Specials collections directly, instead of a keyword search. These are real storefront category pages badged \"Specials\" on-site; matching products are returned with isOnSpecial=true and, when the site shows one, an offer end date. The Warehouse never shows a struck-through original/was price anywhere on the site, so no wasPrice field is produced -- isOnSpecial and offerEndsAt are the real signals the site itself asserts. When set, this replaces keyword search for the run.", "default": "" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "price_asc", "price_desc", "top_rated", "newest", "best_sellers", "name_asc", "name_desc" ], "type": "string", "description": "Maps directly to the storefront search sort rules. URL mode preserves whatever sort is already encoded in the pasted URL.", "default": "relevance" }, "urls": { "title": "The Warehouse URLs", "type": "array", "description": "Search, category, or product URLs. Left untouched, URL mode scrapes one example of each supported shape. Pagination starts from the page encoded in the URL when present and walks forward.", "default": [ "https://www.thewarehouse.co.nz/search?q=toaster", "https://www.thewarehouse.co.nz/c/electronics-gaming", "https://www.thewarehouse.co.nz/p/living-co-2-slice-toaster-stainless-steel/R2957596.html" ], "items": { "type": "string" } }, "fetchDetails": { "title": "Fetch product details", "type": "boolean", "description": "Open each product page for description, brand, structured attributes, breadcrumbs, image gallery and availability.", "default": true }, "includeUnavailable": { "title": "Include unavailable products", "type": "boolean", "description": "Keep products marked unavailable or out of stock. Turn off to return only likely in-stock products when the page exposes availability.", "default": true }, "maxItems": { "title": "Max products", "minimum": 0, "type": "integer", "description": "Maximum matching products to save. Leave empty or set 0 for unlimited. This is the run's only default cap.", "default": 20 }, "maxPages": { "title": "Max pages per query / URL", "minimum": 0, "type": "integer", "description": "Leave empty or set 0 for unlimited; the run walks the whole result set for each query/URL, stopping naturally when the storefront reports no next page or a page repeats no new products, or at Max products if that's reached first. Set a number only when you want an explicit page cap below that natural stop.", "default": 0 }, "fetchReviews": { "title": "Fetch customer reviews", "type": "boolean", "description": "Also collect product reviews when the page exposes a review API or inline review markup. Each started block of 10 delivered reviews bills one detail-enrichment unit.", "default": false }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Cap on reviews collected per product when Fetch customer reviews is on (maximum 1000; 0 uses the default of 20). Each started block of 10 delivered reviews bills one detail-enrichment unit.", "default": 20 }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Use a proxy configuration that matches your account and traffic needs. The default prefill is suitable for most production runs.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "NZ" } }, "resumeFromRunId": { "title": "Resume from a prior run", "type": "string", "description": "Paste a previous run ID or dataset ID to continue a large walk-all pull: product URLs already saved by that run are loaded before scraping starts and skipped, so this run only appends new products. For recurring monitoring of the same search, use Incremental mode below instead. Leave empty for a normal fresh run." }, "incrementalMode": { "title": "Incremental changes for scheduled runs", "type": "boolean", "description": "Turn this on for daily or recurring monitoring. The first run returns all matching products as NEW. Later runs normally return only NEW, UPDATED, and REAPPEARED products. Turn on \"Emit unchanged\" or \"Emit expired\" only when you also want those products returned (and billed). UPDATED means a product's own data changed: price, price range, specials flag and offer end date, availability, title, brand, description, images (compared without their changing CDN query parameters), attributes, features and similar fields; the fields that changed are listed in changedFields. Ratings, rating counts, review counts and review text never trigger UPDATED, and neither does scrapedAt or the source page a product was listed on (sourceUrl). You can exclude more fields with \"Ignore fields when detecting changes\". EXPIRED is only produced after a run that scanned the whole search (no Max products or Max pages cap, no pasted URL that starts mid-listing, no Resume). State is kept separately for each mode/query/URL/specials/sort/detail/review/availability setup; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from a prior run above.", "default": false }, "stateKey": { "title": "State key (optional, incremental mode only)", "type": "string", "description": "Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the search/URL, specials, sort, and detail/review/availability settings — different searches then never mix state with each other." }, "emitUnchanged": { "title": "Emit unchanged products (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return products that have not changed since the last run, marked UNCHANGED. This returns — and bills — extra rows you already have, so leave it off unless you specifically want the full snapshot every run.", "default": false }, "emitExpired": { "title": "Emit expired products (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return products that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search — not when Max products capped it or when Resume was used. This returns — and bills — extra synthetic rows, so leave it off unless you need expiry tracking.", "default": false }, "ignoreFieldsForChanges": { "title": "Ignore fields when detecting changes (incremental mode only)", "type": "array", "description": "Extra output fields that must never make a product count as UPDATED. Use a field name such as \"description\", or a dotted path for a nested field such as \"attributes.Colour\". Ignored fields stay in the output and are left out of changedFields. Already ignored by default: scrapedAt, ratingValue, ratingCount, reviewCount, reviews, rawProduct, and the query-string part of image URLs. Only used when Incremental changes is on.", "default": [], "items": { "type": "string" } }, "mcpConnectors": { "title": "Pipe results into your apps (optional)", "type": "array", "description": "Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify → Settings → Integrations, then select it here. Notion gets a page per item; other connectors receive a best-effort write or digest. Leave empty to skip — this never changes the dataset output. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)." }, "notionParentPageUrl": { "title": "Notion parent page (Notion connector only)", "type": "string", "description": "URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors." }, "maxNotifyListings": { "title": "Max items to export per connector", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on items written to each connector per run. Does not affect the dataset.", "default": 50 } } }, "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 } } } } } } } } } }