{
  "openapi": "3.0.1",
  "info": {
    "title": "Homes.co.nz $1💰 URL | Search | Property Scraper",
    "description": "From $1/1K. Scrape Homes.co.nz listings via search or URL. Supports multiple locations or links per run with forward pagination. Extract enriched data, including property details, agents, branch info, valuations, media, open homes, and filters for status, price, beds, and baths.",
    "version": "1.0",
    "x-build-id": "yxV2Jizo6UFWUe86N"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/abotapi~homes-co-nz-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-abotapi-homes-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~homes-co-nz-scraper/runs": {
      "post": {
        "operationId": "runs-sync-abotapi-homes-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~homes-co-nz-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-abotapi-homes-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": "Collection Mode",
            "enum": [
              "search",
              "url"
            ],
            "type": "string",
            "description": "Search mode resolves location names and expands them into listing results. URL mode accepts Homes detail URLs or map URLs directly.",
            "default": "search"
          },
          "locations": {
            "title": "Locations",
            "type": "array",
            "description": "One or more location names to resolve through Homes and collect listings from.",
            "items": {
              "type": "string"
            }
          },
          "listingStatus": {
            "title": "Listing Status",
            "enum": [
              "for_sale",
              "for_rent",
              "just_sold",
              "off_market"
            ],
            "type": "string",
            "description": "Choose which Homes listing bucket to collect.",
            "default": "for_sale"
          },
          "minBedrooms": {
            "title": "Min Bedrooms",
            "minimum": 0,
            "type": "integer",
            "description": "Only include listings with at least this many bedrooms when the structured feed exposes that filter."
          },
          "minBathrooms": {
            "title": "Min Bathrooms",
            "minimum": 0,
            "type": "integer",
            "description": "Only include listings with at least this many bathrooms when the structured feed exposes that filter."
          },
          "minPrice": {
            "title": "Min Price (NZD)",
            "minimum": 0,
            "type": "integer",
            "description": "Lower price bound to send to the structured Homes query when supported for the chosen listing status."
          },
          "maxPrice": {
            "title": "Max Price (NZD)",
            "minimum": 0,
            "type": "integer",
            "description": "Upper price bound to send to the structured Homes query when supported for the chosen listing status."
          },
          "sortBy": {
            "title": "Sort By",
            "enum": [
              "default",
              "published_desc",
              "published_asc",
              "price_desc",
              "price_asc"
            ],
            "type": "string",
            "description": "Applies to the output ordering of collected listings. Price sorting only affects records where a numeric price can be derived from the structured listing data.",
            "default": "default"
          },
          "urls": {
            "title": "Homes URLs",
            "type": "array",
            "description": "One or more homes.co.nz detail URLs or map URLs. Multi-URL supported. Detail URLs return a single enriched listing. Map URLs expand into structured result pages and walk forward — when used this way, the search filters and sort above also apply.",
            "items": {
              "type": "string"
            }
          },
          "maxListings": {
            "title": "Max Listings (global cap)",
            "minimum": 0,
            "type": "integer",
            "description": "Hard ceiling on listings output across the whole run — pagination stops as soon as this is hit, in both Search and URL modes. Use 0 for no explicit cap.",
            "default": 20
          },
          "maxPages": {
            "title": "Max Pages Per Search",
            "minimum": 0,
            "type": "integer",
            "description": "How many output pages to emit for each search target or map URL. Leave empty to walk every result page: the walk is then bounded only by Max Listings and the site's own candidate ceiling. Set a number only for an explicit page cap below that natural stop.",
            "default": 0
          },
          "pageSize": {
            "title": "Listings Per Page",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Number of listings to emit on each output page.",
            "default": 20
          },
          "fetchPropertyCards": {
            "title": "Fetch Property Cards (extra cost)",
            "type": "boolean",
            "description": "Include extra valuation, title, branch, and agent data when available. Adds one additional request per listing — disable to cut cost when you only need core fields.",
            "default": true
          },
          "includeRawApiResponses": {
            "title": "Include Raw Structured Payloads (debug)",
            "type": "boolean",
            "description": "Include the raw structured API payloads in each output item for debugging.",
            "default": false
          },
          "resumeFromRunId": {
            "title": "Resume from a prior run (optional)",
            "type": "string",
            "description": "Paste a previous run ID or dataset ID to continue a large walk-all pull: listings already saved by that run are loaded before scraping starts and skipped, so this run only appends new listings. Leave empty for a normal fresh run. Independent of Incremental mode below — see that field for recurring/scheduled monitoring instead."
          },
          "incrementalMode": {
            "title": "Incremental mode (recurring monitoring)",
            "type": "boolean",
            "description": "For a scraper you schedule repeatedly against the SAME search/URLs: the actor remembers the previous run itself (no need to paste a run ID) and tags each listing changeType NEW / UPDATED / UNCHANGED / REAPPEARED / EXPIRED, with changedFields / firstSeenAt / lastSeenAt. Off by default (normal one-off scrape). See 'Resume from a prior run' above for continuing ONE interrupted run instead - that is a different feature.",
            "default": false
          },
          "stateKey": {
            "title": "Incremental state key (optional)",
            "type": "string",
            "description": "Only used when Incremental mode is on. Leave empty to auto-derive the tracked search's identity from mode + locations/URLs + filters + fetchPropertyCards (recommended). Set your own text only if you need two runs with different other settings (e.g. different maxListings) to share one baseline, or to keep two similar searches from colliding."
          },
          "emitUnchanged": {
            "title": "Emit UNCHANGED rows (Incremental mode)",
            "type": "boolean",
            "description": "Only used when Incremental mode is on. When off (default), a listing identical to the last run is not pushed again, so a recurring run only bills for what changed. Turn on to get a full refreshed dataset every run - this returns and BILLS an extra row for every unchanged listing.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit EXPIRED rows (Incremental mode)",
            "type": "boolean",
            "description": "Only used when Incremental mode is on, and only after a run completes a full pass of the tracked search (a capped/partial run never emits these). When on, a listing that was present last run but not found this run is pushed once more with changeType EXPIRED - this returns and BILLS an extra row for every listing that dropped out.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Proxy configuration for Homes requests. Apify Proxy is recommended for production runs.",
            "default": {
              "useApifyProxy": true
            }
          },
          "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/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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}