scraperapi-python-sdk

ScraperAPI — Python SDK のベストプラクティス

要件： Python 3.7 以降、pip install scraperapi-sdk、環境変数 SCRAPERAPI_API_KEY。

セットアップ

import os
from scraperapi_sdk import ScraperAPIClient

client = ScraperAPIClient(os.environ["SCRAPERAPI_API_KEY"])

API キーをハードコードしないでください。毎回、環境変数から読み込んでください。

選択ガイド

コードを書く前に、適切な呼び出しパターンを選びます。

状況	パターン
単一の URL で、レスポンスがすぐに必要	client.get() — 同期
URL が 20 件以上、またはタイムアウトが頻発する単一 URL	非同期 Jobs API — async.scraperapi.com/jobs への requests.post()
対応プラットフォーム（Amazon、Google、Walmart、eBay、Redfin）	構造化データエンドポイント — api.scraperapi.com/structured/<vertical>
ページが JavaScript（React、Vue、Angular）でコンテンツを読み込む	render=True を指定した client.get()
サイトが標準プロキシをブロックする	premium=True を指定した client.get()

シンプルな単一 URL の処理には、同期 SDK を使用してください。複数 URL の処理には、非同期エンドポイントに対して生の requests を使用してください。SDK には非同期処理やバッチ処理の組み込みサポートがありません。

基本的な使い方

# Simple scrape — returns HTML as a string
html = client.get(url="https://example.com/")

# With parameters
html = client.get(
    url="https://example.com/",
    params={"render": True, "country_code": "us"}
)

パラメーターのリファレンス

レンダリング

# Render JavaScript before returning HTML
# Use when: page uses React/Vue/Angular, or initial scrape returns empty/partial content
# Cost: +10 credits (standard: 1 → rendered: 10)
html = client.get(url="https://spa-site.com/", params={"render": True})

# Wait for a specific element before capturing (requires render=True)
# Use when: content loads lazily and simple render still misses it
html = client.get(
    url="https://spa-site.com/",
    params={"render": True, "wait_for_selector": ".product-list"}
)

# Capture a screenshot (auto-enables rendering)
html = client.get(url="https://example.com/", params={"screenshot": True})

まずは render=True を指定せずに開始してください。期待するコンテンツがレスポンスに含まれない場合にのみ追加します。コストとレイテンシーが増加します。

プロキシとジオターゲティング

# Route through a specific country — no extra cost
html = client.get(url="https://example.com/", params={"country_code": "us"})

# Premium residential/mobile proxies — for sites that block datacenter IPs
# Cost: 10 credits per request (25 with render=True)
html = client.get(url="https://hard-site.com/", params={"premium": True})

# Ultra-premium — for the toughest anti-bot protections
# Cost: 30 credits per request (75 with render=True)
# Note: incompatible with custom headers (keep_headers is ignored)
html = client.get(url="https://hardest-site.com/", params={"ultra_premium": True})

premium と ultra_premium は相互排他的です。両方を設定しないでください。段階的に切り替えます： standard（1 cr）→ render（10 cr）→ premium（10 cr）→ premium+render（25 cr）→ ultra_premium（30 cr）。

セッション（スティッキープロキシ）

# Reuse the same proxy IP across multiple requests
# Use for: multi-page flows, pagination, login-state scraping
# Sessions expire 15 minutes after last use; any integer is a valid session ID
html1 = client.get("https://example.com/page1", params={"session_number": 42})
html2 = client.get("https://example.com/page2", params={"session_number": 42})

ヘッダーとデバイスタイプ

import requests

# Forward your own headers to the target site
# Note: keep_headers is incompatible with ultra_premium=True
html = client.get(
    url="https://example.com/",
    params={"keep_headers": True},
    headers={"Accept-Language": "en-US", "Referer": "https://google.com"}
)

# Emulate mobile or desktop user-agent
html = client.get(url="https://example.com/", params={"device_type": "mobile"})

レスポンス形式

# Default: raw HTML
html = client.get(url="https://example.com/")

# Structured JSON for supported sites (Amazon, Google, etc.)
# autoparse extracts fields like title, price, reviews automatically
data = client.get(url="https://amazon.com/dp/B09V3KXJPB", params={"autoparse": True})

# Markdown — useful for LLM pipelines
text = client.get(url="https://docs.example.com/", params={"output_format": "markdown"})

# Plain text
text = client.get(url="https://example.com/", params={"output_format": "text"})

# Binary content (PDFs, images)
content = client.get(url="https://example.com/report.pdf", params={"binary_target": True})

エスカレーション手順

必ず最も安価な方法から始めます。サイトが前の段階をブロックした場合にのみ、次の段階に進みます。

def scrape_with_escalation(url):
    for params in [
        {},                       # 1 credit
        {"render": True},         # 10 credits
        {"premium": True},        # 10 credits
        {"premium": True, "render": True},  # 25 credits
        {"ultra_premium": True},  # 30 credits
    ]:
        result = client.get(url=url, params=params)
        if result and "<html" in result.lower():
            return result
    return None

成功した段階を記録しておくと、同じドメインでは次回からその段階で開始できます。

非同期ジョブ（バッチ処理用）

同期 SDK は呼び出しごとに処理をブロックします（URL ごとに最大 70 秒）。URL が 20 件以上の場合は、非同期エンドポイントに対して requests を直接使用してください。バックグラウンドでジョブを送信でき、ポーリングまたは Webhook で結果を受け取れます。

import os, requests, time

API_KEY = os.environ["SCRAPERAPI_API_KEY"]

def submit_job(url, extra_params=None):
    payload = {"apiKey": API_KEY, "url": url, "apiParams": extra_params or {}}
    r = requests.post("https://async.scraperapi.com/jobs", json=payload, timeout=10)
    r.raise_for_status()
    return r.json()  # {"id": "...", "status": "running", "statusUrl": "..."}

def poll_job(job, max_wait=120, interval=5):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(job["statusUrl"], timeout=10)
        data = r.json()
        if data["status"] == "finished":
            return data["response"]["body"]
        if data["status"] == "failed":
            raise RuntimeError(f"Job failed: {job['id']}")
        time.sleep(interval)
    raise TimeoutError(f"Job {job['id']} did not finish in {max_wait}s")

# Batch pattern — submit all, then collect
urls = ["https://example.com/page1", "https://example.com/page2"]
jobs = [submit_job(u) for u in urls]
results = [poll_job(j) for j in jobs]

サーバーを管理している場合は、Webhook（"callback": {"type": "webhook", "url": "https://yourapp.com/cb"}）を使用してください。ポーリングが不要になります。非同期リクエストのドキュメントをご覧ください。

非常に大規模なバッチ（最大 50,000 URL）には、"urls": [...] 配列を指定して https://async.scraperapi.com/batchjobs を使用してください。

構造化データエンドポイント

対象プラットフォームが対応している場合は、生の HTML をスクレイピングする代わりにこれらを使用してください。クリーンな JSON が返され、render=True を指定した生のスクレイピングよりクレジットの消費が少なく、解析ロジックも不要です。

import os, requests

API_KEY = os.environ["SCRAPERAPI_API_KEY"]

def structured_get(vertical, params):
    """Call a structured data endpoint synchronously."""
    url = f"https://api.scraperapi.com/structured/{vertical}"
    r = requests.get(url, params={"api_key": API_KEY, **params}, timeout=70)
    r.raise_for_status()
    return r.json()

# Google SERP
results = structured_get("google/search", {"query": "best Python web scrapers"})

# Amazon product details
product = structured_get("amazon/product", {"asin": "B09V3KXJPB"})

# Walmart product search
items = structured_get("walmart/search", {"query": "standing desk", "tld": "com"})

対応する垂直分野：google/search、google/news、google/jobs、google/shopping、 google/maps、amazon/product、amazon/search、amazon/offers、 walmart/product、walmart/search、walmart/category、 ebay/product、ebay/search、redfin/listing、redfin/search。

各垂直分野で必要なパラメーターについては、構造化データのドキュメントをご覧ください。

エラー処理

import os, requests
from scraperapi_sdk import ScraperAPIClient

client = ScraperAPIClient(os.environ["SCRAPERAPI_API_KEY"])

def scrape(url, params=None):
    try:
        result = client.get(url=url, params=params or {})
        return result
    except requests.exceptions.HTTPError as e:
        status = e.response.status_code
        if status == 401:
            raise ValueError("Invalid API key — check SCRAPERAPI_API_KEY") from e
        if status == 403:
            # Blocked or credits exhausted — try escalating proxy tier
            raise RuntimeError("Blocked or out of credits") from e
        if status == 429:
            # Concurrent request limit — back off and retry
            raise RuntimeError("Rate limit — reduce concurrency or switch to async") from e
        if status in (500, 503):
            # Transient failure — retry with exponential backoff
            raise RuntimeError(f"Transient error {status} — retry") from e
        raise

ステータスコードのリファレンス：200 は成功、401 は不正なキー、403 はブロックまたはクレジット不足、404 は対象が見つからない、429 はレート制限、500/503 は一時的なエラー（安全に再試行可能）です。ScraperAPI は 500 レスポンスに対して課金しません。

クレジットコストのリファレンス

リクエストの種類	クレジット
Standard	1
render=True	10
premium=True	10
premium=True + render=True	25
ultra_premium=True	30
ultra_premium=True + render=True	75
構造化データ（大半の垂直分野）	1–5

任意のリクエストに "max_cost": N を追加すると、クレジットの消費を上限設定できます。リクエストが N クレジットを超える場合は 403 が返されます。

ドキュメント

• Python SDK のはじめ方
• リクエストパラメーター
• 構造化データのエンドポイント
• 非同期 API
• ダッシュボードとクレジット