# Yellow Pages NZ Scraper — Business Leads, Phone & Email (`memo23/yellowpages-nz-scraper`) Actor

Scrape New Zealand business leads from yellow.co.nz — name, phone, email, website, category, full split address, coordinates, opening hours, rating, reviews and description. Search by keyword + city or paste yellow.co.nz URLs. Email included in every result. JSON/CSV export.

- **URL**: https://apify.com/memo23/yellowpages-nz-scraper.md
- **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $12.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.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Yellow Pages NZ Scraper — Business Leads, Phone & Email

Scrape New Zealand business leads from **yellow.co.nz** — name, phone, **email**, website, category, full split address, coordinates, opening hours, rating, reviews and description. Search by keyword + city, or paste yellow.co.nz URLs. Email ships in every result at no extra cost. Export to JSON or CSV.

[![How it works](https://api.apify.com/v2/key-value-stores/dIGFePgtMDZMN5OpE/records/how-it-works-yellowpages-nz.png)](https://apify.com/memo23/yellowpages-nz-scraper)

### Why Use This Scraper?

- **Email included in every result** — yellow.co.nz exposes business emails on each profile page. The competitor charges $0.0275/email as a paid add-on; here it ships in the base result.
- **Full split address** — street, suburb, city, region (AUK/WGN/CAN…), postcode, country, plus lat/lng coordinates.
- **Two speeds** — fast listing mode (name, phone, category, website, rating) or full detail mode (email, hours, description, reviews, payment methods, images).
- **Residential proxy resilience** — yellow.co.nz sits behind Cloudflare; the actor runs Evomi residential first, with automatic IPCook and Apify RESIDENTIAL fallback so a single vendor outage never kills a run.
- **Search by keyword × location** — plumbers in Auckland, cafes in Wellington, accountants nationwide. Multi-query, multi-location, paginated.
- **Direct profile URLs** — paste one or more `yellow.co.nz/{city}/bpp/{slug}-{id}` links and get full details for each.

### Overview

The actor scrapes [yellow.co.nz](https://www.yellow.co.nz), the New Zealand business directory operated by Yellow Pages Group. Each result is one business record. The search flow paginates `/search?search_terms=…&geo_location_terms=…` pages (30 businesses per page), collecting business profile URLs. In full-detail mode each profile page is opened and parsed from its schema.org `LocalBusiness` JSON-LD block, which carries the name, full postal address, geo coordinates, telephone, opening hours, image, aggregate rating, individual reviews, business website, and email.

The dataset is one row per business. No padding rows. Clients pay per result.

### Supported Inputs

**Search mode** (recommended):

```
searchQueries: ["plumber", "electrician"]
locations: ["Auckland", "Wellington"]
```

**Start URLs** — paste yellow.co.nz links, one per line:

- Search URL: `https://www.yellow.co.nz/search?search_terms=plumber&geo_location_terms=Auckland`
- Business profile: `https://www.yellow.co.nz/auckland/bpp/ak-speech-therapy-579486261`

**Unsupported**: whitepages.co.nz (separate site, behind reCAPTCHA), the Yellow mobile app API, logged-in agent pages.

### Use Cases

| Audience | Use |
|---|---|
| B2B lead generation | Build NZ business lists by trade + city with phone and email |
| Email outreach | Recover verified business emails straight from each listing |
| Local SEO / mapping | Collect coordinates + full addresses for NZ business mapping |
| Market research | Category coverage by region, rating distribution, review counts |
| Sales pipelines | Enrich CRM records with website, category, hours, payment methods |

### How It Works

1. **Resolve inputs** — search queries × locations become search-page URLs; pasted start URLs are split into search URLs (expanded) and profile URLs (scraped directly).
2. **Paginate search** — each search page returns 30 business cards. The actor parses name, phone, category, website, address, rating and review count from the HTML, and pulls coordinates from the embedded map JSON.
3. **Collect profile URLs** — each card links to `/{city}/bpp/{slug}-{ypid}`; these are queued for detail fetch.
4. **Fetch details** (if `fetchFullDetails` is on) — each profile page is opened and its `LocalBusiness` JSON-LD is parsed for email, full split address, opening hours, description, reviews, payment methods and images.
5. **Push rows** — one dataset row per business, deduplicated by `ypid`.

### Input Configuration

| Field | Type | Default | Description |
|---|---|---|---|
| `searchQueries` | array | `["plumber"]` | Business types or keywords, one per line. Each runs across every location. |
| `locations` | array | `["Auckland"]` | NZ cities or regions, one per line. Leave empty for nationwide. |
| `startUrls` | array | `[]` | Paste yellow.co.nz search or profile URLs. Combines with the fields above. |
| `fetchFullDetails` | boolean | `true` | Open each profile page for email, hours, reviews, full address. Off = fast listing fields only. |
| `maxItems` | integer | `1000` | Max businesses across all searches. |
| `maxPages` | integer | `0` | Max search pages per query×location (30/page). 0 = unlimited. |
| `maxConcurrency` | integer | `10` | Pages fetched in parallel. |
| `proxy` | object | residential | Leave empty for the default residential proxy. yellow.co.nz is behind Cloudflare. |

**Example — plumbers in Auckland with full details:**

```json
{
  "searchQueries": ["plumber"],
  "locations": ["Auckland"],
  "maxItems": 50,
  "fetchFullDetails": true
}
```

**Example — fast listing scan, no details (cheaper, no email):**

```json
{
  "searchQueries": ["cafe", "restaurant"],
  "locations": ["Wellington", "Christchurch"],
  "maxItems": 200,
  "fetchFullDetails": false
}
```

**Example — direct profile URLs:**

```json
{
  "startUrls": [
    "https://www.yellow.co.nz/auckland/bpp/ak-speech-therapy-579486261",
    "https://www.yellow.co.nz/ashburton/bpp/goulds-towing-limited-579433096"
  ],
  "fetchFullDetails": true
}
```

### Output Overview

Each dataset row is one NZ business. In full-detail mode the row carries 25+ fields; in listing mode it carries the 10 fast fields. The `source` field is `"search"` for listing rows and `"detail"` for profile-enriched rows.

### Output Samples

**Full-detail row** (from a plumber search in Auckland):

```json
{
  "ypid": "579352122",
  "name": "Brockelsby Plumbing & Gasfitting Limited",
  "slug": "brockelsby-plumbing-gasfitting-limited",
  "url": "https://www.yellow.co.nz/lower-hutt/bpp/brockelsby-plumbing-gasfitting-limited-579352122",
  "website": "https://brockelsby.co.nz",
  "phone": "04 569 7029",
  "email": "info@brockelsby.co.nz",
  "description": "We honor our heritage by providing exceptional plumbing and gasfitting services…",
  "categories": ["Metalwork - Architectural", "Drainage Contractors", "Engineers - Sheet Metal", "Gas Appliances", "Gas Lines-Installation & Repairing", "Plumbers"],
  "primaryCategory": "Metalwork - Architectural",
  "streetAddress": "10 Waione Street",
  "suburb": "Lower Hutt",
  "city": "Lower Hutt",
  "region": "WGN",
  "postcode": "5012",
  "country": "NZ",
  "latitude": -41.232006,
  "longitude": 174.89116,
  "rating": 5,
  "reviewCount": 1,
  "openingHours": ["Mo-Su 00:00-23:59"],
  "image": "https://i1.ypcdn.com/blob/f9f4c3815ddcb837acae6b3408a145f2201998ea",
  "paymentAccepted": "invoicing available, cash, mastercard, visa",
  "reviews": [
    { "author": "Yellow Mobile User", "datePublished": "2021-13-05", "ratingValue": 5, "reviewBody": "I experienced Brockelsby's service last month…" }
  ],
  "isAd": false,
  "source": "detail",
  "scrapedAt": "2026-10-20T11:21:17.120Z"
}
```

**Listing row** (fast mode, no details):

```json
{
  "ypid": "579504888",
  "name": "Mojo Central",
  "phone": "044729272",
  "primaryCategory": "Cafes",
  "website": "https://mojo.coffee/",
  "city": "wellington",
  "rating": 4.5,
  "reviewCount": 9,
  "url": "https://www.yellow.co.nz/wellington/bpp/mojo-central-579504888",
  "source": "search"
}
```

### Key Output Fields

**Identity**: `ypid`, `name`, `slug`, `url` (profile URL), `website` (business's own site)

**Contact**: `phone`, `email` (from the profile page, `mailto:` stripped)

**Classification**: `categories[]`, `primaryCategory`

**Address**: `streetAddress`, `suburb`, `city`, `region` (NZ region code), `postcode`, `country`

**Location**: `latitude`, `longitude`

**Reputation**: `rating`, `reviewCount`, `reviews[]` (author, date, rating, body)

**Operations**: `openingHours[]`, `paymentAccepted`, `image`

**Meta**: `isAd`, `source` (`search` | `detail`), `scrapedAt`

### FAQ

**Is email really included for free?** Yes. yellow.co.nz exposes business emails in the profile page's JSON-LD. In full-detail mode every result that has an email on its profile page returns it in the `email` field. No add-on, no extra charge.

**Why do I need a residential proxy?** yellow.co.nz is behind Cloudflare's managed challenge. Datacenter IPs get HTTP 403. The actor's residential fallback chain (Evomi → IPCook → Apify RESIDENTIAL) handles this automatically.

**What's the difference between the two modes?** `fetchFullDetails: true` opens each profile page — slower but returns email, full split address, hours, reviews, description, payment methods. `false` parses only the search-page cards — fast and cheap, returns name, phone, category, website, rating, review count, city, coordinates.

**How many businesses per search page?** 30. The actor paginates automatically up to `maxPages` (0 = unlimited) or until `maxItems` is reached.

**Does it scrape whitepages.co.nz?** No. White Pages is a separate site behind Google reCAPTCHA. This actor covers yellow.co.nz only.

**Can I scrape a single business?** Yes — paste its profile URL into `startUrls` with `fetchFullDetails: true`.

### Support

- **Issues**: [Apify Console → Issues](https://console.apify.com/actors/2kiwoYEx0lwoX4cF9/issues)
- **Author**: [memo23](https://apify.com/memo23)

### Additional Services

Need a custom export format, a specific filter (e.g. only businesses with email, only rating ≥ 4), or integration with your CRM? Reach out via the Issues tab or Apify — custom work is available.

### Explore More Scrapers

See the full [memo23 actor portfolio](https://apify.com/memo23) for other directory, real estate, and lead-generation scrapers.

### ⚠️ Disclaimer

This actor is not affiliated with, endorsed by, or sponsored by Yellow Pages Group or yellow.co.nz. "Yellow Pages" is a trademark of its respective owner. The actor scrapes publicly accessible business directory pages only, in accordance with the site's terms of service. It does not access logged-in or paywalled content. Users are responsible for complying with all applicable laws and regulations, including the GDPR, CCPA, and New Zealand privacy law, when using data scraped from this site. Do not use this actor to send unsolicited commercial electronic messages in breach of the New Zealand Unsolicited Electronic Messages Act 2007.

### SEO Keywords

yellow pages nz scraper, yellow.co.nz scraper, new zealand business directory, nz business leads, nz b2b leads, yellow pages nz email, nz business phone numbers, auckland business directory, wellington business directory, christchurch business directory, nz plumber leads, nz electrician leads, nz business contact list, nz company directory scraper, yellow pages nz api, nz business address data, nz business coordinates, nz business reviews, nz opening hours data, nz lead generation scraper, nz business email finder, scrape yellow pages new zealand

# Actor input Schema

## `searchQueries` (type: `array`):

Business types or keywords to search on yellow.co.nz, one per line (e.g. plumber, cafe, accountant, electrician). Each query runs across every location in the Locations field.

## `locations` (type: `array`):

New Zealand cities or regions to search, one per line (e.g. Auckland, Wellington, Christchurch). Leave empty to search nationwide (New Zealand).

## `startUrls` (type: `array`):

Paste yellow.co.nz search or business-profile URLs, one per line. A search URL (https://www.yellow.co.nz/search?search_terms=plumber\&geo_location_terms=Auckland) is decomposed into its keyword + location and returns the same results. A business-profile URL (https://www.yellow.co.nz/auckland/bpp/ak-speech-therapy-579486261) is scraped directly for full details. Combines with the Search Queries / Locations fields.

## `fetchFullDetails` (type: `boolean`):

When on, each business profile page is opened to add its email, full split address, opening hours, coordinates, description, payment methods, and reviews. When off, only the fast listing-level fields (name, phone, category, website, address, rating) are returned. Email is only available with full details.

## `maxItems` (type: `integer`):

Maximum number of businesses to collect across all searches.

## `maxPages` (type: `integer`):

Maximum number of search pages to crawl per query×location (30 businesses per page). 0 = unlimited.

## `maxConcurrency` (type: `integer`):

Maximum number of pages fetched in parallel.

## `proxy` (type: `object`):

Leave empty to use the default residential proxy. yellow.co.nz is behind Cloudflare, so a residential proxy is required.

## Actor input object example

```json
{
  "searchQueries": [
    "plumber"
  ],
  "locations": [
    "Auckland"
  ],
  "startUrls": [],
  "fetchFullDetails": true,
  "maxItems": 1000,
  "maxPages": 0,
  "maxConcurrency": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "searchQueries": [
        "plumber"
    ],
    "locations": [
        "Auckland"
    ],
    "startUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("memo23/yellowpages-nz-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 = {
    "searchQueries": ["plumber"],
    "locations": ["Auckland"],
    "startUrls": [],
}

# Run the Actor and wait for it to finish
run = client.actor("memo23/yellowpages-nz-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "searchQueries": [
    "plumber"
  ],
  "locations": [
    "Auckland"
  ],
  "startUrls": []
}' |
apify call memo23/yellowpages-nz-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,memo23/yellowpages-nz-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/2kiwoYEx0lwoX4cF9/builds/IFyTcDV6WlGFUS5rS/openapi.json