apify-ecommerce

# E-Commerce Cluster Answer natural language e-commerce questions by routing to the right Apify Actor and delivering a synthesized answer via the `apify` CLI. **CLI rules:** Always pass `--user-agent apify-awesome-skills/apify-ecommerce`, `--json` (or the relevant `--format` flag on `datasets get-items`), and `2>/dev/null`. The `--user-agent` flag is critical for telemetry — never omit it. ## Prerequisites (No need to check it upfront) - Apify CLI v1.5.0+ (`npm install -g apify-cli`) - `jq` (recommended for quick extraction and filtering; `brew install jq` on macOS, `apt install jq` on Linux) - Authentication via one of: - `apify login` (OAuth, opens browser) - `APIFY_TOKEN` env variable (e.g. `export APIFY_TOKEN=...` or `.env` file) - Token from [Apify Console → Settings → Integrations](https://console.apify.com/settings/integrations) Verify auth: `apify info --user-agent apify-awesome-skills/apify-ecommerce` — should show username and userId. ## Workflow Copy this checklist and track progress: ``` Task Progress: - [ ] Step 1: Detect intent and select Actor - [ ] Step 2: Fetch Actor schema - [ ] Step 3: Ask user preferences (format, result count) - [ ] Step 4: Run the Actor and fetch results - [ ] Step 5: Analyze results and deliver synthesized answer ``` ### Step 1: Detect Intent and Select Actor Classify the user's message into an intent, then pick the right Actor. **Intent signals:** | Signals in user message | Intent | |------------------------|--------| | price, cost, cheapest, compare prices, pricing | `pricing` | | review, rating, sentiment, stars, feedback | `reviews` | | bestseller, top selling, most popular, trending | `bestsellers` | | seller, vendor, reseller, who sells | `sellers` | | all products from, scrape store, full catalog | `store-scrape` | | what platform, built on, tech stack, Shopify or WooCommerce | `tech-stack` | | SEO, listing quality, product page audit | `seo-audit` | | competitor funnel, competitor pricing, conversion elements | `competitor` | | search intent, keyword intent, SERP intent | `search-intent` | | match products, same product on different platforms | `product-matching` | | restaurant, food delivery, DoorDash, UberEats, TheFork | `food-delivery` | | enrich store, store metadata, store list | `store-enrichment` | | event, concert, ticket, Eventbrite | `events` | | property, real estate, house listing, Realtor | `real-estate` | | Facebook ads, Meta ads, ad library, competitor ads | `ads-intelligence` | | classified, Craigslist, used item for sale | `classifieds` | | car, used car, vehicle, automotive, Webmotors | `automotive` | | pins, inspiration, Pinterest boards, visual search, Pinterest trends | `content-discovery` | | TikTok Shop, TikTok store, TikTok creator | `tiktok-shop` | | website for sale, domain for sale, Flippa | `website-marketplace` | If multiple intents are detected, ask: *"Do you want [intent A] or [intent B]?"* **Actor routing table — always try Primary first, switch to Fallback only if it fails or returns 0 results.** The Primary actor (`apify/e-commerce-scraping-tool`) handles most intents once you feed the right input mode: - **Have target URLs** (a listing, profile, or category page) → `detailsUrls` / `listingUrls`. - **Have a keyword/marketplace** → `keyword` + `marketplaces` (product-details mode). - **Broad discovery (competitor, search-intent, classifieds, automotive, real-estate, website-marketplace, events)** → use `searchEngineKeyword` (search-engine mode) or `keyword`/`detailsUrls` depending on whether you have a query or URLs. **Exception — skip the Primary and go straight to the Fallback** for intents the Primary genuinely can't do (different data source or specialized analysis): `tech-stack`, `seo-audit`, `store-enrichment`, `product-matching`, `ads-intelligence`, `content-discovery` (Pinterest), and `tiktok-shop`. Routing these to the Primary wastes a run and credits. | Intent | Platform | Primary Actor | Fallback Actor | |--------|----------|---------------|----------------| | `pricing` | Amazon / Walmart / generic | `apify/e-commerce-scraping-tool` | — | | `pricing` | eBay | `apify/e-commerce-scraping-tool` | `ivanvs/ebay-scraper-pay-per-result` | | `pricing` | Etsy | `apify/e-commerce-scraping-tool` | `epctex/etsy-scraper` | | `pricing` | Google Shopping | `apify/e-commerce-scraping-tool` | `epctex/google-shopping-scraper` | | `pricing` | Facebook Marketplace | `apify/e-commerce-scraping-tool` | `apify/facebook-marketplace-scraper` | | `pricing` | SHEIN | `apify/e-commerce-scraping-tool` | `seamless_coffer/shein-product-scraper` | | `pricing` | Lazada | `apify/e-commerce-scraping-tool` | `fatihtahta/lazada-scraper` | | `pricing` | Canadian Tire | `apify/e-commerce-scraping-tool` | `azzouzana/canadiantire-ca-scraper` | | `pricing` | Tesco | `apify/e-commerce-scraping-tool` | `radeance/tesco-scraper` | | `pricing` | Shopify | `apify/e-commerce-scraping-tool` | `trovevault/shopify-products-scraper` | | `pricing` | WooCommerce | `apify/e-commerce-scraping-tool` | `trovevault/woocommerce-products-scraper` | | `reviews` | Amazon / Walmart / generic | `apify/e-commerce-scraping-tool` | `junglee/amazon-reviews-scraper` | | `reviews` | Trustpilot | `apify/e-commerce-scraping-tool` | `casper11515/trustpilot-reviews-scraper` | | `reviews` | TheFork | `apify/e-commerce-scraping-tool` | `jdtpnjtp/thefork-restaurant-scraper-advanced` | | `bestsellers` | Amazon | `apify/e-commerce-scraping-tool` | `junglee/amazon-bestsellers` | | `sellers` | Amazon | `apify/e-commerce-scraping-tool` | `junglee/amazon-seller-scraper` | | `sellers` | eBay | `apify/e-commerce-scraping-tool` | `ivanvs/ebay-scraper-pay-per-result` | | `store-scrape` | Shopify | `apify/e-commerce-scraping-tool` | `trovevault/shopify-products-scraper` | | `store-scrape` | WooCommerce | `apify/e-commerce-scraping-tool` | `trovevault/woocommerce-products-scraper` | | `store-scrape` | Amazon | `apify/e-commerce-scraping-tool` | `junglee/Amazon-crawler` | | `store-scrape` | Flippa | `apify/e-commerce-scraping-tool` | `scraped/flippa-scraper` | | `tech-stack` | any | `apify/e-commerce-scraping-tool` | `trovevault/e-commerce-tech-stack-detector` | | `seo-audit` | any | `apify/e-commerce-scraping-tool` | `trovevault/product-listing-seo-auditor` | | `competitor` | any | `apify/e-commerce-scraping-tool` | `trovevault/competitor-intelligence-scraper---funnel-pricing-conversion` | | `search-intent` | any | `apify/e-commerce-scraping-tool` | `trovevault/ai-serp-intent-extractor---search-intent-classifier` | | `product-matching` | any | `apify/e-commerce-scraping-tool` | — | | `store-enrichment` | any | `apify/e-commerce-scraping-tool` | `trovevault/e-commerce-store-data-enricher` | | `food-delivery` | DoorDash | `apify/e-commerce-scraping-tool` | `tri_angle/doordash-store-details-scraper` | | `food-delivery` | UberEats | `apify/e-commerce-scraping-tool` | `e-commerce/ubereats-reviews-scraper` | | `food-delivery` | TheFork | `apify/e-commerce-scraping-tool` | `jdtpnjtp/thefork-restaurant-scraper-advanced` | | `ads-intelligence` | Facebook / Meta | `apify/e-commerce-scraping-tool` | `apify/facebook-ads-scraper` | | `classifieds` | Craigslist | `apify/e-commerce-scraping-tool` | `ivanvs/craigslist-scraper-pay-per-result` | | `automotive` | Webmotors | `apify/e-commerce-scraping-tool` | `stealth_mode/webmotors-auto-search-scraper` | | `events` | Eventbrite | `apify/e-commerce-scraping-tool` | `aitorsm/eventbrite` | | `real-estate` | Realtor.com | `apify/e-commerce-scraping-tool` | `powerai/realtor-properties-search-scraper` | | `content-discovery` | Pinterest | `apify/e-commerce-scraping-tool` | `fatihtahta/pinterest-scraper-search` | | `tiktok-shop` | TikTok Shop | `apify/e-commerce-scraping-tool` | `lemur/tiktok-shop-creators` | | `website-marketplace` | Flippa | `apify/e-commerce-scraping-tool` | `scraped/flippa-scraper` | **Escalation — if both Primary and Fallback fail or return 0 results**, discover a current alternative live instead of guessing an ID: ```bash # Find relevant, well-rated, pay-per-event Actors for the platform/intent. # Keep the default relevance sort — `--sort-by popularity` surfaces generic # big-name scrapers over the platform you actually asked for. apify actors search "PLATFORM or INTENT keywords" \ --pricing-model PAY_PER_EVENT --limit 10 --json \ --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null \ | jq '[.items[] | select(.stats.totalUsers > 100 and .actorReviewRating > 4.5) | {id: (.username + "/" + .name), users: .stats.totalUsers, rating: (.actorReviewRating | (. * 100 | round / 100)), pricing: .currentPricingInfo.pricingModel}]' ``` Pick the top match. Before running it, confirm it requests only **limited permissions** (check the Actor's Store page / README — prefer Actors that don't require full account access). If the `PAY_PER_EVENT` filter returns nothing, drop the `--pricing-model` flag and re-run, keeping the ≥100-users and ≥4.5-rating bar. ### Step 2: Fetch Actor Schema Fetch the Actor summary, input schema, and README: ```bash # Summary (title, description, pricing, stats) apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ecommerce --json 2>/dev/null # Input schema — use --input WITHOUT --json to get the clean schema directly. # (Adding --json returns the full ~250 KB actor object instead, with the schema # buried as an escaped string under .taggedBuilds.latest.build.inputSchema.) apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ecommerce --input 2>/dev/null # README (capabilities, examples, gotchas) apify actors info "ACTOR_ID" --user-agent apify-awesome-skills/apify-ecommerce --readme 2>/dev/null ``` Replace `ACTOR_ID` with the selected Actor (e.g., `apify/e-commerce-scraping-tool`). **Primary actor input cheat-sheet.** `apify/e-commerce-scraping-tool` is mode-driven — pick fields by intent (always set the matching `max…Results` cap): | Intent | Minimal input | |--------|---------------| | `pricing` (keyword) | `{"keyword": "wireless earbuds", "marketplaces": ["www.amazon.com"], "maxProductResults": 50}` | | `pricing` (specific URLs) | `{"detailsUrls": [{"url": "https://…"}], "maxProductResults": 50}` | | `store-scrape` (category) | `{"listingUrls": [{"url": "https://…/category"}], "maxProductResults": 500}` | | `reviews` | `{"keywordReviews": "echo dot", "marketplacesReviews": ["www.amazon.com"], "sortReview": "Most recent", "maxReviewResults": 200}` | | `sellers` | `{"sellerUrls": [{"url": "https://…"}], "maxSellerResults": 50}` | | `pricing` (Google Shopping) | `{"searchEngineKeyword": "ps5", "countryCode": "us", "maxSearchEngineResults": 50}` | | `food-delivery` | `{"keywordDelivery": "pizza", "marketplacesDelivery": ["www.doordash.com"], "addressDelivery": "New York, NY", "maxDeliveryResults": 50}` | For any other actor (or fields not listed), fetch the schema with the `--input` command above. ### Step 3: Ask User Preferences Before running, ask: 1. **Output format**: - **Quick answer** (default) — synthesized answer in chat, no file saved - **CSV** — full export saved to disk - **JSON** — full export saved to disk 2. **Result count** — suggest defaults by intent: | Intent | Default |