shop-app-research

Shop.app の調査

Shop.app — Shopify のストア横断型ショッピング／発見アプリ（個々の Shopify ストアフロントとは異なります） — で商品、バリエーション、ショップ、レビューを検索、閲覧、分析します。HTML スクレイピングは不要で、すべて Crawlora API から正規化された JSON として取得します。

このスキルを使う場面

• 「Shop.app で X を探して」／「Shop.app でランニングシューズを検索して」
• 「Shop.app での価格帯は？／X を販売しているショップはいくつ？」
• 「この Shop.app のショップを調べて」／「販売者の Shop.app カタログやコレクションを一覧表示して」
• 「この Shop.app の商品またはショップのレビューを取得して」
• 「この Shop.app 商品のバリエーション／オプション／在庫状況を取得して」
• Shop.app でのストア横断検索、市場概況の把握、販売者のデューデリジェンス調査

セットアップ（一度だけ）

• 無料の Crawlora API キー（毎月 2,000 クレジット、カード不要）を https://crawlora.net で取得します。
• ヘルパーを実行する前に、環境変数に CRAWLORA_API_KEY を設定します。
• ヘルパーは環境変数から CRAWLORA_API_KEY を読み取り、https://api.crawlora.net/api/v1 にリクエストを送信します。キーがない場合、または無効な場合は 401 が返されます。

仕組み

1. 検索／発見 — /shop-app/search（query、および deep_search、in_stock、on_sale、最大 50 件の limit）で、キーワードから候補商品を検索します。/shop-app/suggestions はオートコンプリート用のクエリ候補を返し、/shop-app/categories は検索の代わりに閲覧できる一般公開の商品カテゴリーを一覧表示します。
2. 市場概況 — /shop-app/analysis は同じ検索を実行しますが、生の検索結果ではなく、価格帯、通貨、セール件数、割引、上位ショップを集約した概況を返します。結果を自分でページ分割せずに「Shop.app での X の価格帯」を調べる場合に使用します。
3. 商品詳細 — /shop-app/products/{id} で正規化された商品詳細を取得します（特定のバリエーションを指定するには variant_id を追加します）。
4. バリエーション — selected_options に一致する正確なバリエーションは /shop-app/products/{id}/variant で、隣接するバリエーションは /shop-app/products/{id}/variants で取得し、オプションや価格を比較します。
5. 関連商品とレビュー — /shop-app/products/{id}/related と /shop-app/products/{id}/reviews を使用します。
6. ショップの特定 — /shop-app/products/{id}/shop で商品の販売者を特定します。/shop-app/shops/{handle} では販売者のプロフィールを直接取得でき、/shop-app/shops/{handle}/locations では実店舗の所在地を一覧表示できます。
7. ショップのカタログを閲覧 — /shop-app/shops/{handle}/products（sort_by で並べ替え可能）、または特定のコレクションについては /shop-app/shops/{handle}/collections/{collection_id}/products を使用します。/shop-app/shops/{handle}/typeahead は単一ショップ内を検索し、/shop-app/shops/{handle}/reviews は販売者のレビューを取得します。

すべてのエンドポイント、メソッド、パラメーターの一覧は reference/endpoints.md を参照してください。

API の呼び出し

# Search Shop.app (GET, key=value params):
scripts/crawlora.sh /shop-app/search query="running shoes" in_stock=true | jq '.'

# Product detail:
scripts/crawlora.sh /shop-app/products/12345 | jq '.data'

# Browse a shop's catalog, sorted low-to-high:
scripts/crawlora.sh /shop-app/shops/some-shop-handle/products sort_by=PRICE_LOW_TO_HIGH | jq '.'

すべてのリクエストには scripts/crawlora.sh を使用してください。API キーがコマンドライン引数に含まれないようにできます。

エンドポイントリファレンス

このスキルで使用する Shop.app の全エンドポイント（メソッド、パス、パラメーター、説明）については、reference/endpoints.md を参照してください。

使用例

• 購入前の市場概況の確認： /shop-app/analysis に query="wireless earbuds" と on_sale=true を指定し、現在の価格帯、割引、割引商品を販売する上位ショップを確認します。
• 販売者のデューデリジェンス： おすすめする前に、/shop-app/shops/{handle} と /shop-app/shops/{handle}/reviews を使って、Shop.app の販売者のプロフィールと最近のレビューをまとめます。
• コレクションの監査： /shop-app/shops/{handle}/products（limit でページ分割）、または特定の /shop-app/shops/{handle}/collections/{collection_id}/products を使って、販売者のカタログを価格付きで一覧表示し、基準値を上回る商品や下回る商品を特定します。

注意事項と制限

• クレジット／成功時課金： 2xx の場合にのみ課金されます。無料枠は月 2,000 クレジットです。 https://crawlora.net でキーを取得してください。
• 公開データのみ — 公開されている Shop.app の商品／ショップページを対象とします。Shop.app の利用規約を遵守してください。
• セキュリティ： キーは CRAWLORA_API_KEY のみに保存してください。ハードコード、クエリパラメーターでの指定、コミットはしないでください。
• 結果数には上限があり、オフセットによるページネーションには対応していません。search、analysis、related、reviews、shop/collection products、suggestions／typeahead はすべて limit によって上限に達します（各エンドポイントにそれぞれ最大値があり、バリアントによって 20 から 100 まで異なります）。
• selected_options はフラットな key=value ペアではなく、JSON オブジェクトです。 JSON 文字列として渡す（例：selected_options='{"Color":"Black"}'）か、option.Name=value／option[Name]=value のフィルターを繰り返し指定してください。
• ショップ／コレクションの商品一覧で sort_by に指定できるのは、MOST_SALES、PRICE_LOW_TO_HIGH、PRICE_HIGH_TO_LOW、RELEVANCE のみです。