Yellow.co.nz Scraper: Business Contacts, Ratings & Reviews

Yellow.co.nz Scraper turns New Zealand's Yellow Pages directory into structured business data. Search any trade or keyword in any NZ location and get contact details, ratings, reviews, opening hours and geo coordinates for every matching business. Run a one-off search, resume an interrupted run, or track a search on a schedule with incremental mode to get only new and changed listings, then export to JSON, CSV or Excel, or pull the results straight into your app through the API.

Why This Scraper?

• Full contact data from every listing. Phone, email, full postal address, latitude and longitude, and opening hours, pulled straight from each business's detail page.
• Search by any trade and any NZ location. Enter a keyword and a place name, no need to browse categories by hand.
• Automatic pagination. Walks every search result page for you, with independent caps on pages and total listings so you control run size and cost.
• Deep enrichment on demand. Turn on detail page scraping for reviews, star ratings, year established, trade associations, services and payment methods, or leave it off for a fast, contact only pass.
• Built for schedules. Incremental mode returns only new and changed listings on recurring runs, and a genuinely blocked first page fails the run loudly instead of quietly returning an empty dataset.
• Resume support. Continue an interrupted run from its run or dataset ID without re-collecting, and re-paying for, listings already gathered.
• Pipe results into your apps. Optionally send a summary of each business straight into Notion, Linear or Airtable through MCP connectors.

Use Cases

• Lead generation teams: pull phone numbers and email addresses for a trade and region to build an outreach list.
• Local SEO and directory agencies: audit categories, ratings and review counts for a niche across multiple towns.
• Market researchers: build a census of every business in a trade across New Zealand, complete with location data for mapping.
• Ops and compliance teams: track new competitors or closures in a market with scheduled incremental runs.

Data You Get

Sample shape: values are illustrative placeholders, not from a live record.

Field	Example
name	"Example Plumbing Services Ltd"
phone	"07 012 3456"
email	"info@example-plumbing.co.nz" (when detail pages are scraped)
address	"10 Example Street, Hamilton, WKO, 3200"
fullAddress	{ "street": "10 Example Street", "locality": "Hamilton", "region": "WKO", "postalCode": "3200", "country": "NZ" }
latitude / longitude	-37.787 / 175.2793
categories	["Plumbers", "Drainlayers"]
rating	4.5
reviewCount	12
reviews	[{ "author": "Jane Example", "rating": 5, "text": "Quick, tidy and reasonably priced.", "date": "2024-03-15" }]
website	"https://example-plumbing.co.nz"
detailUrl	"https://yellow.co.nz/hamilton/bpp/example-plumbing-services-12345678"
openStatus	"OPEN NOW" (also "CLOSED NOW")
openingHours	["Mo-Fr 07:00-17:00", "Sa 08:00-12:00"]
description	"Example Plumbing Services has been serving Hamilton homes and businesses since 1998..."
yearEstablished	"1998"
slogan	"Your trusted local plumber"
associations	"Master Plumbers, Gasfitters and Drainlayers NZ"
paymentAccepted	"visa, cash, mastercard"
servicesAndProducts	["Plumbing", "Drainage", "Gasfitting"]
imageUrl / logoUrl	"https://i2.ypcdn.com/blob/..." / "https://i1.ypcdn.com/blob/..."
searchTerms / searchLocation	"Plumbers" / "Hamilton"
changeType (incremental mode only)	"NEW" (also UPDATED / UNCHANGED / REAPPEARED / EXPIRED)
changedFields / firstSeenAt / lastSeenAt (incremental mode only)	["phone"] / "2026-01-01T00:00:00Z" / "2026-01-02T00:00:00Z"

Detail pages can also return generalInfo, a longer business description than the search snippet, when a business's profile carries one. The four incremental mode fields above appear only when incrementalMode is on; on a normal run they are absent from the record entirely, not empty.

How to Use

1. Enter Search Terms (a trade or keyword) and Location (a city, region, or "New Zealand").
2. Turn Scrape Detail Pages on for full contact and profile data, or off for a fast, search-results-only pass.
3. Set Max Listings and/or Max Pages to control run size and cost, and Max Concurrency to control how many detail pages fetch at once.
4. Click Start, then download the dataset as JSON, CSV or Excel, or read it through the API.

A quick contact list, no detail pages:

{
  "searchTerms": "Electricians",
  "location": "Auckland",
  "scrapeDetails": false,
  "maxListings": 50
}

Full enrichment with an explicit proxy group:

{
  "searchTerms": "Plumbers",
  "location": "Wellington",
  "scrapeDetails": true,
  "maxConcurrency": 5,
  "maxListings": 100,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}

Track a search on a schedule, only new and changed listings:

{
  "searchTerms": "Cafes",
  "location": "Christchurch",
  "incrementalMode": true,
  "stateKey": "christchurch-cafes",
  "emitExpired": true
}

Resume an interrupted run:

{
  "searchTerms": "Builders",
  "location": "New Zealand",
  "resumeFromRunId": "<PREVIOUS_RUN_OR_DATASET_ID>",
  "maxListings": 0
}

Run it from your code

Python:

from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("abotapi/yellow-nz-scraper").call(run_input={"searchTerms": "Plumbers", "location": "Auckland"})
for business in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(business["name"], business.get("phone"))

JavaScript:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('abotapi/yellow-nz-scraper').call({ searchTerms: 'Plumbers', location: 'Auckland' });
const { items } = await client.dataset(run.defaultDatasetId).listItems();

Or connect it to Make, Zapier, n8n, Google Sheets or webhooks from the Integrations tab.

How Max Pages and Max Listings interact

Yellow.co.nz serves roughly 30 listings per search results page. Max Pages bounds how many of those pages the actor walks; leave it empty to walk every page the site has for that search. Max Listings is the actual run size cap, checked before each page is processed, so a run stops as soon as it has collected enough listings even if Max Pages would allow more. 0 on Max Listings, or an empty or 0 Max Pages, means no cap from that field; an empty Max Listings falls back to its default of 20.

Resume and recurring updates

Two different things, both in the same input section because they are easy to confuse:

• Resume from run ID (resumeFromRunId) continues ONE specific interrupted run. Paste a previous run ID (or dataset ID) from this actor; listings already collected there are skipped, so this run only returns new ones.
• Incremental mode (incrementalMode) is for running the same search again and again (daily or weekly) and getting only what changed, without pasting a run ID every time. The actor keeps its own baseline in a key-value store, keyed by a hash of searchTerms + location + scrapeDetails (the caps maxListings / maxPages / maxConcurrency are deliberately excluded from that key, so changing them alone never starts a new monitoring campaign). Use stateKey to name a campaign explicitly or to share state across differently-configured runs.

Each output record in incremental mode gets four extra fields: changeType (NEW / UPDATED / UNCHANGED / REAPPEARED / EXPIRED), changedFields, firstSeenAt, lastSeenAt. UNCHANGED listings are suppressed (not returned, not billed) unless emitUnchanged is on.

EXPIRED rows are produced only once a run has scanned the tracked search to a genuine, uncapped, non-resumed end, and only when emitExpired is on. A run interrupted by a page failure, a maxListings or maxPages cap, or a resumed continuation never emits EXPIRED rows, and the stored state for those listings is left exactly as it was. REAPPEARED can only happen to a listing that a PRIOR complete, emitExpired run had already marked EXPIRED; a listing that was simply never marked gone stays UNCHANGED or turns UPDATED, it is never REAPPEARED on its own.

What counts as "changed": every field is compared except a few intentional exclusions, so the site's own rendering quirks never look like a business changed.

• openStatus ("OPEN NOW" / "CLOSED NOW") reflects the business's fixed hours crossed with the current time, not the business itself, so it is excluded from change detection while still being shown in the output.
• imageUrl / logoUrl are served from a small pool of mirror hosts chosen per request; only the mirror host is normalized away for comparison, the URL in the output is always the one actually observed.
• description (the search-results snippet) is sometimes served cut short mid-sentence with a trailing ellipsis. A pair where the shorter side is a truncation-marked prefix of the longer side is treated as unchanged; a genuine edit still registers as UPDATED.
• address sometimes includes an NZ region-code segment and sometimes does not. Only that formatting difference is normalized away; a genuinely different street number, name or postcode still registers as UPDATED.
• address occasionally renders as a "Servicing:

Failed or partial detail fetch: if a business's detail page fails to fetch, or a field comes back empty, on a given run, that field is backfilled from the last known good value before comparison, so a transient failure never looks like the business lost data and never poisons the next comparison. A field that never had a real value stays empty; nothing is invented.

Send results into your apps (MCP connectors)

Optionally pipe the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. This is an extra delivery step after the scrape; the Apify dataset is never changed.

What gets written to the connector: a condensed, human-readable summary of each record, not the full JSON. Each item becomes one entry with a title and its key fields flattened to plain text. The complete record always stays in the Apify dataset.

1. Authorize a connector once under Apify → Settings → Integrations (Notion, Linear, Airtable, or Apify).
2. Select it in the "Pipe results into your apps" input field. (If the picker is empty, you haven't authorized a connector yet.)
3. For Notion, also set notionParentPageUrl to the page where items should be created.

The connection is mediated by Apify's MCP proxy, so this actor never sees your third-party credentials. Leave the field empty to skip.

Input Parameters

Parameter	Type	Default	Description
searchTerms	string	Plumbers	Business type or keyword to search for.
location	string	New Zealand	Location to search in (city, region, or "New Zealand").
maxPages	integer	none (empty walks every result page)	Optional bound on how many search result pages to walk (roughly 30 listings per page); the run size is otherwise controlled by Max Listings.
maxListings	integer	20	Hard cap on total business listings returned. 0 means no cap.
scrapeDetails	boolean	true	Fetch each business's detail page for email, full address, geo coordinates, opening hours, reviews and more.
maxConcurrency	integer	5	Maximum concurrent detail page requests (1-20).
proxy	object	none (runs without a proxy)	Optional proxy configuration; recommended for large runs.
resumeFromRunId	string	none	Continue one interrupted run: paste its run or dataset ID and already-collected listings are skipped.
incrementalMode	boolean	false	Turn on for recurring monitoring of the same search; later runs return only NEW and UPDATED listings (plus REAPPEARED, once an earlier run with Emit expired listings on had marked a listing EXPIRED).
stateKey	string	none	Optional. Name a monitoring campaign, or share state deliberately across differently-configured runs.
emitUnchanged	boolean	false	Also return (and bill for) listings unchanged since the last run, marked UNCHANGED.
emitExpired	boolean	false	Also return (and bill for) listings from a previous run no longer found, marked EXPIRED. Only produced after a run that scanned the tracked search to its natural end, never on a resumed or capped run.
mcpConnectors	array	none	Optional: send a summary of each record to apps you authorized under Integrations.
notionParentPageUrl	string	none	Notion connector only: page under which item pages are created.
maxNotifyListings	integer	50	Cap on items written to each connector per run. Does not affect the dataset.

Output Example

Sample shape: values are illustrative placeholders, not from a live record.

{
  "name": "Example Plumbing Services Ltd",
  "phone": "07 012 3456",
  "email": "info@example-plumbing.co.nz",
  "address": "10 Example Street, Hamilton, WKO, 3200",
  "fullAddress": {
    "street": "10 Example Street",
    "locality": "Hamilton",
    "region": "WKO",
    "postalCode": "3200",
    "country": "NZ"
  },
  "latitude": -37.787,
  "longitude": 175.2793,
  "categories": ["Plumbers", "Drainlayers"],
  "rating": 4.5,
  "reviewCount": 12,
  "reviews": [
    {
      "author": "Jane Example",
      "rating": 5,
      "text": "Quick, tidy and reasonably priced.",
      "date": "2024-03-15"
    }
  ],
  "website": "https://example-plumbing.co.nz",
  "detailUrl": "https://yellow.co.nz/hamilton/bpp/example-plumbing-services-12345678",
  "openStatus": "OPEN NOW",
  "openingHours": ["Mo-Fr 07:00-17:00", "Sa 08:00-12:00"],
  "description": "Example Plumbing Services has been serving Hamilton homes and businesses since 1998...",
  "yearEstablished": "1998",
  "slogan": "Your trusted local plumber",
  "associations": "Master Plumbers, Gasfitters and Drainlayers NZ",
  "paymentAccepted": "visa, cash, mastercard",
  "servicesAndProducts": ["Plumbing", "Drainage", "Gasfitting"],
  "imageUrl": "https://i2.ypcdn.com/blob/example-image",
  "logoUrl": "https://i1.ypcdn.com/blob/example-logo",
  "searchTerms": "Plumbers",
  "searchLocation": "Hamilton"
}

Plan Requirement

This actor runs without a proxy by default and works out of the box for light use. For large or frequent runs, set Proxy Configuration to Apify Proxy; the residential group gives more headroom for New Zealand searches specifically, and choosing it without a country automatically pins the connection to New Zealand.

FAQ

How much does it cost?

You pay per record returned. The Pricing tab on the actor page shows the current rates. Use Max Listings (and Max Pages) to cap the cost of any run.

Is it legal to scrape Yellow.co.nz?

This actor collects only publicly available business listing data. You are responsible for how you use it: follow Yellow.co.nz's terms and the laws that apply to you, and get legal advice if you plan commercial redistribution. Customer reviews and photos may carry their own rights beyond the underlying facts.

Can I track a search on a schedule and get only new or changed listings?

Yes. Schedule the actor from the Schedules tab and turn on Incremental changes for scheduled runs. Later runs then return only NEW and UPDATED listings (plus REAPPEARED for a listing that an earlier run with Emit expired listings on had marked EXPIRED); unchanged listings are not billed unless you also turn on Emit unchanged listings.

What's the difference between Resume from run ID and Incremental mode?

They solve different problems. Resume from run ID continues ONE specific interrupted run from a pasted run or dataset ID. Incremental mode is for running the SAME search again and again on a schedule; the actor remembers its own baseline and classifies every listing against it, so you never have to paste an ID.

Why did my run fail instead of returning an empty dataset?

If Yellow.co.nz refuses every attempt at the very first search page, the run fails with a clear message instead of reporting success with nothing collected, so a genuinely blocked run is never confused with a search that legitimately matched zero businesses. A refusal on a later page, after real listings were already collected, does not fail the run; it keeps what was already gathered.

Can I use it with AI agents or MCP?

Yes. Call it from any Apify integration or MCP client, and use the connector field to push results into Notion, Linear or Airtable.

🔗 Want more Yellow data?

Pair this actor with these related scrapers from the same team:

📇 Yellow Pages AU From $1/1K. Scrape business listings from Yellow Pages Australia by type and location...	📇 PagesJaunes FR From $0.8/1K. Scrapes business listings from PagesJaunes.fr (French Yellow Pages)...
📇 Herold.at Scraper From $0.80/1K. Scrape Herold.at business listings across Austria into clean JSON. Extract...	📇 2GIS From $1/1K. Extract business and place data from 2GIS.com at scale. Get names, addresses...
📇 HiPages Scraper Scrape business listings from HiPages Australia by category, location, or URL. Extract...	📇 BBB Scraper Scrape bbb.org (Better Business Bureau, USA & Canada) business profiles: BBB rating...

👉 Browse all abotapi scrapers

💬 Support & custom scrapers

• 🐞 Found a bug or a missing field? Open a ticket on the Issues tab. We usually reply within hours.
• 🛠️ Need another site, extra fields or a private build? Email abotapi@proton.me or message Telegram @abotapi.
• ⭐ Enjoying it? A quick review on the actor page helps other users find it.