scraperapi-nodejs-sdk

ScraperAPI — Node.js SDK のベストプラクティス

必要条件： Node.js 14 以降、npm install scraperapi-sdk、SCRAPERAPI_API_KEY 環境変数。

セットアップ

// CommonJS
const scraperapiClient = require('scraperapi-sdk')(process.env.SCRAPERAPI_API_KEY);

// ES Modules / TypeScript
import ScraperAPIClient from 'scraperapi-sdk';
const scraperapiClient = new ScraperAPIClient(process.env.SCRAPERAPI_API_KEY);

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

選択ガイド

状況	パターン
URL が 1 件で、結果をすぐに取得したい	scraperapiClient.get(url)
URL が 20 件以上、またはバッチ処理	Async Jobs API — fetch/axios で async.scraperapi.com/jobs にアクセス
対応プラットフォーム（Amazon、Google、Walmart、eBay、Redfin）	構造化データエンドポイント — api.scraperapi.com/structured/<vertical>
ページが JavaScript でコンテンツを読み込む	.get(url, { render: true })
サイトがデータセンタープロキシをブロックする	.get(url, { premium: true })
対象にフォームまたは JSON ボディを POST する必要がある	.post(url, options)

基本的な使い方

// GET — returns HTML as a string (Promise-based)
const html = await scraperapiClient.get('https://example.com/');

// With parameters
const html = await scraperapiClient.get('https://example.com/', {
  render: true,
  country_code: 'us',
});

// Without async/await (Promise chain)
scraperapiClient.get('https://example.com/')
  .then(html => console.log(html))
  .catch(err => console.error(err));

POST および PUT リクエスト

// POST — forward a JSON body to the target site
const result = await scraperapiClient.post('https://example.com/api', {
  body: JSON.stringify({ query: 'example' }),
  headers: { 'Content-Type': 'application/json' },
});

// PUT — same signature, different HTTP method
const result = await scraperapiClient.put('https://example.com/resource', {
  body: JSON.stringify({ name: 'updated' }),
  headers: { 'Content-Type': 'application/json' },
});

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

レンダリング

// Render JavaScript before returning HTML
// Use when: page uses React/Vue/Angular, or initial scrape returns empty content
// Cost: +10 credits
const html = await scraperapiClient.get('https://spa-site.com/', { render: true });

// Wait for a specific element before capturing (requires render: true)
const html = await scraperapiClient.get('https://spa-site.com/', {
  render: true,
  wait_for_selector: '.product-list',
});

// Screenshot (auto-enables rendering)
const html = await scraperapiClient.get('https://example.com/', { screenshot: true });

まずは render: true を指定せずに開始してください。期待されるコンテンツがレスポンスに含まれていない場合にのみ追加してください。

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

// Route through a specific country — no extra credit cost
const html = await scraperapiClient.get('https://example.com/', { country_code: 'gb' });

// Premium residential/mobile proxies
// Cost: 10 credits (25 with render: true)
const html = await scraperapiClient.get('https://hard-site.com/', { premium: true });

// Ultra-premium — for the toughest anti-bot protections
// Cost: 30 credits (75 with render: true)
// Incompatible with custom headers — keep_headers is ignored when ultra_premium is set
const html = await scraperapiClient.get('https://hardest-site.com/', { ultra_premium: true });

premium と ultra_premium は相互排他的です。両方を設定しないでください。 段階的な引き上げ順序：standard（1 クレジット）→ render（10 クレジット）→ premium（10 クレジット）→ ultra_premium（30 クレジット）。

セッション（固定プロキシ）

// Reuse the same proxy IP across requests (same session_number = same IP)
// Sessions expire 15 minutes after last use
const page1 = await scraperapiClient.get('https://example.com/page1', { session_number: 42 });
const page2 = await scraperapiClient.get('https://example.com/page2', { session_number: 42 });

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

// Forward your own headers to the target site
// Note: keep_headers is ignored when ultra_premium: true
const html = await scraperapiClient.get('https://example.com/', {
  keep_headers: true,
  headers: { 'Accept-Language': 'en-US', 'Referer': 'https://google.com' },
});

// Emulate mobile or desktop browser
const html = await scraperapiClient.get('https://example.com/', { device_type: 'mobile' });

レスポンス形式と自動解析

// Structured JSON for supported sites (Amazon, Google, etc.)
const data = await scraperapiClient.get('https://amazon.com/dp/B09V3KXJPB', { autoparse: true });

// Markdown — useful for LLM pipelines or documentation tools
const md = await scraperapiClient.get('https://docs.example.com/', { output_format: 'markdown' });

// Plain text
const text = await scraperapiClient.get('https://example.com/', { output_format: 'text' });

アカウント情報

// Returns usage stats: concurrent request usage, total requests, account limits
const account = await scraperapiClient.account();
console.log(account);

これを使って、クレジット消費量と同時実行数の上限をプログラムから監視できます。

段階的な引き上げ

async function scrapeWithEscalation(url) {
  const tiers = [
    {},                                    // 1 credit
    { render: true },                      // 10 credits
    { premium: true },                     // 10 credits
    { premium: true, render: true },       // 25 credits
    { ultra_premium: true },               // 30 credits
  ];
  for (const params of tiers) {
    const html = await scraperapiClient.get(url, params);
    if (html && html.includes('<html')) return html;
  }
  return null;
}

Async Jobs（バッチ処理向け）

同期 SDK は各呼び出しの完了まで待機します。URL が 20 件以上の場合は、非同期エンドポイントを直接使ってジョブを並行して実行してください。

const API_KEY = process.env.SCRAPERAPI_API_KEY;

async function submitJob(url, apiParams = {}) {
  const res = await fetch('https://async.scraperapi.com/jobs', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ apiKey: API_KEY, url, apiParams }),
  });
  return res.json(); // { id, status, statusUrl }
}

async function pollJob(job, maxWaitMs = 120_000, intervalMs = 5_000) {
  const deadline = Date.now() + maxWaitMs;
  while (Date.now() < deadline) {
    const res = await fetch(job.statusUrl);
    const data = await res.json();
    if (data.status === 'finished') return data.response.body;
    if (data.status === 'failed') throw new Error(`Job ${job.id} failed`);
    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error(`Job ${job.id} timed out`);
}

// Batch — submit all, then collect
const urls = ['https://example.com/p1', 'https://example.com/p2'];
const jobs = await Promise.all(urls.map(submitJob));
const results = await Promise.all(jobs.map(pollJob));

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

対応プラットフォームでは、生の HTML ではなく構造化エンドポイントを使ってください。解析ロジックが不要な、クリーンな JSON が返されます。

async function structuredGet(vertical, params) {
  const query = new URLSearchParams({ api_key: API_KEY, ...params });
  const res = await fetch(`https://api.scraperapi.com/structured/${vertical}?${query}`);
  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
  return res.json();
}

// Google SERP
const serp = await structuredGet('google/search', { query: 'javascript scraping' });

// Amazon product
const product = await structuredGet('amazon/product', { asin: 'B09V3KXJPB' });

// Walmart search
const items = await structuredGet('walmart/search', { query: 'standing desk' });

すべての垂直分野と必須フィールドについては、構造化データのドキュメントを参照してください。

エラー処理

async function safeScrape(url, params = {}) {
  try {
    return await scraperapiClient.get(url, params);
  } catch (err) {
    const status = err?.response?.status ?? err?.status;
    if (status === 401) throw new Error('Invalid API key — check SCRAPERAPI_API_KEY');
    if (status === 403) throw new Error('Blocked or out of credits — try premium or ultra_premium');
    if (status === 429) throw new Error('Rate limit — reduce concurrency or switch to async');
    if (status === 500 || status === 503) throw new Error('Transient error — retry with backoff');
    throw err;
  }
}

ステータスコード：200 は成功、401 はキーが無効、403 はブロックまたはクレジット不足、404 は対象が見つからない、429 はレート制限、500/503 は一時的なエラー（課金されないため、安全に再試行できます）。

クレジット消費量の目安

リクエストタイプ	クレジット
Standard	1
render: true	10
premium: true	10
premium: true + render: true	25
ultra_premium: true	30
ultra_premium: true + render: true	75

ドキュメント

• Node.js SDK のスタートガイド
• SDK メソッドリファレンス
• API ステータスコード
• アカウント情報
• ダッシュボードとクレジット