apify-ecommerce

Eコマースクラスター

自然言語によるEコマースの質問に対し、適切なApify Actorへルーティングし、apify CLIを使って回答をまとめて提供します。

CLI のルール： 常に --user-agent apify-awesome-skills/apify-ecommerce、--json（または datasets get-items で該当する --format フラグ）、および 2>/dev/null を指定してください。--user-agent フラグはテレメトリーに不可欠です。省略しないでください。

前提条件

（事前に確認する必要はありません）

• Apify CLI v1.5.0+（npm install -g apify-cli）
• jq（すばやい抽出やフィルタリングに推奨。macOS では brew install jq、Linux では apt install jq）
• 次のいずれかによる認証：
  • apify login（OAuth。ブラウザーが開きます）
  • APIFY_TOKEN 環境変数（例：export APIFY_TOKEN=... または .env ファイル）
  • Apify Console → Settings → Integrations のトークン

認証の確認：apify info --user-agent apify-awesome-skills/apify-ecommerce を実行すると、ユーザー名とuserIdが表示されます。

ワークフロー

このチェックリストをコピーして、進捗を管理します。

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

ステップ1：意図を検出してActorを選択する

ユーザーのメッセージを意図に分類し、適切なActorを選択します。

意図を示すシグナル：

ユーザーメッセージ内のシグナル	意図
価格、費用、最安値、価格比較、価格設定	pricing
レビュー、評価、センチメント、星、フィードバック	reviews
ベストセラー、売れ筋、人気商品、トレンド	bestsellers
販売者、ベンダー、再販業者、販売元	sellers
すべての商品、ストアをスクレイピング、全商品カタログ	store-scrape
どのプラットフォームか、何を基盤としているか、技術スタック、ShopifyかWooCommerceか	tech-stack
SEO、出品品質、商品ページの監査	seo-audit
競合のファネル、競合の価格設定、コンバージョン要素	competitor
検索意図、キーワードの意図、SERPの意図	search-intent
商品の照合、異なるプラットフォーム上の同一商品	product-matching
レストラン、フードデリバリー、DoorDash、UberEats、TheFork	food-delivery
ストアの情報拡充、ストアのメタデータ、ストア一覧	store-enrichment
イベント、コンサート、チケット、Eventbrite	events
物件、不動産、住宅の掲載情報、Realtor	real-estate
Facebook広告、Meta広告、広告ライブラリ、競合の広告	ads-intelligence
クラシファイド、Craigslist、中古品の販売	classifieds
車、中古車、車両、自動車、Webmotors	automotive
ピン、インスピレーション、Pinterestボード、ビジュアル検索、Pinterestのトレンド	content-discovery
TikTok Shop、TikTokストア、TikTokクリエイター	tiktok-shop
販売中のウェブサイト、販売中のドメイン、Flippa	website-marketplace

複数の意図が検出された場合は、" [intent A] と [intent B] のどちらを希望しますか？" と尋ねます。

Actorルーティング表 — まず必ずPrimaryを試し、失敗するか結果が0件の場合のみFallbackに切り替えます。 Primary actor（apify/e-commerce-scraping-tool）は、適切な入力モードを指定すれば、ほとんどの意図に対応します。

• 対象URLがある場合（掲載ページ、プロフィール、カテゴリーページ）→ detailsUrls / listingUrls。
• キーワードやマーケットプレイスがある場合 → keyword + marketplaces（商品詳細モード）。
• 幅広い情報の発見（競合、検索意図、クラシファイド、自動車、不動産、販売中のウェブサイト、イベント） → クエリがあるかURLがあるかに応じて、searchEngineKeyword（検索エンジンモード）または keyword / detailsUrls を使用します。

例外 — Primaryでは対応できない意図は、PrimaryをスキップしてFallbackを直接使用してください（データソースが異なる、または専門的な分析が必要な場合）：tech-stack、seo-audit、store-enrichment、product-matching、ads-intelligence、content-discovery（Pinterest）、および tiktok-shop。これらをPrimaryにルーティングすると、実行とクレジットが無駄になります。

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

エスカレーション — Primary と Fallback の両方が失敗するか、結果が 0 件の場合、ID を推測せず、実行時に最新の代替手段を探します：

# 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}]'

最上位の候補を選びます。実行する前に、要求される権限が限定的であることを確認してください（Actor の Store ページまたは README を確認し、アカウントへの完全なアクセスを必要としない Actor を優先してください）。PAY_PER_EVENT フィルターで何も見つからない場合は、--pricing-model フラグを外して再実行し、ユーザー数 100 以上、評価 4.5 以上の基準は維持してください。

ステップ 2：Actor スキーマを取得する

Actor の概要、入力スキーマ、README を取得します：

# 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

ACTOR_ID を選択した Actor に置き換えます（例：apify/e-commerce-scraping-tool）。

Primary actor の入力チートシート。 apify/e-commerce-scraping-tool はモード駆動型です。目的に応じてフィールドを選択してください（一致する max…Results 上限は必ず設定します）。

目的	最小限の入力
pricing（キーワード）	{"keyword": "wireless earbuds", "marketplaces": ["www.amazon.com"], "maxProductResults": 50}
pricing（特定の URL）	{"detailsUrls": [{"url": "https://…"}], "maxProductResults": 50}
store-scrape（カテゴリ）	{"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}

その他の Actor（または一覧にないフィールド）については、上記の --input コマンドでスキーマを取得してください。

ステップ 3：ユーザーの希望を確認する

実行前に、次の項目を確認します：

1. 出力形式：
   • 簡易回答（デフォルト） — チャット内で回答をまとめ、ファイルは保存しません
   • CSV — 完全なエクスポートをディスクに保存します
   • JSON — 完全なエクスポートをディスクに保存します
2. 結果件数 — 目的に応じたデフォルトを提案します：

目的	デフォルト
pricing	商品 50 件
reviews	レビュー 200 件
bestsellers	商品 100 件
sellers	セラー 50 件
store-scrape	すべて（無制限）
food-delivery	レストラン 50 件
その他すべて	20～50 件

コストへの配慮：Actor の入力には、常に妥当な結果件数の上限を設定します。Primary actor の上限フィールドはモード固有です。maxProductResults、maxReviewResults、maxSellerResults、maxSearchEngineResults、または maxDeliveryResults を使用します（共通の maxResults はありません）。Fallback actors では、スキーマで公開されているフィールド（maxResults、resultsLimit、maxItems、maxCrawledPages など）を使用します。ユーザーが明示的に件数の増加を求めない限り、上記の目的別デフォルトを使用してください。結果が 1000 件以上になる大規模なスクレイピングは Apify クレジットを多く消費するため、実行前にユーザーへ警告してください。

ステップ 4：Actor を実行して結果を取得する

2 つのステップで行います。Actor を実行し（完了するまで待機）、その後、指定された形式でデータセットの項目を取得します。

Actor を実行する — 実行メタデータを JSON として返します。次のステップで使う defaultDatasetId を抽出します。

apify actors call "ACTOR_ID" -i 'JSON_INPUT' \
  --user-agent apify-awesome-skills/apify-ecommerce --json 2>/dev/null

出力から .id（実行 ID）、.status（SUCCEEDED である必要があります）、.defaultDatasetId を使用します。

結果を取得する — ユーザーの希望に応じて形式を選びます。

# Quick answer: total count + fields + top 5 in chat (no file)
apify datasets info DATASET_ID --json \
  --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null \
  | jq '{itemCount, fields, consoleUrl}'
apify datasets get-items DATASET_ID --limit 5 \
  --user-agent apify-awesome-skills/apify-ecommerce --format json 2>/dev/null

# CSV file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ecommerce --format csv 2>/dev/null > YYYY-MM-DD_OUTPUT_FILE.csv

# JSON file
apify datasets get-items DATASET_ID \
  --user-agent apify-awesome-skills/apify-ecommerce --format json 2>/dev/null > YYYY-MM-DD_OUTPUT_FILE.json

その他の --format オプション：jsonl、xlsx、xml、rss、html。大規模なデータセットをページ分割するには、--offset N を使用します。

ヒント： ざっと確認するだけでない場合は、まずデータセットをローカルファイルに保存し（> file.json／> file.csv）、その後ディスク上のデータを使って分析してください。apify datasets get-items は常にネットワーク経由でストリーミングするため、直接 jq にパイプすると、実行のたびにデータ全体を再ダウンロードすることになります。

jq と組み合わせて手早く抽出する：

jq は apify datasets get-items の代わりではなく、補完として使用します。サーバー側の --limit／--offset／--format を使えば、コストと帯域幅を抑えられます。jq はサンプル項目、またはすでに保存したファイルに対して使用してください。

# Discover real field names from one sample item (Actor outputs vary —
# use this before composing further jq queries)
apify datasets get-items DATASET_ID --limit 1 --format json \
  --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null \
  | jq '.[0]'

# Quick aggregation from a JSON file you already saved with the commands above
jq '[.[] | select(.rating != null and .rating >= 4.5)] | length' YYYY-MM-DD_OUTPUT_FILE.json

ステップ 5：結果を分析して回答を提示する

実行が完了したら、データをそのまま羅列するのではなく、要点をまとめた明確な回答を提示します。

• 価格： 価格帯、平均価格、最安値上位 5 件と URL
• レビュー： 平均評価、肯定的・否定的な主な傾向を各上位 3 件、最近の抜粋
• ベストセラー： ランク順の上位 10 件と商品名、価格、評価、URL
• 販売者： 販売者の合計数、販売者ごとの価格帯、無許可販売者のフラグ
• ストアのスクレイピング： 商品の合計数、カテゴリ別内訳、価格帯、在庫の概要
• 技術スタック： 検出されたプラットフォーム、信頼度、注目すべきプラグイン
• フードデリバリー： レストラン数、平均評価、価格帯別の内訳
• 広告インテリジェンス： 広告の合計数、アクティブ／非アクティブの内訳、上位のクリエイティブ形式

エラー処理

• 認証エラー → apify login を実行するか、APIFY_TOKEN 環境変数を設定します
• Actor not found → ルーティングテーブルの Actor ID のスペルを確認します
• 実行ステータスが FAILED → 実行メタデータのコンソール URL（.consoleUrl）を開いてログを確認します
• タイムアウト／実行時間が非常に長い → apify actors call に --timeout <seconds> を渡します
• No results → キーワードの範囲を広げ、フォールバック Actor に切り替えます。それでも失敗する場合は、エスカレーションの探索コマンド（ステップ 1）を使用します
• proxy is required → Actor の入力に "proxy": {"useApifyProxy": true} を追加します
• Platform not detected → generic インテントで apify/e-commerce-scraping-tool をデフォルトとして使用します

注意点

• --input --json は罠です。 スキーマではなく、完全な約 250 KB の actor オブジェクトが返されます。クリーンなスキーマを取得するには apify actors info ID --input --user-agent apify-awesome-skills/apify-ecommerce 2>/dev/null（--json なし）を使用してください。JSON 形式で必要な場合に限り、.taggedBuilds.latest.build.inputSchema を確認してください。
• Primary actor には maxResults フィールドがありません。 上限はモードごとに異なり（maxProductResults、maxReviewResults、maxSellerResults、maxSearchEngineResults、maxDeliveryResults）、maxResults を設定しても何も起こらず、実行時には上限なしでスクレイピングされます。
• Primary は適切な入力モードを使えば、ほとんどのインテントに対応します（URL → detailsUrls／listingUrls、クエリ → keyword または searchEngineKeyword）。競合、検索インテント、クラシファイド、自動車、不動産、ウェブサイトマーケットプレイス、イベントも含まれます。一方、tech-stack、seo-audit、store-enrichment、product-matching、ads-intelligence、content-discovery（Pinterest）、tiktok-shop には対応できません。これらは直接 Fallback に振り分けてください。
• apify actors call -i には、1 行の有効な JSON が必要です。 URL 配列や引用符を含む入力の場合は、インラインで渡すのではなく、ファイルに書き込んで -i @input.json を渡してください。シェルのクォート処理によって複雑な入力が気付かないうちに壊れることがあります。
• datasets get-items は常にネットワーク経由でストリーミングします。 いったんファイルに保存し（> file.json）、そのファイルに対して jq を実行してください。コマンドの出力を繰り返し jq にパイプすると、そのたびに再ダウンロードされます。
• apify actors search --sort-by popularity は関連性を無視します。 クエリに関係なく、最も有名なスクレイパーが返されます（「etsy」で検索しても Instagram／Google Maps Actors が表示されます）。エスカレーション先を探す場合は、デフォルトの関連性順を維持し、stats.totalUsers／actorReviewRating で絞り込んでください。
• marketplaces の値には、完全なドメインスラッグが必要です（例：["www.amazon.com", "www.ebay.com"]）。"amazon" や表示名ではありません。Delivery モードではさらに限定され、marketplacesDelivery が受け付けるのは ["www.doordash.com", "www.instacart.com"] のみです（UberEats は含まれません。UberEats の場合は e-commerce/ubereats-reviews-scraper のフォールバックを使用してください）。値を推測する前に、必ず --input スキーマの enum で受け付けられる値を確認してください。