Yellow Pages NZ $0.8💰 Scraper

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.

URL mode (Start URLs)

Paste yellow.co.nz links into Start URLs and the run scrapes them instead of running a keyword search. Search Terms and Location are ignored when you do. Plain place names work in Location (for example Ponsonby or Auckland), and a search that matches nothing finishes cleanly with an empty dataset rather than an error.

Link type	Example	What you get
Search results	https://yellow.co.nz/search?search_terms=Plumbers&geo_location_terms=Auckland	Every listing on the results pages, page after page (a page= value in the link is honoured).
Browse page (place and category)	https://yellow.co.nz/auckland/plumbers	The listings of that place and category, page after page.
One business page	https://yellow.co.nz/auckland/bpp/onehunga-plumbers-579426046	That single business, identified by the number at the end of the link (never by a text search).

Any other yellow.co.nz or non-yellow.co.nz link is skipped, with a warning in the run log naming the link.

Untouched form: the Start URLs field ships with one example of each link type above. If you run with the field untouched and Search Terms and Location unchanged, the run scrapes those three examples (bounded by Max Listings). If you only change Search Terms or Location (for example through the API) while leaving Start URLs untouched, the keyword search runs exactly as before. Clear the list, or send an empty list, to force a keyword search.

Several searches, filters and flat fields

• Search Queries / Locations: give several keywords and several New Zealand places in one run; every keyword and place pair is searched once and duplicates are removed. Empty lists fall back to Search Terms and Location.
• Filters (applied to the scraped result, so the run still reads the pages behind them): Minimum rating, Only businesses with an email, Only businesses with a website. Only listings that pass count towards Max Listings and are billed as results. Email filtering needs Scrape Detail Pages.
• Extra flat fields on every row: businessId, listingUrl, category, street, city, suburb, region, postalCode, country, addressText, allEmails, emailSource, searchQuery, source, observedAt. suburb is read from the search-result address when it has a separate suburb segment (for example "Auckland Central"), also on rows whose detail page loaded, otherwise it is absent; city and postalCode fall back to the card address when the detail page has no structured address. The nested fields stay unchanged.
• Sorting is not offered: the site has no verified sort option. Email and contact enrichment beyond the business page is not part of this actor.

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").
searchQueries	array	none	Several keywords in one run; combined with Locations, each pair searched once, duplicates removed. Empty uses Search Terms. Ignored when Start URLs is customised; Start URLs left at the shipped examples do not block it.
locations	array	none	Several New Zealand places in one run. Empty uses Location.
minRating	number	none	Keep only businesses rated at least this (1-5); unrated businesses are dropped when set.
hasEmail	boolean	false	Keep only businesses whose page shows an email. Needs Scrape Detail Pages.
hasWebsite	boolean	false	Keep only businesses that list a website.
startUrls	array	three example links (one per link type)	Paste yellow.co.nz links instead of typing a search. See the URL mode table below.
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.
maxReviews	integer	20	Most customer reviews kept per business (0 to 100; needs Scrape Detail Pages). The business pages list at most 5 reviews, so the default of 20 does not cut anything today; the cap only matters if the site shows more. Changing it never marks a business as updated in incremental mode. Reviews are included in the per-record price, nothing extra is charged.
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 (backup connection)	Proxy configuration. Apify Proxy with the RESIDENTIAL group is recommended; see Plan Requirement.
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.
ignoreFieldsForChanges	array	none	Incremental mode only: field names (dots for nested, e.g. reviews.date) that never count as a change. They stay in the output; openStatus is always ignored.
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

Yellow.co.nz refuses most requests that do not come from a residential connection, so for dependable results use Proxy Configuration with Apify Proxy and the RESIDENTIAL group. Choosing it without a country pins the connection to New Zealand. Even then a single connection can be refused, so the actor retries each page on a fresh connection and falls back to a backup connection when the selected one is unavailable.

Apify free plans do not include residential proxies. On a free plan, or with no proxy set, the run continues on the backup connection and logs a warning that some pages may still be unavailable. If the very first results page cannot be loaded, the run fails with a clear message instead of returning an empty dataset. To get residential access, upgrade your Apify plan or supply your own proxy URLs.

FAQ

How much does it cost?

Billing has two events. A start charge applies once per run, scaled by the memory the run uses (per GB). On top of that, each result row written to the dataset is charged once. Rows that are not delivered (for example unchanged listings in incremental mode, unless you turn on Emit unchanged listings) are not charged. 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 Scraper Scrape Yellow Pages Australia (yellowpages.com.au) business listings by category and...	📇 PagesJaunes FR Scrapes business listings from PagesJaunes.fr (French Yellow Pages). Extract...
📇 Herold.at Scraper Scrape Herold.at business listings across Austria into clean JSON. Extract names...	📇 TrueLocal AU Directory Listings & Reviews Scraper Scrape TrueLocal.com.au business listings by keyword, location, or URL. Extract names...
📇 Local.ch Pull structured company data from local.ch, including name, address, GPS, phone, email...	📇 HiPages Scraper Scrape business listings from HiPages Australia by category, location, or URL. Extract...

👉 Browse all abotapi scrapers

💬 Support

• 🐞 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 contact@abotapi.com.
• ⭐ Enjoying it? A quick review on the actor page helps other users find it.