NZ Active Lifestyle Retailer Discovery

What it does

NZ Active Lifestyle Retailer Discovery finds likely New Zealand active-lifestyle retailers from configured public sources, scores the evidence for each candidate, and extracts catalog intelligence where public catalog data is available.

This Actor discovers likely retailers from configured public sources and crawlable public pages. It does not guarantee complete coverage of the New Zealand retail market.

Use it to build a working discovery dataset for outdoor, camping, hiking, surf, sports, activewear, travel gear, footwear, hunting, fishing, pack, and apparel retailers. It can emit retailer rows, product rows, and a summary row in the default Apify dataset.

What it does not guarantee

This Actor does not guarantee that every New Zealand retailer is discovered, that every discovered candidate is definitely a retailer, or that every retailer has an extractable product catalog.

Public sources can be incomplete, stale, blocked, or unavailable. Some retailers block catalog endpoints, use unsupported commerce platforms, hide products behind JavaScript or bot protection, or expose only partial public pages. Those cases are still useful signals, so the Actor keeps retailer rows with catalogStatus and failureReason values instead of silently dropping them.

Firecrawl API key

Firecrawl is used for discovery crawling and generic product extraction from crawlable public pages. Provide firecrawlApiKey for discoverAndExtract and discoverOnly runs.

extractOnly can run without Firecrawl when you provide direct Shopify storefront URLs in storeUrls; in that case the Actor attempts public /products.json extraction only. If Firecrawl is configured for extractOnly, the Actor can also sample product-like data from non-Shopify public pages.

You control Firecrawl cost and limits. Use run mode, useDefaultDiscoverySources, discoverySources, queryThemes, maxRetailers, maxProductsPerGenericStore, and your Firecrawl account settings to cap the amount of crawling and extraction. The Actor does not bypass Firecrawl account limits.

Run modes

• discoverAndExtract: discovers retailer candidates, scores them, then attempts catalog extraction for candidates that meet the confidence threshold.
• discoverOnly: discovers and scores retailer candidates without product extraction.
• extractOnly: skips discovery and extracts from storeUrls; this is the lowest-cost mode for known Shopify storefronts.

Inputs

• mode: selects discovery, extraction, or both.
• firecrawlApiKey: Firecrawl key for discovery and generic extraction.
• useDefaultDiscoverySources: includes curated public New Zealand tourism and shopping source pages.
• discoverySources: additional public source URLs to crawl for retailer candidates.
• queryThemes: search phrases used during discovery.
• storeUrls: direct retailer URLs for extraction, especially in extractOnly.
• scopeKeywords: active-lifestyle terms used for evidence scoring.
• excludeDomains: domains to skip.
• maxRetailers: maximum scored retailers retained for extraction or output.
• maxProductsPerShopifyStore: cap for public Shopify /products.json rows per store.
• maxProductsPerGenericStore: cap for Firecrawl generic product extraction per store.
• minRetailerConfidence: minimum retailer confidence required before extraction.
• currency: currency label for prices, usually NZD.
• includeSummaries: emits a summary row when enabled.

Output rows

The default dataset can contain three row types:

• retailer: one row per discovered or supplied retailer, including retailerName, canonicalDomain, platform, catalogStatus, confidence scores, source evidence, and failure details when extraction is not available.
• product: one row per extracted product or variant, including title, classifiedCategory, price, compareAtPrice, isMarkdown, discountPct, extractionMethod, productConfidence, sourceUrl, and productUrl.
• summary: aggregate counts for discovered retailers, extracted retailers, catalog statuses, platforms, confidence tiers, and product categories.

You can download the default dataset from Apify in JSON, CSV, Excel, HTML, XML, or RSS formats.

Blocked and unsupported retailers remain visible as retailer rows. For example, a store can have catalogStatus values such as blocked, unsupported, failed, noProducts, notAttempted, extracted, or partial, with failureReason explaining the reason when known.

Confidence and evidence

retailerConfidence reflects evidence that the candidate is a New Zealand retailer. activeLifestyleConfidence reflects evidence that the candidate fits the active-lifestyle scope. confidenceTier summarizes the combined signal as high, medium, or low.

Product rows also include productConfidence. Shopify /products.json rows are higher confidence because they come from structured catalog data. Firecrawl product extraction rows are lower confidence because they are inferred from crawlable public page content.

Confidence scores are evidence scores, not guarantees. Review sourceUrls, evidence snippets, product URLs, and failure reasons before using the data for operational decisions.

Local run

Install dependencies and run from this actor directory:

npm install
npx --yes apify-cli run

For local input, create storage/key_value_stores/default/INPUT.json:

{
  "mode": "discoverAndExtract",
  "firecrawlApiKey": "fc_your_key",
  "useDefaultDiscoverySources": true,
  "discoverySources": ["https://example.co.nz/outdoor-retailers"],
  "storeUrls": ["https://www.bivouac.co.nz"],
  "maxRetailers": 25,
  "maxProductsPerShopifyStore": 250,
  "maxProductsPerGenericStore": 25,
  "includeSummaries": true
}

Local Apify storage is written under storage/ and is not uploaded to Apify Console.

Deploy

Deploy from this actor directory only:

npx --yes apify-cli validate-schema
npm test
npx --yes apify-cli push

Do not commit Firecrawl keys, Apify tokens, private storefront credentials, or scraped private data. Keep secrets in Apify Console or local environment variables.

Validation

Before publishing changes, run:

npx --yes apify-cli validate-schema
npm test
git diff --check

These checks validate the Apify input schema, run the Vitest suite, and catch whitespace errors in the git diff.