brightdata-sdk-js

Bright Data JavaScript SDK

統一された Node.js/TypeScript SDK（@brightdata/sdk）を通じてウェブデータにアクセスできます。1 つのクライアントで複数のサービスを利用できます。ウェブのブロック解除（scrapeUrl）、プラットフォームのスクレイピング（scrape.<platform>）、SERP 検索（search.google/bing/yandex）、AI ディスカバリー（discover）、データセット、ブラウザーの自動化、Scraper Studio に対応しています。

Node.js ≥ 20 が必要です。 ESM + CommonJS と、完全な TypeScript 型定義を同梱しています。クライアントは bdclient（小文字です。誤植ではありません）としてエクスポートされます。

セットアップの必須手順（最初に実行してください）

npm install @brightdata/sdk     # or: pnpm add / yarn add

クライアントは BRIGHTDATA_API_TOKEN 環境変数を読み取ります。または、{ apiKey } を渡してください。トークンは https://brightdata.com/cp/setting/users から取得できます。

// ESM (package.json "type": "module", or .mjs)
import { bdclient } from '@brightdata/sdk';

// CommonJS (.cjs / "type": "commonjs")
const { bdclient } = require('@brightdata/sdk');

const client = new bdclient();             // reads BRIGHTDATA_API_TOKEN
// const client = new bdclient({ apiKey: '...' });
try {
  const html = await client.scrapeUrl('https://example.com');
} finally {
  await client.close();                    // always close (or `await using`)
}

await using client = new bdclient()（TS 5.2+ / Node ≥20）を使うと、スコープの終了時に自動でクローズされます。

サービスの選択（最初に決めてからメソッドを調べてください）

特定のメソッドを選ぶ前に、まずサービスを選択してください。ルーティングの間違いの多くは、この手順を省略してキーワードだけで判断することが原因です。

Have a URL?
  ├── On a supported platform (Amazon, LinkedIn, Facebook, Instagram, YouTube,
  │   TikTok, Reddit, Pinterest, ChatGPT, Perplexity, DigiKey)?
  │     → Platform scraping: client.scrape.<platform>.<method>(urls, opts?)
  │
  ├── Generic page (no dedicated platform scraper)?
  │     → Web unlocker: client.scrapeUrl(url, { dataFormat: 'markdown' })
  │
  └── Need login / JS / click-scroll-fill / CAPTCHA / multi-step nav?
        → Browser API: client.browser.getConnectUrl() (connect via Playwright)

No URL?
  ├── Want entities matching natural-language criteria
  │   ("find AI startups in Berlin", "competitors of Acme")?
  │     → Discover: client.discover(query, { intent })
  │
  ├── Want web pages / search-result links ("search Google for X")?
  │     → SERP: client.search.google(query) [or .bing / .yandex]
  │
  ├── Want to search WITHIN a platform ("Amazon products by keyword",
  │   "LinkedIn jobs", "Instagram reels by profile")?
  │     → Platform discovery: client.scrape.<platform>.discover*(filters)
  │       or amazon.productSearch(...)  (NOTE: client.search is SERP-only here)
  │
  └── Want bulk/historical data at scale?
        → Datasets: client.datasets.<name>.query(filter) → .download(snapshotId)

例外ケース：

• 対応プラットフォームの URL でも、ユーザーがログイン／クリック／スクロール／JS に言及している場合 → Browser API（操作の必要性がプラットフォームより優先されます）。
• 対応プラットフォームのスクレイピングで 403／ブロックが返された場合 → client.scrapeUrl()（ウェブのブロック解除）に切り替えます。
• URL とともに「X は誰かを探す／調査する」（「acme.com の競合他社」など）場合 → Discover を使います。URL はコンテキストであり、スクレイピング対象ではありません。

⚠️ Python SDK との主な違い

Python SDK（brightdata-sdk）を知っていても、JS のインターフェースは異なります。名前をそのまま移植しないでください。

概念	Python	JavaScript
クライアント	SyncBrightDataClient / BrightDataClient	bdclient（1 つのみ、すべて非同期）
ウェブのブロック解除	client.scrape_url(url=...)	client.scrapeUrl(url, opts)
プラットフォーム検索	client.search.amazon.products(...)	なし — scrape.amazon.productSearch / discover* を使用
client.search	SERP およびプラットフォーム検索	SERP のみ（google/bing/yandex）
バッチ	*_trigger メソッド + job.wait()	1 回の呼び出しに string[] を渡すか、*Trigger + job.wait() を使用
命名規則	snake_case	camelCase
データセット	client.datasets.amazon_products	client.datasets.amazonProducts

メソッド名：使用前に確認してください

プラットフォームのメソッドが存在する／しないと述べる前に、references/scrapers.md を参照してください。各プラットフォームで確認済みのメソッドがすべて記載されています。SDK には TypeScript 型定義が同梱されているため、型付きプロジェクトではコンパイラー／エディターを使ってメソッドの存在を確認することもできます。

各プラットフォームでは、最大 3 種類のメソッドスタイルを利用できます（references/scrapers.md を参照）。

• collect<Thing>(input, opts?) — 行を直接返します（object[]）。
• <thing>(input, opts?) — オーケストレーションを実行します（トリガー → ポーリング → ダウンロード）。{ data, status, rowCount } を返します。デフォルトではこれを使用してください。
• discover<Thing>By<X>(filters, opts?) — 直接 URL ではなく、キーワード／カテゴリ／URL フィルターで項目を検索します。

幻覚が起きやすい例（これらは書かないでください。references/scrapers.md で確認してください）。

誤り	正しい例
client.search.amazon.products(...)	client.scrape.amazon.productSearch(...)（JS にプラットフォーム検索ルーターはありません）
client.scrape.linkedin.people(...)	client.scrape.linkedin.profiles(urls)
client.scrape.chatgpt...	client.scrape.chatGPT...（G+T は camelCase）
client.datasets.amazon_products	client.datasets.amazonProducts
BrightDataClient / new BdClient()	bdclient（すべて小文字）

便利な単独メソッド

メソッド	機能
client.scrapeUrl(url | url[], opts?)	Web アンロッカーです。あらゆる URL から HTML／Markdown／JSON／スクリーンショットを取得します。並列で一括処理するには、配列を渡します。
client.search.google(q | q[], opts?)	SERP の結果を取得します（.bing、.yandex も利用できます）。配列を渡すと一括処理されます。
client.discover(query, { intent })	AI によるランキング付きのエンティティ／ページ検出です。
client.discoverTrigger(query, opts?)	ブロッキングせずに検出を実行し、.wait()／.fetch() を備えた Job を返します。
client.datasets.list()	実行時に利用可能なすべてのデータセットを一覧表示します。
client.scraperStudio.run(collectorId, { input })	カスタム Scraper Studio コレクターを実行します。
client.browser.getConnectUrl({ country })	Playwright／Puppeteer／Selenium 用の CDP WebSocket URL です。
client.listZones()	アクティブな Bright Data ゾーンを一覧表示します。
client.saveResults(data, { filename, format })	結果をファイルに書き込みます。
client.close()	HTTP 接続を閉じます。処理が終わったら必ず呼び出してください。

注意点

• 必ず await client.close() を呼び出してください（または await using を使用してください）。クライアントはキープアライブトランスポートを保持するため、解放しないとプロセスが終了しなくなります。
• client.search は SERP 専用です（google／bing／yandex）。プラットフォーム内を検索するには、そのプラットフォームの discover*／productSearch スクレイパーメソッドを使用してください。client.search.amazon はありません。
• chatGPT は client.scrape 上ではキャメルケースです。.chatgpt ではなく、client.scrape.chatGPT.search(...) を使用してください。
• 一括処理ではループせず、配列を渡してください。 scrapeUrl([...urls]) と search.google([...queries]) は内部で並列実行されます。大量の入力を扱うプラットフォームスクレイパーでは、配列を使ったオーケストレーションメソッド、または *Trigger と job.wait() のパターンを推奨します（references/advanced.md を参照）。単一項目の呼び出しを Promise.all で囲んでブロッキング呼び出しを実行すると、レートリミッターと競合します。
• オーケストレーションメソッドは数分間ブロッキングします。 products／profiles などはジョブを開始し、準備が整うまでポーリングします（多くの場合、2～10 分）。pollTimeout を極端に小さく設定しないでください。{ pollInterval, pollTimeout } で調整できます。デフォルト値は適切に調整されています。
• データセットは過去のデータ／一括処理用であり、リアルタイムデータではありません。 最新のデータが必要な場合は、プラットフォームスクレイパーまたは scrapeUrl を使用してください。query() は snapshotId を返し、download() はスナップショットの準備が整うまでブロッキングします。
• 403 の場合は Web アンロッカーにフォールバックします。 プラットフォームスクレイパーがブロックされた場合は、client.scrapeUrl() 経由で URL を再試行してください。
• 独自の再試行ループを追加しないでください。 トランスポートはバックオフ付きでネットワークエラー／タイムアウトエラーをすでに再試行するため、二重に再試行するとクレジットが無駄になります。代わりに、コンストラクターで timeout／rateLimit を調整してください。
• コストの目安（安い順）： データセット → SERP → プラットフォームスクレイパー → Web アンロッカー → Discover → Scraper Studio → Browser API。要件を満たす最も安価なサービスを優先してください。

エラー処理

すべてのエラーは BRDError を継承します。分岐処理には、必要なクラスをインポートしてください。

import { bdclient, ValidationError, AuthenticationError, BRDError } from '@brightdata/sdk';

try {
  const data = await client.scrape.amazon.products(['https://www.amazon.com/dp/B0D77BX8Y4']);
} catch (err) {
  if (err instanceof AuthenticationError) { /* bad/expired token */ }
  else if (err instanceof ValidationError) { /* bad input */ }
  else if (err instanceof BRDError) { /* any SDK error */ }
  else throw err;
}

クラス：BRDError（基底クラス）、ValidationError、AuthenticationError、ZoneError、 NetworkError、NetworkTimeoutError、TimeoutError、APIError、 DataNotReadyError、FSError。

例

一般的なページを Markdown としてスクレイピングする

const md = await client.scrapeUrl('https://example.com/article', { dataFormat: 'markdown' });

Amazon の商品を取得する（デフォルトのオーケストレーション方式）

const res = await client.scrape.amazon.products(['https://www.amazon.com/dp/B0D77BX8Y4']);
console.log(res.status, res.rowCount, res.data);

SERP の一括処理

const results = await client.search.google(['best running shoes', 'best trail shoes'], { country: 'us' });

エンティティを検索する（Discover）

const startups = await client.discover('AI startups in Berlin', {
  intent: 'early-stage machine-learning companies',
  numResults: 10,
});

データセットを使った一括／過去データの取得

const ds = client.datasets;
const snapshotId = await ds.instagramProfiles.query({ url: 'https://www.instagram.com/natgeo/' }, { records_limit: 50 });
// download() blocks until the snapshot is ready
const rows = await ds.instagramProfiles.download(snapshotId);

トラブルシューティング

• AuthenticationError／401 — トークンがないか、無効です。BRIGHTDATA_API_TOKEN または apiKey オプションを確認してください。
• 403／ブロックされた — サイトがスクレイパーをブロックしました。client.scrapeUrl()（Web アンロッカー）経由で URL を再試行してください。
• タイムアウト — timeout（コンストラクターで指定、1000～300000 ms）またはオーケストレーションの pollTimeout を増やしてください。小さくしないでください。
• 「Dataset not found」 — client.datasets.list() を呼び出してください。データセット名はキャメルケースです（amazonProducts、linkedinProfiles）。
• 処理終了後もプロセスが終了しない — await client.close() を呼び忘れています。
• サンドボックスでの SSL／プロキシエラー — ゾーン／SSL オプションについては references/advanced.md を参照してください。
• レート制限エラー — コンストラクターで { rateLimit, ratePeriod } を設定するか、Promise.all の代わりに配列／トリガーパターンで一括処理してください。

リファレンスを読み込むタイミング

• references/scrapers.md — ユーザーが Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、Pinterest、ChatGPT、Perplexity、DigiKey を指定した場合に参照します。プラットフォームごとの検証済みメソッド一覧（collect / orchestrated / discover）と、scrapeUrl のウェブアンロッカーオプションが記載されています。
• references/search.md — SERP エンジン（search.google/bing/yandex）と Discover API（discover / discoverTrigger）について、すべてのオプションを記載しています。
• references/datasets-overview.md — データセット名、query → getStatus → download のライフサイクル、フィルターについて記載しています。
• references/advanced.md — コンストラクターのオプションと環境変数、バッチ／トリガーのオーケストレーション、Browser API（Playwright/Puppeteer）、Scraper Studio、エラークラス、ゾーン／SSLについて記載しています。