mcpField
S
scraperapi-scraper-builder

scraperapi-scraper-builder

github.com/scraperapi開発10106 回インストール12 週間前に更新
リポジトリ

scraperapi-scraper-builder について

ScraperAPIを使った実行可能なスクレイパーの構築を支援するワークフロー型スキルです。要件の確認、ページ調査、構成の選択を経てコードを生成します。

主な機能

  1. 01要件の確認
  2. 02サンプルページの調査
  3. 03根拠に基づく構成判断
  4. 04PythonとNode.jsのスクリプト生成
  5. 05クレジット予算と再試行の案内

活用シーン

  1. 01対象サイト向けスクレイパーの作成
  2. 02レンダリングとプロキシ設定の選択
  3. 03ページネーションや大量URLへの対応

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/scraperapi/scraperapi-skills --skill scraperapi-scraper-builder

インストール後、Claude Code で/scraperapi-scraper-builderを入力して読み込まれたか確認します。

同梱ファイルreferences/code-templates.md

詳細

ScraperAPI スクレイパービルダー

ScraperAPI を使用して、本番環境品質のスクレイパーを構築します。要件の収集、対象サイトの調査、アーキテクチャの決定、実行可能な完全なスクリプトの生成という4つのフェーズを順に進めます。

フェーズ 1 — 要件の収集

コードを書く前に、以下の情報を集めます。ユーザーのプロンプトから情報を取得し、不足している項目だけを質問してください。

情報指定がない場合のデフォルト
対象の URL またはウェブサイト必須 — 不明な場合は質問します
抽出するデータ項目曖昧な場合は質問します（「商品情報」→具体的にどの項目か？）
量推定します：単一 URL／ページネーションあり／URL の一括リスト
言語コンテキストから明確でない場合は質問します。Python が妥当なデフォルトです
出力形式stdout JSON
ジオターゲティングが必要か？サイトの種類から推定します。e コマースの価格情報では確認します

フェーズ 2 — サイトの事前調査

アーキテクチャを決定する前に、ScraperAPI を使って対象サイトからサンプルページを1〜2件取得し、実際の挙動を確認します。 これにより推測を避けられ、最大2クレジットで調査できます。

取得するページ

ページは最大2件取得します。

  1. 一覧またはカテゴリページ（主な対象） — 例：商品グリッド、検索結果、記事インデックス
  2. 詳細ページ（個々の項目からデータを取得する必要がある場合のみ） — 例：単一の商品、記事、プロフィール

必ず標準リクエスト（render なし、premium なし）から始めます。これが最も低コストの調査方法です。

GET https://api.scraperapi.com/?api_key=<SCRAPERAPI_API_KEY>&url=<target_url>
確認する内容

1. レスポンスステータス

ステータス意味
200コンテンツの分析に進みます
403 + 本文に "Just a moment"、cf-ray、または "Cloudflare" が含まれるCloudflare が検出されました
403 + 本文に "DataDome"、"PerimeterX"、または "Akamai" が含まれるボット管理システムが検出されました
403（一般的なもの）ボット対策が存在します。プレミアムプロキシが必要になる可能性があります
429レート制限されています。アーキテクチャのフェーズで留意してください

2. コンテンツの完全性（ステータスが200の場合）

render=true が必要になる兆候：

  • 空の SPA コンテナー：子要素のない <div id="root"></div>、<div id="app"></div>、<div id="__next"></div>
  • <script> タグ内のフレームワークのマーカー：_next、__nuxt__、react、vue、angular
  • レスポンスの大半が <script> タグと <div> タグで、目に見えるテキストがほとんどない
  • フェーズ 1 で指定した対象データ項目が HTML に存在しない

対象データが生の HTML に目視できる形で含まれている場合は、標準レンダリングで十分です。render を有効にしないでください。

3. ページネーションの構造

<a> の href とリンクタグから、サイトのページネーション方式を確認します。

  • <a rel="next"> または <link rel="next"> → 次のリンクをたどる方式
  • href に ?page=N、?p=N、/page/N/ が含まれる → ページ番号によるページネーション
  • ?start=N または ?offset=N → オフセット方式のページネーション
  • ページネーションリンクがなく、data-infinite-scroll または "Load more" ボタンがある → JS 駆動の無限スクロール（render=true が必要）

正確な URL パターンを記録してください。これはフェーズ 4 のページネーションループで直接使用します。

4. データ構造（対象の項目が確認できる場合）

  • 繰り返し要素のコンテナーを特定します（例：<li class="product-item">、<div class="listing-card">）
  • フェーズ 1 で指定した各データ項目の CSS セレクターを記録します
  • 埋め込みの構造化データを確認します：<script type="application/ld+json">（JSON-LD）または data-* 属性。これらは多くの場合、生の HTML を解析するよりも簡潔に処理できます

5. 内部 API エンドポイント（補足）

インラインの <script> ブロックを調べ、内部パス（例：/api/products、/_next/data/）を参照する fetch( または axios.get( の呼び出しを探します。見つかった場合は、HTML を解析するよりも、その JSON エンドポイントをスクレイピングするほうが通常は簡単で安定します。

サイトプロファイル — このフェーズの出力

次に進む前に、調査結果を表にまとめます。各行はフェーズ 3 の特定の判断に対応します。

| Signal                  | Observed                              |
|-------------------------|---------------------------------------|
| HTTP status (standard)  | 200 / 403 / ...                       |
| Anti-bot protection     | None / Cloudflare / DataDome / ...    |
| JS rendering needed     | Yes / No / Uncertain                  |
| Pagination pattern      | ?page=N / rel=next / load-more / ...  |
| Target data visible     | Yes / No (skeleton HTML)              |
| Data container selector | e.g. div.product-card                 |
| Structured data (LD+J)  | Present / Not found                   |
| Internal API detected   | Yes (<path>) / No                     |

フェーズ 3 — アーキテクチャの決定

フェーズ 2 のサイトプロファイルを、各判断の主な根拠として使用します。プロファイルから具体的な観察結果を挙げながら、6つの判断をすべて順に進めます。コードを書く前に、判断をすべて表にまとめます（このセクションの末尾を参照）。

Decision 1 — 構造化データエンドポイントはありますか？

対象サイトがサポート対象の業種に該当するか確認します。該当する場合は、そのエンドポイントを使用してください。構造化データエンドポイントは HTML を解析せずにクリーンな JSON を返し、レンダリングとボット対策も自動で処理します。Decision 2 と 3 はスキップしてください。

サポート対象の業種（ドキュメントで確認してください）：

  • Amazon：product、search、offers、reviews
  • Google：search、news、jobs、shopping、maps
  • Walmart：product、search、category
  • eBay：product、search
  • Redfin：listing、search
  • Indeed：jobs、job
  • LinkedIn：profile、jobs（利用可能かどうかは異なる場合があります）

エンドポイントの形式：GET https://api.scraperapi.com/structured/<site>/<type>?api_key=...&<required_param>=...

Decision 2 — ページで JavaScript のレンダリングが必要ですか？

Site Profile で、標準レスポンスに対象データが含まれていないことが確認された場合に限り、render=true を有効にしてください。コスト：約10クレジット／リクエスト。

  • Site Profile に「Target data visible: No」または「JS rendering needed: Yes」とある → render=true を有効にする
  • Site Profile に「Target data visible: Yes」とある → render=true を有効にしない
  • Site Profile に「Uncertain」とある → render=true を指定してサンプルをもう1件取得し、比較する

推測で render=true を有効にしないでください。Phase 2 のプローブ結果が判断材料になります。

Decision 3 — サイトにボット対策がありますか？

最初の判断には、Site Profile の「Anti-bot protection」の行を使用してください。段階的に強化し、最初から最高のティアを使用しないでください。

  • Site Profile に「None」とある → 標準設定で開始する
  • Site Profile に「Cloudflare」または何らかのボット管理サービスとある → premium=true（約10クレジット）で開始する
  • premium=true を指定しても 403 が返る → ultra_premium=true（約30クレジット）に引き上げる

ultra_premium=true と premium=true は同時に使用できません。両方を設定しないでください。

Decision 4 — リクエスト数はどのくらいですか？
リクエスト数方法
1～10 URL特別な処理なしで同期ループ
10～100 URL1リクエスト／秒のレート制限を設けて同期処理
>100 URL非同期 Jobs API（POST https://async.scraperapi.com/batchjobs）

非同期バッチでは、スクリプトがすべての URL を送信し、すべてのジョブが完了するまでポーリングします。非同期処理のパターンについては、references/code-templates.md を参照してください。

Decision 5 — セッション状態が必要ですか？

次の場合は session_number=<int> を追加します。

  • スクレイパーでログインフローをたどる必要がある
  • 複数ステップのチェックアウト、または認証が必要なページを扱う
  • リクエスト間でページネーションの状態を維持する必要がある

セッション ID には任意の整数を指定します。同じ session_number を指定したリクエストは、同じプロキシ IP 経由でルーティングされます。

Decision 6 — 地域ターゲティングが必要ですか？

次の場合は country_code（ISO-3166。例：us、gb、de）を追加します。

  • 地域によって異なる価格をスクレイピングする
  • 対象サイトが地域に応じてリダイレクトまたはブロックする
  • SERP の検索結果を地域に合わせる必要がある
アーキテクチャの概要表

コードを生成する前に、この表を出力します。

| Parameter      | Value      | Reason                            |
|----------------|------------|-----------------------------------|
| url            | ...        | target                            |
| render         | true/false | (why)                             |
| premium        | true/false | (why)                             |
| ultra_premium  | true/false | (why)                             |
| country_code   | us / –     | (why)                             |
| session_number | N / –      | (why)                             |
| volume mode    | sync/async | (why)                             |

Phase 4 — コードを生成する

使用する言語がまだわからない場合は確認してください（デフォルト：Python）。疑似コードやスニペットではなく、完全に実行可能なスクリプトを生成します。ベースとなるテンプレートとその応用方法については、references/code-templates.md を参照してください。

Phase 2 の Site Profile を使って解析ロジックを事前に設定します。データコンテナのセレクター（例：div.product-card）が特定されている場合は、TODO のままにせず、extract() 関数に直接記述してください。JSON-LD が見つかった場合は、HTML ツリーをたどるのではなく、<script type="application/ld+json"> を解析してください。内部 API のパスが見つかった場合は、ページ HTML ではなく、そのエンドポイントを対象にしてください。

Python スクリプトの構成
  1. --url、--pages、--output、--max-credits と、Phase 3 で決定したすべての ScraperAPI パラメーター用フラグを備えた argparse CLI
  2. os.environ["SCRAPERAPI_API_KEY"] から API キーを取得します。ハードコードはしません
  3. 指数バックオフによる再試行（5 回）を行う scrape() 関数
  4. 以下のエラーテーブルに従ったステータスコードの処理
  5. リクエストを送信する前に、クレジットの見積もりを stderr に出力します
  6. Site Profile で特定したパターンを使ったページネーションループ。同期モードでは 1 秒あたり 1 リクエストのレート制限を設けます
  7. Site Profile のセレクターをあらかじめ設定した extract() 関数（特定されていない場合は TODO）
  8. JSON を stdout または --output ファイルに出力します
Node.js スクリプトの構成

上記と同じフラグと動作を使用します。node-fetch@2 と commander を使用してください。既存のモジュール形式（ESM または CommonJS）がわかっている場合はそれに合わせ、わからない場合は CommonJS を既定で使用します。

生成するスクリプトの先頭に必ず含める
# Requirements: pip install requests  (Python)
# Requirements: npm install node-fetch@2 commander  (Node.js)
# Usage: SCRAPERAPI_API_KEY=your_key python scraper.py --url "https://example.com" --pages 5

クレジットコストの参考情報

設定リクエストあたりのクレジット
標準1
render=true約 10
premium=true約 10
ultra_premium=true約 30
構造化エンドポイント1～10（分野によって異なります）

実行前にコストの見積もりを出力します：# Estimated: 50 pages × 10 credits = ~500 credits

生成するスクリプトには、見積もりが予算を超えた場合に処理を中断する --max-credits フラグを含める必要があります。

エラー処理

ステータスアクション
200解析して返します
401中断します — API キーが無効です。再試行しません
403premium=true を指定して再試行します。それでもブロックされる場合は ultra_premium=true を試します
404この URL をスキップします — ページが存在しません
429指数バックオフで再試行します。大規模なバッチでは非同期に切り替えます
500/503指数バックオフで最大 5 回試行します

検証チェックリスト

スクリプトを提示する前に、以下を確認してください。

  • Phase 2 で Site Profile が作成されており、各アーキテクチャ上の判断で Site Profile が根拠として示されている
  • API キーは $SCRAPERAPI_API_KEY 環境変数から読み込まれており、ハードコードされていない
  • 再試行ロジックで 429、500、503 を指数バックオフにより処理している
  • --max-credits による制限があり、最初のリクエストを送信する前に適用される
  • リクエストを送信する前に、クレジットの見積もりが stderr に出力される
  • 構造化エンドポイントを使用する場合、分野名が cheatsheet と完全に一致している
  • 非同期の場合、ジョブの送信だけでなく、ポーリングループまたは Webhook 処理がスクリプトに含まれている
  • ultra_premium と premium が同時に設定されていない
  • セットアップ手順のコメントがスクリプトの先頭にある
  • ユーザーが解析ロジックを追加する場所に TODO コメントがある

参考資料

コメント

Markdown 対応