costco-research

Costco のリサーチ

Costco の商品、カテゴリー、配送可否、近隣の倉庫、レビューを検索・比較します。すべて Crawlora API から取得した正規化済み JSON として扱い、HTML スクレイピングは行いません。

このスキルを使う場面

• 「Costco で X はいくらですか？」または「Costco でこの商品を探して。」
• 「この Costco の商品は在庫がありますか？／郵便番号 {postal_code} への配送はいつですか？」
• 「{keyword} に一致する Costco のカテゴリーはありますか？」／「Costco の {category} を見せて。」
• 「この Costco 商品のレビュー／評価を取得して。」
• 「{latitude}、{longitude} に最も近い Costco の倉庫を探して。」

セットアップ（初回のみ）

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

動作の仕組み

1. カテゴリーの閲覧 — /costco/categories は Costco のカテゴリーのスラッグと商品数を返します。検索語で絞り込むこともできます。各スラッグは /costco/search の category フィルターにそのまま使用できます。
2. 検索 — /costco/search は query および／または category スラッグで商品候補を検索し、各結果の商品名、ブランド、モデル、画像、評価を返します。
3. 詳細 — /costco/product/{id} は特定商品の商品名、説明、メーカー、画像、価格、在庫状況、評価を取得します。
4. 配送可否 — /costco/product/{id}/availability は、配送先の postal_code と state に応じた在庫状況と配送予定状況を返します。
5. レビュー — /costco/product/{id}/reviews は商品のレビューを 1 ページ分返します。内容はタイトル、本文、評価、投稿者、おすすめ度です。
6. 倉庫 — /costco/warehouses は latitude／longitude に基づき、近隣の Costco 倉庫を距離順に検索します。

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

API の呼び出し

# Browse categories matching a term:
scripts/crawlora.sh /costco/categories query="patio furniture" | jq '.'

# Search products by query and/or category slug:
scripts/crawlora.sh /costco/search query="robot vacuum" | jq '.'

# Product detail, then availability at a ZIP/state:
scripts/crawlora.sh /costco/product/1234567 | jq '.data'
scripts/crawlora.sh /costco/product/1234567/availability postal_code=98101 state=WA | jq '.'

すべてのリクエストには scripts/crawlora.sh を使用してください。API キーをコマンドライン引数に含めずに済みます。

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

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

使用例

• 倉庫の在庫確認： /costco/search で商品の id を見つけてから、買い物客の postal_code と state を指定して /costco/product/{id}/availability を呼び出し、商品をおすすめする前に配送可能であることを確認します。
• カテゴリー別の価格比較： /costco/categories でキーワードに対応するカテゴリーのスラッグを確認してから、その category を指定して /costco/search を呼び出し、一致する商品を一覧表示して価格と評価を比較します。
• 購入前の確認： /costco/product/{id} で価格と在庫状況を確認し、さらに /costco/product/{id}/reviews で最近の評価とおすすめ度を確認してから購入します。

注意事項と制限

• クレジット／成功時のみ課金： 2xx の場合にのみ課金されます。無料枠は月 2,000 クレジットです。キーの取得先：https://crawlora.net。
• 公開データのみ — Costco の公開ページを対象とします。Costco の利用規約を遵守してください。
• セキュリティ： キーは CRAWLORA_API_KEY のみに保存してください。ハードコード、クエリパラメーターへの指定、コミットは絶対にしないでください。
• 配送可否の確認は米国内のみ — /costco/product/{id}/availability には、米国の postal_code と 2 文字の state コードが必要です。米国外への配送確認には対応していません。
• /costco/warehouses には latitude／longitude の組み合わせが必要です。自由形式の住所や ZIP コードは指定できません。地名しかわからない場合は、事前にジオコーディングしてください。