scraperapi-crawler

ScraperAPI クローラー

クローラーは、シード URL から開始し、正規表現パターンに一致するリンクをたどって、リンク先のページを自動的に見つけてスクレイピングします。サイトの多数のページからデータを取得したいものの、あらかじめ URL がわからない場合に使用してください。

クローラーを使用しない場合

• 既知の URL リストがある場合 → 代わりに Async API を使用してください。料金が安く、予測しやすくなります。
• 単一のページが必要な場合 → Standard API（api.scraperapi.com）を使用してください。
• ログインが必要なコンテンツの場合 → クローラーがアクセスできるのは一般公開されているページのみです。
• 無料プランで深度 1 を超える必要がある場合 → 無料アカウントでは max_depth: 1 に制限されています。

エンドポイント

操作	メソッド	URL
クロールを開始	POST	https://crawler.scraperapi.com/job
ステータスを確認	GET	https://crawler.scraperapi.com/job/<jobId>
クロールをキャンセル	DELETE	https://crawler.scraperapi.com/job/<jobId>

認証：api_key を JSON 本文（POST）またはクエリパラメーター（GET/DELETE）に含めてください。

クロールの開始

import os, requests

API_KEY = os.environ["SCRAPERAPI_API_KEY"]

job = requests.post(
    "https://crawler.scraperapi.com/job",
    json={
        "api_key":            API_KEY,
        "start_url":          "https://example.com/blog/",
        "url_regexp_include": "(?<full_url>https?://example\\.com/blog/.*)",
        "url_regexp_exclude": ".*\\.(pdf|png|jpg|zip)",
        "max_depth":          3,
        "crawl_budget":       500,
        "api_params": {
            "country_code": "us",
            "render":       False,
        },
        "callback": {
            "type": "webhook",
            "url":  "https://yourapp.com/crawler-results"
        },
    }
).json()

job_id = job["jobId"]
print(f"Started: {job_id}")

必須パラメーター

パラメーター	説明
api_key	ScraperAPI キー（環境変数から読み込み、ハードコードしないでください）
start_url	シード URL — クロールの開始地点
url_regexp_include	クロール対象の URL を定義する正規表現（下記のパターンを参照）
max_depth または crawl_budget	少なくとも一方を指定する必要があります。両方を指定すると、先に到達した方の制限が適用されます

URL 正規表現パターン

url_regexp_include と url_regexp_exclude は標準的な正規表現です。Include パターンでは、名前付きキャプチャグループを必ず使用してください。絶対 URL には (?<full_url>...)、相対 URL には (?<relative_url>...) を使います。

# All pages on a domain
(?<full_url>https?://example\.com/.*)

# Only blog posts
(?<full_url>https?://example\.com/blog/.*)

# Only HTML pages — exclude files by requiring no extension
(?<full_url>https?://example\.com/[^.]*$)

# Relative paths (for sites that use relative links)
(?<relative_url>/products/.*)

除外パターン（url_regexp_exclude — 通常の正規表現で、キャプチャグループは不要です）：

# Skip binary files
.*\.(pdf|png|jpg|jpeg|gif|svg|zip|mp4)

# Skip auth and admin pages
.*(login|logout|signup|admin|auth).*

まず url_regexp_include を狭い範囲に設定し、対象を広げる前に小規模なテスト実行で検証してください。.* のようなパターンでは外部リンクもたどり、インターネット全体をクロールしてしまいます。

深度と予算の使い分け

max_depth を使う場合	crawl_budget を使う場合
サイト構造がわかっており、範囲が限定されている	サイトの規模が不明
特定のセクションが必要（例：ランディングページから 3 ホップ）	クレジット消費に上限を設けたい
小規模なサイト	リンク密度が予測できない大規模なサイト

安全に探索するには、両方を併用してください。max_depth: 3, crawl_budget: 500 の場合、どちらかの制限に先に達した時点で停止します。

深度 0 = 開始 URL のみ。深度 1 = 開始 URL と、そこからリンクされているすべてのページ。深度 2 = さらに 1 レベル下のページ、以降同様です。

ページごとのスクレイピングパラメーター（api_params）

検出した各ページの取得方法を制御します。ScraperAPI の標準パラメーターはすべてサポートされています。

{
  "render":       true,
  "premium":      false,
  "ultra_premium": false,
  "country_code": "us",
  "device_type":  "desktop",
  "output_format": "markdown"
}

サイトが JavaScript でコンテンツを読み込む場合に限り、render: true を追加してください。クロールするすべてのページのクレジットコストが倍増します。まずは指定せずにテストしてください。

ステータスの確認

import time, requests

def wait_for_crawl(job_id, api_key, poll_interval=10):
    url = f"https://crawler.scraperapi.com/job/{job_id}"
    while True:
        data = requests.get(url, params={"api_key": api_key}).json()
        status = data.get("status")
        print(f"Status: {status}")
        if status in ("completed", "failed", "cancelled", "delivered"):
            return data
        time.sleep(poll_interval)

ジョブの状態：delayed → running → completed / failed / cancelled → in delivery → delivered。

長時間のクロールでは、ポーリングの代わりに Webhook を使用してください。最終結果を得るためにポーリングする必要がなく、ページがスクレイピングされるたびに結果が送信されます。

Webhook

callback を設定すると、ScraperAPI は各ページのスクレイピング時に（完了時だけでなく）エンドポイントへ結果を POST します。各ペイロードには、クロールした URL、HTML／コンテンツ、そのリクエストのクレジットコスト、現在の深度が含まれます。

クロールが完了すると、成功／失敗したすべての URL と合計コストを記載した最終サマリーペイロードが送信されます。

{
  "callback": {
    "type": "webhook",
    "url": "https://yourapp.com/crawler-results"
  }
}

Webhook URL はパブリックにアクセス可能である必要があります。ScraperAPI は配信を最大 3 回再試行します。Webhook が失敗しても、クロール自体は停止しません。再取得が必要な場合に備え、結果は最大 30 日間保持されます。

スケジュール設定

1 回限りのクロールでは schedule を省略してください。定期的に実行する場合は追加します。

{
  "schedule": {
    "name": "weekly-blog-crawl",
    "interval": "daily"
  }
}

利用可能な間隔：once、hourly、daily、weekly、monthly。スケジュール設定には有料プランが必要です。無料アカウントでは、max_depth: 1 の 1 回限りのクロールのみ実行できます。

クレジットコスト

クローラーのクレジットコストは、クロール中のすべての個別ページリクエストの合計です。各ページのコストは、同じ api_params（render、premium など）を使用した Standard API の直接呼び出しと同じです。

crawl_budget を設定すると、クレジットの合計に上限を設定できます。上限に達するとクロールは正常に停止し、上限を超えることはありません。失敗したリクエストには課金されません。

各 webhook ペイロードの sa-credit-cost ヘッダーを確認すると、ページごとのコストがわかります。この値を使って、今後の実行に向けて crawl_budget を調整してください。

エラー処理

コード	意味	対処
200	ジョブが作成された、またはステータスが返された	続行します
400	リクエストの形式が正しくありません	必須フィールドと正規表現の構文を確認してください
401	API キーが無効です	SCRAPERAPI_API_KEY を確認してください
403	クレジットを使い切ったか、無料プランの深度制限に達しました	プランをアップグレードするか、max_depth／crawl_budget を減らしてください
429	同時実行中のジョブが多すぎます	待ってから再試行してください
500	一時的な障害です	バックオフを設定して再試行してください

ドキュメント

• クローラーの概要
• API リファレンス
• ダッシュボード