# Realestate Agents Search Scraper (`stealth_mode/realestate-agents-search-scraper`) Actor

Scrape agent profiles and office listings from realestate.co.nz with ease. Collect agent details, contact info, relationships, attributes, and more — perfect for lead generation, market research, and real estate analytics.

- **URL**: https://apify.com/stealth\_mode/realestate-agents-search-scraper.md
- **Developed by:** [Stealth mode](https://apify.com/stealth_mode) (community)
- **Categories:** Automation, Developer tools, Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Real Estate Agents Search Scraper: Extract NZ Property Agent Data

---

### What Is Realestate.co.nz?

Realestate.co.nz is New Zealand's largest property portal, hosting thousands of residential and commercial listings alongside comprehensive agent and agency directories. Finding and organizing agent data manually is labor-intensive — the **Real Estate Agents Search Scraper** automates extraction of agent profiles, office information, and relationships from search results pages.

---

### Overview

The **Real Estate Agents Search Scraper** extracts structured agent and office data from realestate.co.nz search result pages. It is designed for:

- **Real estate recruiters** building talent databases and competitor lists
- **Lead generation professionals** collecting qualified agent contacts
- **Market researchers** analyzing agent distribution and agency networks
- **CRM managers** populating systems with verified agent profiles
- **Real estate analytics platforms** aggregating agency data

Key advantages include high-volume scraping (up to 200 items per URL), resilient error handling via `ignore_url_failures`, and structured output capturing relationships between agents and offices.

---

### Input Format

The scraper accepts a JSON configuration with agent search URLs:

```json
{
  "urls": [
    "https://www.realestate.co.nz/search/results/agents/a",
    "https://www.realestate.co.nz/search/results/agencies/a"
  ],
  "ignore_url_failures": true,
  "max_items_per_url": 200
}
````

| Parameter | Type | Description |
|---|---|---|
| `urls` | array | List of realestate.co.nz agent or office search result URLs. Start with alphabetical filters (e.g., `/agents/a`, `/agents/b`) or location-based searches. |
| `max_items_per_url` | integer | Maximum number of agent/office records to extract per URL (default: `20`, max: `200`). Increase for comprehensive list scraping. |
| `ignore_url_failures` | boolean | If `true`, the scraper continues processing remaining URLs even if one fails. If `false`, execution stops at first error. |

> **Best practice:** Use alphabetical search filters (`/a` through `/z`) to systematically collect nationwide agent data with pagination control.

***

### Output Format

#### Attributes Object

```json
{
  "relationships": {
    "listings": {
      "data": []
    },
    "offices": {
      "data": [
        {
          "id": "497456",
          "type": "office"
        },
        {
          "id": "285793",
          "type": "office"
        },
        {
          "id": "9230",
          "type": "office"
        }
      ]
    },
    "office": {
      "data": {
        "id": "497456",
        "type": "office"
      }
    }
  },
  "attributes": {
    "office-name": "Frank Commercial Ltd (Licensed: REAA 2008)",
    "image": {
      "base-url": "/per_orgs/175352/f3ffbfe8023f67c82b2c02f09cf01d8f"
    },
    "office-image": "/per_orgs/497456/fa5506b24edf5c5bbb97b857916a2be7",
    "office-brand-hex-code": "#f0802f",
    "listing-count": 827,
    "first-name": "Laura",
    "job-title": "Commercial Leasing Agent",
    "office-is-brand-colour-light": true,
    "phone-ddi": "09 303 3804",
    "website-url": "http://www.frankcommercial.co.nz",
    "name": "Laura Osborne",
    "show-profile": true,
    "phone-mobile": "021 969 480",
    "slug": "laura-osborne",
    "email": "laura@frankcommercial.co.nz",
    "last-name": "Osborne",
    "linkedin-url": "https://nz.linkedin.com/in/laosborne"
  },
  "id": "175352",
  "type": "agent",
  "from_url": "https://www.realestate.co.nz/search/results/agents/a"
}
```

Each scraped agent or office record contains four primary fields:

#### Core Fields

| Field | Type | Description |
|---|---|---|
| `ID` | string | Unique identifier assigned by realestate.co.nz to the agent or office profile |
| `Type` | string | Record classification: `agent` (individual agent) or `office` (agency/brokerage) |
| `Relationships` | array | Links to associated entities (e.g., agents belonging to an office, or offices where an agent is licensed) |
| `Attributes` | object | Agent/office profile data including name, contact details, location, specializations, license info, and performance metrics |

#### Relationships Structure

The `Relationships` array describes connections between records:

| Relationship Type | Description |
|---|---|
| `works_at` | An agent is employed by or associated with an office |
| `manages` | An office manages multiple agents |
| `licensed_in` | An agent is licensed to operate in specific regions |

***

### How to Use

1. **Identify search URLs** — Navigate to realestate.co.nz and go to the agent search page. Copy URLs from alphabetical listings or location filters (e.g., `https://www.realestate.co.nz/search/results/agents/a`).

2. **Prepare input JSON** — Add URLs to the `urls` array. Set `max_items_per_url` to `200` for comprehensive scraping or lower values for faster runs.

3. **Enable error handling** — Keep `ignore_url_failures: true` to skip problematic pages without stopping the entire job.

4. **Run the scraper** — Execute the job and monitor the run log for completion status.

5. **Download & parse results** — Export data as JSON or CSV. Use the `Relationships` array to build agent-to-office mappings in your CRM or database.

**Handling common scenarios:**

- For **nationwide coverage**, scrape all 26 alphabetical filters (`/a` through `/z`) in separate runs or batch them.
- For **regional focus**, use location-filtered URLs (e.g., `/agents?location=Auckland`) to target specific markets.
- For **office networks**, start with office search pages (`/offices/...`) to map agency hierarchies.

***

### Real-World Use Cases

- **CRM enrichment:** Automatically populate Salesforce or HubSpot with verified agent contact details and office associations
- **Lead generation:** Extract agent databases for targeted outreach campaigns by region or specialization
- **Competitive intelligence:** Monitor competitor agent counts, locations, and specializations across New Zealand
- **Market analysis:** Analyze agent density, turnover rates, and office network structures by area
- **Agency directory publishing:** Build a custom agency portal or real estate marketplace with up-to-date agent listings

The scraper eliminates manual data entry, delivering clean, structured records that integrate seamlessly into business workflows.

***

### Compliance & Best Practices

- **Respect robots.txt:** Ensure your scraping complies with realestate.co.nz's usage policies
- **Rate limiting:** Space out requests to avoid overwhelming the server
- **Data accuracy:** Cross-reference extracted license numbers with the Real Estate Authority's official registry
- **Privacy:** Use scraped agent data responsibly and in compliance with New Zealand's Privacy Act 2020

# Actor input Schema

## `urls` (type: `array`):

Add the URLs of the agents/office list urls you want to scrape. You can paste URLs one by one, or use the Bulk edit section to add a prepared list.

## `ignore_url_failures` (type: `boolean`):

If true, the scraper will continue running even if some URLs fail to be scraped.

## `max_items_per_url` (type: `integer`):

The maximum number of items to scrape per URL.

## Actor input object example

```json
{
  "urls": [
    "https://www.realestate.co.nz/search/results/agents/a"
  ],
  "ignore_url_failures": true,
  "max_items_per_url": 20
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "urls": [
        "https://www.realestate.co.nz/search/results/agents/a"
    ],
    "ignore_url_failures": true,
    "max_items_per_url": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("stealth_mode/realestate-agents-search-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "urls": ["https://www.realestate.co.nz/search/results/agents/a"],
    "ignore_url_failures": True,
    "max_items_per_url": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("stealth_mode/realestate-agents-search-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "urls": [
    "https://www.realestate.co.nz/search/results/agents/a"
  ],
  "ignore_url_failures": true,
  "max_items_per_url": 20
}' |
apify call stealth_mode/realestate-agents-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=stealth_mode/realestate-agents-search-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Realestate Agents Search Scraper",
        "description": "Scrape agent profiles and office listings from realestate.co.nz with ease. Collect agent details, contact info, relationships, attributes, and more — perfect for lead generation, market research, and real estate analytics.",
        "version": "0.0",
        "x-build-id": "bZ0GrQyBRXXKERz3A"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/stealth_mode~realestate-agents-search-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-stealth_mode-realestate-agents-search-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/stealth_mode~realestate-agents-search-scraper/runs": {
            "post": {
                "operationId": "runs-sync-stealth_mode-realestate-agents-search-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/stealth_mode~realestate-agents-search-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-stealth_mode-realestate-agents-search-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": {
                    "urls": {
                        "title": "URLs of the agents/office list urls to scrape",
                        "type": "array",
                        "description": "Add the URLs of the agents/office list urls you want to scrape. You can paste URLs one by one, or use the Bulk edit section to add a prepared list.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "ignore_url_failures": {
                        "title": "Continue running even if some URLs fail to be scraped",
                        "type": "boolean",
                        "description": "If true, the scraper will continue running even if some URLs fail to be scraped."
                    },
                    "max_items_per_url": {
                        "title": "Max items per URL",
                        "type": "integer",
                        "description": "The maximum number of items to scrape per URL."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```