Yellow NZ Business Scraper

Scrapes business listings from Yellow.co.nz (New Zealand Yellow Pages). Extract comprehensive business information including contact details, emails, ratings, reviews, opening hours, and geo coordinates.

Features

Core Capabilities

• Comprehensive Data Extraction: Business names, phone, email, address, ratings, reviews, opening hours, geo coordinates, and more
• Flexible Search: Search by any keyword and location across New Zealand
• Pagination Support: Automatically handles pagination to fetch all results
• Detail Page Enrichment: Optional deep scraping via JSON-LD structured data for full business profiles
• Proxy Support: Optional proxy configuration for large-scale scraping

Perfect for Lead Generation

• Direct Contact Information: Extract phone numbers and email addresses for immediate outreach
• Location Intelligence: Full addresses with latitude/longitude coordinates for geo-targeting
• Business Verification: Year established, associations, and payment methods for lead qualification
• Customer Reviews: Star ratings, review counts, and full review text for quality assessment

AI-Ready Data Structure

• Structured JSON Output: Clean, consistent data format perfect for AI processing and analysis
• Rich Context: Business descriptions, services, slogan, and customer reviews for AI understanding
• Geo Data: Latitude/longitude coordinates for location-based analysis and mapping
• Training Data: Comprehensive business profiles ideal for training recommendation systems

Input Parameters

Parameter	Type	Description	Default
searchTerms	string	Business type or keyword (e.g., 'Plumbers', 'Restaurants')	Plumbers
location	string	Location (e.g., 'New Zealand', 'Auckland', 'Wellington')	New Zealand
maxPages	integer	Optional bound on search result pages walked (30 listings per page). Leave empty to walk every result page; the run size is controlled by maxListings, which this field defers to.	none (unlimited)
maxListings	integer	Hard cap on total business listings returned. 0 means no cap (bounded by maxPages / result count instead).	20
scrapeDetails	boolean	Fetch detail pages for rich data (email, geo, hours, reviews)	true
maxConcurrency	integer	Concurrent detail page requests (1-20)	5
proxy	object	Optional proxy configuration	null

Resume & recurring updates

Two different things, both in one input section because they're 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 (e.g. daily/weekly) and getting only what changed, without pasting a run ID every time. The actor remembers its own baseline in a key-value store, keyed by a hash of searchTerms + location + scrapeDetails (caps like maxListings/maxPages/maxConcurrency are deliberately excluded from that key — changing them alone never starts a new monitoring campaign). Use stateKey to name a campaign explicitly or to share state across differently-configured runs.

Parameter	Type	Description	Default
resumeFromRunId	string	Paste a previous run ID (or dataset ID) from this actor.	none
incrementalMode	boolean	Turn on for recurring monitoring of the same search. First run: everything is NEW. Later runs: only NEW/UPDATED/REAPPEARED by default.	false
stateKey	string	Optional. Name the monitoring campaign; leave empty to derive one automatically from the search scope.	none
emitUnchanged	boolean	Also return (and bill for) listings unchanged since the last run, marked UNCHANGED.	false
emitExpired	boolean	Also return (and bill for) listings from a previous run no longer found, marked EXPIRED. Only fires after a run that scanned the tracked search to its natural end — never on a resumed or maxListings/maxPages-capped run.	false

Each output record in incremental mode gets four extra fields: changeType (NEW/UPDATED/UNCHANGED/REAPPEARED/EXPIRED), changedFields, firstSeenAt, lastSeenAt.

What counts as "changed": every field is compared except a couple of intentional exclusions —

• openStatus ("OPEN NOW"/"CLOSED NOW") is a function of the business's fixed hours crossed with the current wall-clock time, not of the business itself — it would flip within the same day with nothing about the business changing, so it's excluded from change detection (it's still shown in the output, unchanged).
• imageUrl/logoUrl: Yellow.co.nz serves these from a small pool of CDN mirror hosts (i1–i4.ypcdn.com) chosen per-request — confirmed with two live fetches ~4 minutes apart, where 4 of 6 sampled businesses' logoUrl came back with the identical image but a different mirror host. Only the CDN host is normalized away for change detection; the URL returned in the output is always the real one observed.
• description (the search-results snippet): Yellow.co.nz sometimes serves it cut short mid-sentence with a trailing …, at a different cut point on different requests — confirmed live, same business, same text, one fetch ending …today. We await your call! and the next ending …today. We…. A pair where the shorter side is a truncation-marked prefix of the longer side is treated as unchanged; a genuine edit (the shorter side does not end in …/...) still registers as UPDATED naming description.
• address: Yellow.co.nz is inconsistent about whether it includes the NZ region abbreviation (e.g. BOP for Bay of Plenty) as a comma segment, and about the comma before the postcode — confirmed live, same business, "18 Macdonald Street, Mount Maunganui, BOP, 3116" vs "18 Macdonald Street, Mount Maunganui 3116". Only that region-code segment and surrounding punctuation are normalized away for change detection; a genuinely different street number, street name, or postcode still registers as UPDATED naming address, and the value returned in the output is always the real one observed.
• address (service-area substitution): some cards render "Servicing: <region list>" in place of a street address — confirmed live, same business, "58 Arthur Street, Blenheim, MBH, 7201" became "Servicing: Canterbury Region, Marlborough Region, ..." on a later fetch. That text is not an address, so it's treated like a failed/partial fetch (see below): the run's output and the stored baseline keep the last known real street address instead of overwriting it. A business that has never had a real street address (only ever a service area) keeps showing that service-area text — it never collapses to an empty address.

Failed/partial detail fetch: if a business's detail page fails to fetch (or a field is empty) on a given run, that field is backfilled from the last known good value before comparison, so a transient failure doesn't look like the business lost data, and doesn't poison next run's comparison with a spurious change. A field that never had a real value before still comes back 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.

Output Format

Search-Only Data

Each business record includes:

{
  "name": "Crawshaw Sample Ltd",
  "phone": "07 012 1234",
  "address": "Servicing: Waikato Region",
  "categories": ["Plumbers"],
  "rating": 5.0,
  "reviewCount": 2,
  "openStatus": "CLOSED NOW",
  "website": "https://example.co.nz",
  "description": "At Sample Plumbers we are experienced...",
  "detailUrl": "https://yellow.co.nz/hamilton/bpp/crawshaw-plumbers-ltd-12345678",
  "searchTerms": "Plumbers",
  "searchLocation": "New Zealand"
}

Enriched Data (when scrapeDetails: true)

Additional fields from detail pages:

{
  "email": "info@example.co.nz",
  "fullAddress": {
    "street": "10 Sample Street",
    "locality": "Lower Hutt",
    "region": "WGN",
    "postalCode": "5012",
    "country": "NZ"
  },
  "latitude": -41.23,
  "longitude": 174.89,
  "openingHours": ["Mo-Fr 07:00-17:00", "Sa 08:00-12:00"],
  "paymentAccepted": "visa, cash, mastercard",
  "imageUrl": "https://i3.ypcdn.com/blob/...",
  "logoUrl": "https://i1.ypcdn.com/blob/...",
  "reviews": [
    {
      "author": "John Smith",
      "rating": 5,
      "text": "Excellent service...",
      "date": "2024-03-15"
    }
  ],
  "yearEstablished": "1950",
  "slogan": "Your trusted local plumber",
  "associations": "Master Plumbers, Gasfitters & Drainlayers NZ",
  "generalInfo": "Full business description...",
  "servicesAndProducts": ["Plumbing", "Drainage", "Gasfitting"]
}