zalando-research

Zalando の調査

Zalando の商品、カテゴリー、検索結果を調べて比較します — すべて Crawlora API から正規化された JSON として取得し、HTML スクレイピングは行いません。

このスキルを使う場面

• 「Zalando で X はいくらですか？」または「ドイツのストアで X を探して。」
• 「Zalando で X を検索して」／「Zalando のランニングシューズカテゴリーには何がありますか？」
• 「SKU でこの Zalando の商品を調べて。」
• 「この Zalando の検索クエリをオートコンプリートして。」
• 「利用できる Zalando の国別ストアフロントはどれですか？」
• Zalando に絞った競合価格やカタログの調査。

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

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

仕組み

1. マーケットを解決する — ほかのすべての Zalando エンドポイントでは、デフォルト値のない market（de、fr、com などの国別ストアフロントコード）が必須です。使用するコードがわからない場合は、/zalando/markets で一覧を取得します。
2. 検索する — /zalando/search（q+market）でキーワードから商品候補を検索します。価格、ブランド、画像を含む正規化済みの商品カードと total_count が返されます。利用できるのは最初のページのみです。
3. オートコンプリート — /zalando/suggest（q+market）で、検索前に入力途中の検索語（例：「running sho」→「running shoes」）を補完します。
4. 商品詳細 — /zalando/product（sku+market）で、ブランド、説明、画像、およびサイズごとの価格／在庫状況／GTIN を取得します。検索結果またはカテゴリー結果から取得した sku を使用します。
5. カテゴリーを閲覧する — /zalando/category（category+market）で、市場固有の URL スラッグを使ってカテゴリーまたはブランドの一覧を閲覧します。検索と同じ商品カードに加えて total_count が返されます。

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

API の呼び出し

# Resolve storefronts, then search a market (GET, key=value params):
scripts/crawlora.sh /zalando/markets | jq '.'
scripts/crawlora.sh /zalando/search q="running shoes" market=de | jq '.'

# Product detail (sku from a search/category result, same market):
scripts/crawlora.sh /zalando/product sku=AD116A0FL-Q11 market=de | jq '.data'

# Browse a category, and autocomplete a partial query:
scripts/crawlora.sh /zalando/category category=shoes market=de | jq '.'
scripts/crawlora.sh /zalando/suggest q="running sho" market=de | jq '.'

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

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

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

使用例

• ストアフロントを考慮した価格確認： /zalando/markets で適切なコードを確認し、そのマーケットで /zalando/search を使ってキーワードの現在価格を取得します。
• カテゴリーの調査： マーケット固有のスラッグ（例：de／gb では shoes、fr では chaussures）を指定して /zalando/category を使い、カテゴリーのカタログを一覧表示して、価格しきい値を上回る商品や下回る商品を確認します。
• 検索から詳細情報へ： /zalando/search で SKU の候補を見つけ、最適な商品について /zalando/product を使い、価格、サイズ、在庫状況の詳細を取得します。

注意事項と制限

• クレジット／成功時のみ課金： 2xx の場合にのみ課金されます。無料枠は月 2,000 クレジットです。 キーは https://crawlora.net で取得できます。
• 公開データのみ — 公開されている商品ページと一覧ページを対象とします。Zalando の利用規約を遵守してください。
• セキュリティ： キーは CRAWLORA_API_KEY にのみ保存してください。ハードコード、クエリパラメーターへの追加、コミットは絶対に行わないでください。
• Zalando では常に market が必要です（デフォルトのストアフロントはありません）。有効なコードがわからない場合は、/zalando/markets で確認してください。sku の商品は、通常、見つかったマーケットでのみ販売されているため、検索／カテゴリーと商品詳細の呼び出しでは同じ market を指定してください。
• カテゴリーのスラッグはマーケットごとに異なります（各ストアフロントで現地語のスラッグが使われます）。別のマーケットのものではなく、そのマーケットのサイトナビゲーションまたは商品の url フィールドから取得してください。
• /zalando/search と /zalando/category が返すのは検索結果の最初のページのみです。次ページ以降の取得にはまだ対応していません。