# Kiwi Directory Scraper - New Zealand Business Directory (`crawlerbros/kiwi-directory-scraper`) Actor Scrape kiwidirectory.co.nz, a New Zealand business directory. Search by category and region, or fetch full business profiles by URL. Get names, addresses, phone numbers, categories, opening hours, websites, social links, images and geo-coordinates. - **URL**: https://apify.com/crawlerbros/kiwi-directory-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Lead generation, SEO tools - **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 and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## Kiwi Directory Scraper - New Zealand Business Directory Scrape **kiwidirectory.co.nz** — a New Zealand business directory. Search any business category or region, or run a free-text keyword search, and get names, addresses, phone numbers, categories, regions, opening hours, websites, social links, GPS coordinates, and photos. No login, no cookies, no API key required. ### What this actor does - **Four modes:** `search` (category and/or region and/or keyword), `byCategory` (browse one category), `byRegion` (browse one region), `byUrl` (fetch specific listing URLs) - **9 curated categories** — Automotive, Entertainment, Health, Home & Garden, Marine, Miscellaneous, Professional, Real Estate, Travel & Tourism - **7 New Zealand regions** — Auckland, Canterbury, Northland, Wellington, Waikato, Marlborough, Manawatu-Whanganui - **Free-text keyword search** across business names and descriptions - **Sort by** relevance, name (A-Z), or region (A-Z) - **Filter by** "has a website", "has a phone number", and/or "featured listing only" - **Rich business profiles** — GPS coordinates, structured opening hours, website, Facebook/Instagram/LinkedIn/Twitter/YouTube links, photos - **Full Māori macron support** — names like Whāngārei are handled correctly in both input and output - **Empty fields are omitted** — you only ever see fields that were actually found for a business ### Output per business - `name` — business name - `description` — business description - `searchCategory` — the category this business was found under (mode=search / byCategory) - `region`, `subRegion` — New Zealand region and sub-region/city, from the business's own address - `searchRegion` — the region this business was found under (mode=search / byRegion) - `street`, `city`, `postalCode`, `country` - `latitude`, `longitude` — GPS coordinates - `phone`, `email`, `website` - `facebookUrl`, `instagramUrl`, `linkedinUrl`, `twitterUrl`, `youtubeUrl` — social links the business has published - `rating`, `reviewCount` — when the business has received at least one review - `featured` — `true` when kiwidirectory.co.nz marks the listing with its own "Featured" badge on browse pages (omitted, not `false`, otherwise) - `openingHours[]` — structured opening hours (`{day, opens, closes}` per slot), when published - `images[]` — business photos - `sourceUrl` — canonical kiwidirectory.co.nz listing URL for the business - `recordType: "business"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string (select) | `search` | `search`, `byCategory`, `byRegion`, or `byUrl` | | `category` | string (select) | `automotive` | One of 9 categories, or "All categories" (mode=search, byCategory) | | `region` | string (select) | – (all) | One of 7 NZ regions, or "All regions" (mode=search, byRegion) | | `keyword` | string | – | Free-text keyword search (mode=search, used when category is "All categories") | | `businessUrls` | array | – | kiwidirectory.co.nz listing URLs to fetch directly (mode=byUrl) | | `sortBy` | string (select) | `relevance` | `relevance` / `name` (A-Z) / `region` (A-Z) — applied client-side across the fetched batch | | `hasWebsiteOnly` | boolean | `false` | Only return businesses with a website link | | `hasPhoneOnly` | boolean | `false` | Only return businesses with a phone number | | `featuredOnly` | boolean | `false` | Only return businesses marked "Featured" by the site itself | | `maxItems` | int | `20` | Hard cap on returned records (1-500) | #### Example: browse all automotive businesses ```json { "mode": "byCategory", "category": "automotive", "maxItems": 20 } ```` #### Example: browse businesses in the Auckland region ```json { "mode": "byRegion", "region": "auckland", "maxItems": 20 } ``` #### Example: keyword search with filters ```json { "mode": "search", "category": "", "keyword": "dent removal", "hasWebsiteOnly": true, "maxItems": 20 } ``` #### Example: fetch specific business profiles ```json { "mode": "byUrl", "businessUrls": [ { "url": "https://kiwidirectory.co.nz/listings/dent-devils-paintless-dent-removal/" } ] } ``` ### Use cases - **Local lead generation** — build a prospect list of New Zealand businesses by trade and region for B2B outreach - **Market research** — see business density and coverage for a category across NZ regions - **Directory aggregation** — feed structured New Zealand business data into your own local-search product - **Competitor mapping** — see who else operates in a category and region, with contact info - **Data enrichment** — resolve `businessUrls` you already have (e.g. from a sitemap or another source) into full structured profiles ### Data source and a note on Yellow.co.nz This actor's original target was **yellow.co.nz**, New Zealand's best-known business directory. During development we found that yellow.co.nz's edge network (CloudFront) returns a hard `403 Request blocked` response to every request from outside New Zealand — confirmed identical across a direct HTTP request, a full headless-Chromium browser session, and an actual Apify cloud run through both no-proxy and Apify's free AUTO datacenter-proxy group. The block is a static, pre-rendered error page (not a bot/JS challenge), which means it is enforced at the network edge rather than by inspecting the request — no proxy tier available on Apify's free plan can pass it, and using a paid residential/geo-targeted proxy is outside this actor's zero-cost design. **kiwidirectory.co.nz** was selected as a same-category, unblocked replacement: a real, live New Zealand business directory (WordPress + GeoDirectory) that publishes clean, structured `schema.org LocalBusiness` data for every listing. It is smaller in scale than yellow.co.nz (roughly 100+ listings across 9 categories and 7 regions at the time of writing, and growing), which is reflected honestly below rather than padded with placeholder data. ### Limitations - **Directory size.** kiwidirectory.co.nz is a boutique NZ directory, not a nationwide index — expect roughly 5-25 listings per category and a total in the low hundreds. Every returned record is real, verified data; this actor never fabricates or pads results to reach `maxItems`. - **No combined category + region URL.** The site itself doesn't expose a single URL that filters by both category and region at once. When both are set in `search` mode, the actor crawls the category's listing pages and applies the region as a client-side filter, so total matches can be smaller than either dimension alone. - **`sortBy`, `hasWebsiteOnly`, `hasPhoneOnly`, `featuredOnly` are applied client-side.** The site's own listing pages don't support a sort or has-website/has-phone/featured query parameter, so these are applied across the batch of records this run actually fetched. - **Ratings.** Most listings currently have zero reviews, so `rating`/`reviewCount` are present only on the (currently few) businesses that have received at least one review — this is expected and not a bug. ### FAQ **What data source does this actor use?** It reads the publicly available category, region, search, and listing pages on kiwidirectory.co.nz, a New Zealand business directory. No account or API key is needed. **Is this affiliated with kiwidirectory.co.nz?** No. This is an independent, third-party actor that reads publicly accessible pages. **Why do some businesses have no website, phone, or rating?** kiwidirectory.co.nz only shows the contact details and ratings a business itself provided or has received. Fields with no data are simply omitted from the record rather than shown as empty or null. **Can I search by both category and region at once?** Yes, in `search` mode — set both `category` and `region`. The actor crawls the category's pages and filters to the chosen region client-side (see Limitations). **Can I search all businesses without any category filter?** Yes — in `search` mode, set `category` to "All categories" and either provide a `keyword`, set a `region`, or leave both empty to page through every listing. **How accurate are the GPS coordinates?** `latitude`/`longitude` come directly from the business's own kiwidirectory.co.nz listing page. **Does this actor need a proxy or login?** No — kiwidirectory.co.nz's pages are served without any anti-bot challenge, so this actor runs entirely on Apify's free plan with no proxy and no credentials. A free Apify AUTO proxy fallback is wired in for resilience but is not required for normal operation. **Does this actor cover yellow.co.nz?** No — see "Data source and a note on Yellow.co.nz" above for why yellow.co.nz could not be scraped within this actor's zero-cost, no-login design, and why kiwidirectory.co.nz was used instead. # Actor input Schema ## `mode` (type: `string`): What to fetch: a general search (category and/or region and/or keyword), browse one category, browse one region, or fetch full business profiles from direct listing URLs. ## `category` (type: `string`): Business category to browse (mode=search or mode=byCategory). Leave as 'All categories' to not filter by category. ## `region` (type: `string`): New Zealand region to browse or filter by (mode=search or mode=byRegion). Leave as 'All regions' to not filter by region. ## `keyword` (type: `string`): Free-text keyword to search business names/descriptions for, e.g. 'plumber' or 'cafe' (mode=search, used only when 'Category' is 'All categories'). Matches kiwidirectory.co.nz's own search index. ## `businessUrls` (type: `array`): Direct kiwidirectory.co.nz listing URLs to fetch, e.g. https://kiwidirectory.co.nz/listings/some-business/. Use the 'sourceUrl' field from search results. ## `sortBy` (type: `string`): How to order results after fetching (mode=search, byCategory, byRegion). The site itself only returns its own listing order, so 'name' and 'region' are applied client-side across the fetched batch. ## `hasWebsiteOnly` (type: `boolean`): Only return businesses that have a website link on their listing. ## `hasPhoneOnly` (type: `boolean`): Only return businesses that have a phone number on their listing. ## `featuredOnly` (type: `boolean`): Only return businesses that kiwidirectory.co.nz marks with its own 'Featured' badge on the listing/browse pages (mode=search, byCategory, byRegion). ## `maxItems` (type: `integer`): Hard cap on the number of business records to return. ## Actor input object example ```json { "mode": "search", "category": "", "region": "", "keyword": "", "businessUrls": [], "sortBy": "relevance", "hasWebsiteOnly": false, "hasPhoneOnly": false, "featuredOnly": false, "maxItems": 20 } ``` # Actor output Schema ## `businesses` (type: `string`): Dataset containing all scraped kiwidirectory.co.nz business listings. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "search", "category": "", "region": "", "keyword": "", "businessUrls": [], "sortBy": "relevance", "hasWebsiteOnly": false, "hasPhoneOnly": false, "featuredOnly": false, "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/kiwi-directory-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "search", "category": "", "region": "", "keyword": "", "businessUrls": [], "sortBy": "relevance", "hasWebsiteOnly": False, "hasPhoneOnly": False, "featuredOnly": False, "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/kiwi-directory-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 '{ "mode": "search", "category": "", "region": "", "keyword": "", "businessUrls": [], "sortBy": "relevance", "hasWebsiteOnly": false, "hasPhoneOnly": false, "featuredOnly": false, "maxItems": 20 }' | apify call crawlerbros/kiwi-directory-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/kiwi-directory-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Kiwi Directory Scraper - New Zealand Business Directory", "description": "Scrape kiwidirectory.co.nz, a New Zealand business directory. Search by category and region, or fetch full business profiles by URL. Get names, addresses, phone numbers, categories, opening hours, websites, social links, images and geo-coordinates.", "version": "1.0", "x-build-id": "TcmYhjcmWpkdkYMth" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~kiwi-directory-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-kiwi-directory-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/crawlerbros~kiwi-directory-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-kiwi-directory-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/crawlerbros~kiwi-directory-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-kiwi-directory-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "byCategory", "byRegion", "byUrl" ], "type": "string", "description": "What to fetch: a general search (category and/or region and/or keyword), browse one category, browse one region, or fetch full business profiles from direct listing URLs.", "default": "search" }, "category": { "title": "Category", "enum": [ "", "automotive", "entertainment", "health", "home-garden", "marine", "miscellaneous", "professional", "real-estate", "travel-tourism" ], "type": "string", "description": "Business category to browse (mode=search or mode=byCategory). Leave as 'All categories' to not filter by category.", "default": "" }, "region": { "title": "Region", "enum": [ "", "auckland", "canterbury", "northland", "wellington", "waikato", "marlborough", "manawatu-whanganui" ], "type": "string", "description": "New Zealand region to browse or filter by (mode=search or mode=byRegion). Leave as 'All regions' to not filter by region.", "default": "" }, "keyword": { "title": "Keyword", "type": "string", "description": "Free-text keyword to search business names/descriptions for, e.g. 'plumber' or 'cafe' (mode=search, used only when 'Category' is 'All categories'). Matches kiwidirectory.co.nz's own search index.", "default": "" }, "businessUrls": { "title": "Business profile URLs (mode=byUrl)", "type": "array", "description": "Direct kiwidirectory.co.nz listing URLs to fetch, e.g. https://kiwidirectory.co.nz/listings/some-business/. Use the 'sourceUrl' field from search results.", "items": { "type": "object", "properties": { "url": { "title": "URL", "type": "string", "description": "kiwidirectory.co.nz listing URL." } } }, "default": [] }, "sortBy": { "title": "Sort order", "enum": [ "relevance", "name", "region" ], "type": "string", "description": "How to order results after fetching (mode=search, byCategory, byRegion). The site itself only returns its own listing order, so 'name' and 'region' are applied client-side across the fetched batch.", "default": "relevance" }, "hasWebsiteOnly": { "title": "Only businesses with a website", "type": "boolean", "description": "Only return businesses that have a website link on their listing.", "default": false }, "hasPhoneOnly": { "title": "Only businesses with a phone number", "type": "boolean", "description": "Only return businesses that have a phone number on their listing.", "default": false }, "featuredOnly": { "title": "Only featured listings", "type": "boolean", "description": "Only return businesses that kiwidirectory.co.nz marks with its own 'Featured' badge on the listing/browse pages (mode=search, byCategory, byRegion).", "default": false }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on the number of business records to return.", "default": 20 } } }, "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 } } } } } } } } } } ```