brightdata-sdk

Bright Data SDK

統一された Python SDK を通じてウェブデータにアクセスできます。1 つのクライアントで、プラットフォームのスクレイピング、プラットフォーム検索、ウェブ検索（SERP）、AI を活用したディスカバリー、データセット、ウェブアンロッキング、ブラウザー自動化、スクレイパースタジオの 8 つのサービスカテゴリを利用できます。

クライアントは常にコンテキストマネージャーとして使用してください。同期環境（スクリプト、ノートブック、Claude Code）では SyncBrightDataClient を使用します。非同期環境では BrightDataClient を使用します。どちらも同じメソッド名を使い、同期クライアントは呼び出しを自動的にラップします。注：現在、同期クライアントが対応するプラットフォームは限られています。詳細は references/scrapers.md の同期互換性に関する注記を参照してください。未対応のプラットフォームまたはデータセット API には、非同期クライアント（BrightDataClient）を使用してください。

サービスの選択（最初に判断し、次に特定のメソッドを確認します）

特定のメソッドを探す前に、この判断ツリーを使って適切なサービスを選んでください。この手順を省略し、ユーザーのキーワードだけでパターンマッチングすることが、ルーティングの失敗の主な原因です。

Have a URL?
  ├── On a supported platform (Amazon, LinkedIn, Facebook, Instagram, YouTube,
  │   TikTok, Reddit, ChatGPT, Perplexity, Pinterest, DigiKey)?
  │     → Platform scraping: client.scrape.<platform>.<method>(url=...)
  │
  ├── Generic page (not on any supported platform)?
  │     → Web unlocker: client.scrape_url(url=...)
  │
  └── Need login / JavaScript / click-scroll-fill / CAPTCHA / multi-step navigation?
        → Browser API: client.browser.get_connect_url() (then connect with Playwright)

No URL?
  ├── Want entities matching natural-language criteria
  │   ("find AI startups in Berlin", "competitors of Acme Corp", "people who worked at X")?
  │     → Discover: client.discover(query=..., intent=...)
  │
  ├── Want web pages / articles / search-result links
  │   ("search Google for X", "find pages about Y")?
  │     → SERP: client.search.google(query=...) [or .bing / .yandex]
  │
  ├── Want to search WITHIN a specific platform
  │   ("find products on Amazon", "TikTok videos by hashtag", "Pinterest pins about recipes")?
  │     → Platform search: client.search.<platform>.<method>(...)
  │
  └── Want bulk historical data at scale
      ("all LinkedIn companies in tech", "historical Amazon prices", "every Zillow listing in Texas")?
        → Datasets: client.datasets.<name>(filter=...) (then .download(snapshot_id))

例外的なケース：

• 対応プラットフォームの URL でも、ユーザーがログイン／クリック／スクロール／JS を明示的に指定している場合 → Browser API（操作の指定がプラットフォームより優先されます）。
• 対応プラットフォームの URL でも、スクレイパーが 403／ブロックを返す場合 → client.scrape_url()（ウェブアンロッカー）にフォールバックします。
• URL とともに「X を探す／調査する／X は誰か」と依頼された場合（例：「acme.com の競合相手を探して」）→ Discover のままです。URL は文脈であり、スクレイピング対象ではありません。

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

プラットフォームのメソッドが存在するかどうかを主張したり、プラットフォームが対応していないと主張したりする前に、必ず references/scrapers.md を確認してください。過去の評価では、モデルがメソッド名を捏造したり（例：client.scrape.linkedin.people は存在しません。.profiles を使用します）、プラットフォームが未対応だと誤って主張したり（例：Pinterest は client.scrape.pinterest と client.search.pinterest の両方で対応しています）したことが確認されています。

ルール： 特定のプラットフォームメソッドを挙げる前に、references/scrapers.md を読み込んでください。このリファレンスファイルには、すべてのプラットフォーム、メソッドのシグネチャ、同期／非同期の対応状況一覧が記載されています。推測せず、確認してください。このセッションですでに references/scrapers.md を読み込んでいる場合は、コンテキスト内の内容を参照してください。再読み込みは不要です。

既知の捏造例（これらの名前は SDK に存在しません。過去の評価でモデルが作り出したものです）：

捏造された名前	正しい置き換え
client.scrape.linkedin.people(...)	client.scrape.linkedin.profiles(url=...)
client.scrape.instagram.users(...)	client.scrape.instagram.profiles(url=...)
client.list_datasets()	client.datasets.list()
asyncio.gather(*[client.scrape.X.<quick>(...) for ...])	トリガーパターン：「Batch gotcha」を参照

評価で新たな捏造例が見つかるたびに、この一覧は増えていきます。references/scrapers.md で確認していないものの、「正しそうに感じる」メソッド名を書こうとしている場合は、捏造の可能性が高いと考え、リファレンスを読み込んで確認してください。

便利な単独メソッド

特定のワークフローに属さないメソッドです。プラットフォームやルーティング判断に関連付けられていないため、見落としやすい傾向があります。モデルがこれらの一部を捏造したことがあります（client.datasets.list() ではなく client.list_datasets() とするなど）。以下の正規の名前を使用してください。

メソッド	機能
client.datasets.list()	実行時に 310 以上のすべてのデータセットを一覧表示します。dir() やイントロスペクションは使用せず、このメソッドを使用してください。
client.discover(query=, intent=)	企業、人、製品を AI でランク付けして検索します。上記の「サービスの選択」を参照してください。
client.scrape_url(url=...)	任意の URL 用のウェブアンロッカーです。専用のプラットフォームスクレイパーがないサイトに使用してください。
client.browser.get_connect_url()	Playwright／Puppeteer／Selenium 用の CDP WebSocket URL です。
client.list_zones()	有効な Bright Data ゾーンを一覧表示します。
client.delete_zone(name)	ゾーンを削除します。
client.test_connection()	API トークンが機能することを確認します。
client.get_account_info()	使用状況、クォータ、有効なゾーンを確認します。

リクエストへの対応方法

機能を探る

ユーザーが利用できる機能を知りたい場合や、「何ができますか？」と尋ねた場合は、次の8つのカテゴリーを説明してください。それぞれ、名前 — 機能 — 呼び出し例 — 使用する場面、の形式です。

1. プラットフォームのスクレイピング — 対応する11のプラットフォームから、URLを使って構造化データを抽出します。client.scrape.<platform>.<method>(url=...)（プラットフォーム：Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、ChatGPT、Perplexity、Pinterest、DigiKey）。ユーザーが対応プラットフォームのURLを持っていて、価格、プロフィール情報、投稿へのエンゲージメントなどの構造化フィールドを求めている場合に使用します。

2. プラットフォーム内検索 — キーワード、プロフィール、フィルターを使って、特定のプラットフォーム内を検索します。client.search.<platform>.<method>(...)。「キーワードでAmazonの商品を探す」「ハッシュタグでTikTokの動画を見つける」「レシピに関するPinterestのピンを探す」など、ユーザーが特定のURLを持たず、プラットフォーム内を検索したい場合に使用します。

3. ウェブ検索（SERP） — 検索エンジンの結果（タイトル、リンク、スニペット、順位）を構造化して取得します。client.search.google(query=...)（または .bing ／ .yandex）。「XについてGoogleで検索する」「Yに関するページや記事を探す」「Zのニュースを調べる」など、ユーザーがエンティティではなくウェブページを求めている場合に使用します。

4. ディスカバー（AI 搭載） — client.discover(query=..., intent=...) を使って、自然言語の条件に一致するエンティティ（企業、人、製品、場所）を探します。「ベルリンのAIスタートアップを探す」「Acme Corpの競合他社を探す」「Stripeで働いたことのある人を探す」「SaaSの価格設定の動向を調査する」など、ユーザーが説明に一致するエンティティの一覧を求めていて、ウェブページを求めていない場合に使用します。

5. データセット — 310以上の構築済みデータセットにアクセスし、過去のデータや大量のデータを大規模に取得します。client.datasets.<name>(filter=...)（その後 .download(snapshot_id)）。「LinkedInの企業データを一括取得する」「電子機器のAmazon価格の履歴を調べる」「テキサス州のZillow掲載物件をすべて取得する」など、ユーザーが1ページのライブデータではなく、多数のレコードを一度に求めている場合に使用します。

6. ウェブアンロッカー — 専用のプラットフォームスクレイパーがないサイトに対し、ボット対策を回避して任意のURLをスクレイピングします。client.scrape_url(url=...)。URLが一般的なウェブサイト（専用スクレイパーなし）の場合、またはプラットフォームスクレイパーが403エラーやブロックを返した場合の代替手段として使用します。

7. ブラウザー API — CDP（Chrome DevTools Protocol）経由でリモートブラウザーに接続し、実際のブラウザーを操作します。client.browser.get_connect_url()（その後、Playwright／Puppeteerで接続）。ログイン処理、JavaScriptを多用するシングルページアプリ、クリック／スクロール／入力操作、CAPTCHAなど、実際のブラウザーセッションが必要な場合に使用します。最もコストが高い方法です。より簡単な方法ではタスクを達成できない場合にのみ使用してください。

8. Scraper Studio — Bright Dataダッシュボードで設定した、構築済みまたはカスタムのスクレイピングテンプレートを実行します。client.scraper_studio.run(collector="c_xxx", input={...})。ユーザーから、プラットフォームスクレイパーでは対応していないテンプレートのコレクターIDが提供された場合に使用します。

各カテゴリーの詳細については、該当するリファレンスファイルを読み込むことを提案してください。

特定のURLからデータを抽出する

ユーザーがURLを持っていて、そのURLから構造化データを求めています。

URLが対応プラットフォームのものである場合（Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、ChatGPT、Perplexity、Pinterest、DigiKey — 対応プラットフォームと利用可能なメソッドの全一覧は references/scrapers.md を参照）：

• client.scrape.<platform>.<method>(url=...) を使用します
• 各プラットフォームで利用可能なメソッドを確認するには、references/scrapers.md を読みます

URLが未対応のプラットフォーム、または一般的なウェブサイトのものである場合：

• ボット対策を回避してページの生データを取得するには、client.scrape_url(url=...) を使用します
• ウェブアンロッカーのオプションについては、references/advanced.md を読みます

ユーザーが複数のURL（一括処理）を持っている場合：

• 順次処理によるブロックを避けるため、BrightDataClientとトリガーメソッド（_trigger サフィックス付き）を使用します
• まずすべてのトリガーを実行し、その後 job.wait() と job.to_result() で結果を収集します
• 一括実行のパターンについては、references/advanced.md を読みます

特定の URL を指定しない調査や情報の発見

ユーザーは情報を探したいものの、出発点となる URL がありません。

ウェブ検索結果（リンク、スニペット、ランキング）の場合：

• client.search.google(query=...)、client.search.bing(query=...)、または client.search.yandex(query=...) を使用します
• 利用可能な検索エンジンとパラメーターについては、references/search.md を参照してください

プラットフォーム固有の検索（Amazon で商品を探す、LinkedIn でプロフィールを探す、YouTube で動画を探すなど）の場合：

• client.search.<platform>.<method>(...) を使用します
• 検索メソッドは各プラットフォームの項目の下に記載されています。references/scrapers.md を参照してください

より詳しい情報の発見（条件に合う企業、人、エンティティを探す）の場合：

• client.discover(query=..., intent=...) を使用します
• Discover API にはキーワードだけでなく、意図を示すフレーズが必要です
• Discover API の詳細については、references/search.md を参照してください

大量データや履歴データが必要な場合

ユーザーが「大量データ」、「履歴データ」、「データベース」、「一覧」を求めている場合や、個別のページをスクレイピングせずに大規模なデータを求めている場合。

• 実行時に client.datasets.list() を使用して、利用可能なデータセットを確認します
• データセットのカテゴリと使用パターンについては、references/datasets-overview.md を参照してください
• フィルター済みのスナップショットを作成します：snapshot_id = client.datasets.<name>(filter={...})
• データをダウンロードします：data = client.datasets.<name>.download(snapshot_id)（デフォルト形式は jsonl です。json と csv もサポートしています）
• スナップショットの作成には時間がかかります。ダウンロードは準備が整うまで（最大 5 分）待機します

複数ステップの調査ワークフロー

ユーザーが幅広い調査を求めている場合（例：「ベルリンの競合他社を調査する」）。

ステップ 1：情報源を見つける

• エンティティレベルの情報発見には client.discover(query=..., intent=...) を使用します
• または、ウェブ検索結果の取得には client.search.google(query=...) を使用します

ステップ 2：見つかった情報源からデータを抽出する

• 見つかった各 URL に対して client.scrape.<platform>.<method>(url=...) を実行します
• URL が多い場合は、トリガーメソッドを使用して一括処理します

ステップ 3：必要に応じて大量データで情報を補う

• 見つかったエンティティの履歴情報について、client.datasets を確認します

インタラクティブなウェブタスク

ユーザーがログイン、クリック、スクロール、フォーム入力、または JavaScript の実行を必要としている場合。

• client.browser.get_connect_url() を使用して CDP WebSocket URL を取得します
• Playwright、Puppeteer、または別の CDP クライアントを使用して接続します
• これは最もコストの高い方法です。より簡単な方法で実行できない場合にのみ使用してください
• ブラウザー API の詳細については、references/advanced.md を参照してください

Scraper Studio テンプレート

ユーザーが既成またはカスタムのスクレイピングテンプレートを使用する場合。

• client.scraper_studio.run(collector="c_xxx", input={...}) を使用します
• コレクター ID が必要です。ユーザーはこれを指定するか、使用するテンプレートを把握している必要があります
• Scraper Studio の詳細については、references/advanced.md を参照してください

注意点

Browser API は最後の手段であり、デフォルトではありません

デフォルト： 対応プラットフォームのページ（Amazon の商品、LinkedIn のプロフィール、Instagram の投稿／リールなど）には、プラットフォームスクレイパーを使用します。

例外： ユーザーが次のいずれかを明示的に指定した場合は、ブラウザー API のリクエストに従います（その場合は適切なツールです）。 ログイン、サインイン、クリック、スクロール、入力欄への入力、文字入力、JavaScript の実行、CAPTCHA、スクリーンショット、PDF の生成、複数ステップのナビゲーション。

例外への例外： 上記のいずれも必要ないページについて、かつ URL が対応プラットフォーム上にあるにもかかわらず、ユーザーがブラウザー API をリクエストした場合は、従わないでください。プラットフォームスクレイパーのコードを提示し、費用と速度の違い（約 10 倍安価、約 30 秒対約 5 分）を説明してください。

# WRONG (browser when scraper would do):
cdp_url = client.browser.get_connect_url()
browser = await playwright.chromium.connect_over_cdp(cdp_url)
page = await browser.new_page()
await page.goto("https://amazon.com/dp/B09V3KXJPB")
# ↑ scraper is ~10x cheaper, ~30s vs ~5min, returns structured data not raw HTML

# RIGHT (use the platform scraper):
result = await client.scrape.amazon.products(url="https://amazon.com/dp/B09V3KXJPB")

# RIGHT — legitimate browser-API case (the user mentions login):
# User said "log into Amazon and check my recent orders"
cdp_url = client.browser.get_connect_url(country="us")
browser = await playwright.chromium.connect_over_cdp(cdp_url)
page = await browser.new_page()
await page.goto("https://amazon.com/login")
await page.fill("#ap_email", username)
# ... etc — browser is the right tool here.

• データセットから返されるのは過去のデータであり、ライブデータやリアルタイムデータではありません。ユーザーが最新のデータを必要としている場合は、プラットフォームスクレイパーまたは Web アンロッカーを使用してください。
• Discover API では、キーワードだけでなく、意図（探しているものを自然言語で説明したもの）が必要です。「restaurants」のような単独のキーワードは、「オースティン中心部で、屋外席のあるイタリア料理店を探す」のような意図を表すフレーズに言い換えてください。
• スクレイパーが 403 を返すか、ブロックされた場合は、フォールバックとして client.scrape_url()（Web アンロッカー）を試してください。ボット対策を処理できます。
• リクエストを満たすサービスのうち、常に最も安価なものを優先してください。費用の階層（安い順）：データセット → SERP → プラットフォームスクレイパー → Web アンロッカー → Discover → Scraper Studio → ブラウザー API。
• クライアントは常にコンテキストマネージャーとして使用してください。クライアントインスタンスを複数作成せず、セッション内のすべての操作で同じクライアントを再利用してください。
• 各スクレイパーには、クイック（結果が返るまでブロック）、トリガー（ジョブをすぐに返す）、手動（トリガー＋ステータス確認＋取得）の 3 つの実行パターンがあります。バッチ処理またはノンブロッキング実行が必要な場合を除き、デフォルトではクイックを使用してください。
• クイックメソッドは、プラットフォームやページの複雑さに応じて数分間ブロックします。短いタイムアウトは設定しないでください。SDK のデフォルト値はプラットフォームごとに調整されています。ほとんどの操作では 2～10 分かかることを想定してください。
• SDK はネットワークエラーとタイムアウトを自動で再試行します（3 回、指数バックオフ）。独自の再試行ロジックを追加しないでください。再試行が重複して API クレジットを無駄にします。
• データセットの操作では、データが直接返されるのではなく、snapshot_id が返されます。スナップショットには、scheduled → building → ready のライフサイクルがあります。スナップショットの準備が整うまでブロックする .download(snapshot_id) を使用してください。対応するダウンロード形式：json、jsonl、csv。

バッチ操作（多数の URL）の場合は、トリガーパターンを使用してください

理由： クイックメソッド（例：client.scrape.amazon.products）は、スクレイピングが完了するまで毎回 2～10 分間ブロックします。デフォルトの 10 req/s のレート制限を使っても、クイック呼び出し 200 件を asyncio.gather で実行すると、200 × 約 5 分 / 10（レート制限）= 約 100 分のブロック実行時間になります。トリガーパターンではリクエストを送信してジョブをすぐに返し、準備ができたら結果を並行して取得します。

# WRONG (anti-pattern, even with rate_limit respected):
results = await asyncio.gather(*[
    client.scrape.amazon.products(url=u) for u in urls
])  # ↑ each call blocks ~5min; total ~100min for 200 URLs

# RIGHT (trigger pattern):
jobs = [await client.scrape.amazon.products_trigger(url=u) for u in urls]
for job in jobs:
    await job.wait(timeout=600)
results = [await job.to_result() for job in jobs]
# ↑ total time ≈ longest single scrape ≈ 5-10 min, regardless of N

デフォルトのレート制限（10 req/s）により、トリガーの送信は順次行われます。並列処理が行われるのは待機フェーズであり、ステータス確認のポーリングだけなので、負荷は軽微です。トリガーを並列に送信するために asyncio.gather を使用しないでください。レート制限に達します。

• 同期環境（スクリプト、ノートブック、Claude Code）では、SyncBrightDataClient を使用してください。非同期環境では BrightDataClient を使用してください。どちらも同じメソッド名を使います。違いは、非同期呼び出しでは await が必要な点だけです。SyncBrightDataClient で _sync 接尾辞付きのメソッドは使用しないでください。注：同期クライアントが対応するプラットフォームは限られています。同期スクレイピングの対応対象：Amazon、LinkedIn、Instagram、Facebook、ChatGPT、Pinterest。同期検索の対応対象：Google、Bing、Yandex、Amazon、LinkedIn、Instagram、ChatGPT、Pinterest。TikTok、YouTube、Reddit、Perplexity、DigiKey のスクレイパー／検索、およびデータセット API には、非同期クライアントを使用してください。
• プラットフォーム検索メソッド（例：client.search.amazon.products()）は、プラットフォームスクレイパー（例：client.scrape.amazon.products()）とは異なります。検索ではキーワードから対象を探し、スクレイピングでは特定の URL からデータを抽出します。

例

「この Amazon 商品のレビューを取得して」

client.scrape.amazon.reviews(url="<the_url>") を使用します。 評価、テキスト、日付、レビュアー名を含む、構造化されたレビューのデータを返します。 簡易メソッドです。完了するまでブロックします（最大約 4 分）。

「ベルリンの AI スタートアップを探して」

ステップ 1：client.discover(query="AI startups in Berlin", intent="find technology companies") URL とメタデータを含む、一致したエンティティのリストを返します。

ステップ 2：URL がある各結果について、必要に応じて詳細データをスクレイピングします。 client.scrape.linkedin.companies(url=...) または client.scrape_url(url=...) を使用します。

「電子機器の過去の価格データが必要です」

ステップ 1：関連するデータセットを探すために client.datasets.list() を実行します。

ステップ 2：フィルターを指定してスナップショットを作成します。 snapshot_id = client.datasets.amazon_products(filter={"name": "category", "operator": "=", "value": "Electronics"}, records_limit=1000)

ステップ 3：データをダウンロードします。 data = client.datasets.amazon_products.download(snapshot_id)

注：スナップショットの作成中、ダウンロードはブロックします（最大 5 分）。デフォルトの形式は jsonl です（json と csv にも対応しています）。これは過去のデータ／一括データであり、リアルタイムの価格ではありません。レコードのリストを返します。

トラブルシューティング

• 401 Unauthorized：API トークンが無効か、期限切れです。クライアントのコンストラクターに渡したトークンを確認してください。
• 403 Forbidden / Blocked：対象サイトがリクエストをブロックしました。代替手段として client.scrape_url()（ウェブアンロッカー）を試すか、別のスクレイパーメソッドを使用してください。
• タイムアウト：タイムアウトを短くせず、長くしてください。処理によっては数分かかります。プラットフォーム固有のデフォルト値はすでに最適化されています。
• 「Dataset not found」：利用可能なデータセットを確認するには、client.datasets.list() を使用してください。データセットの属性名は snake_case です（例：amazon_products、linkedin_profiles）。
• サンドボックス環境での SSL／プロキシエラー：SSL 検証をスキップするには、クライアントのコンストラクターに ssl_verify=False を渡します。独自の証明書を使用する場合は、ssl_ca_cert='/path/to/cert.pem' を指定します。
• レート制限エラー：並列処理数を減らしてください。デフォルトの上限は毎秒 10 リクエストです。逐次呼び出しを使用するか、バッチ処理にはトリガーメソッドを使用してください。

参照資料を読み込むタイミング

• ユーザーが Amazon、LinkedIn、Facebook、Instagram、YouTube、TikTok、Reddit、ChatGPT、Perplexity、Pinterest、DigiKey やその他の特定のプラットフォームについて言及した場合は、references/scrapers.md を読んでください。そのプラットフォームで利用可能なスクレイパーメソッド、検索メソッド、パラメーターを確認できます。
• 特定のプラットフォームに触れずに、ユーザーが何かを 「探す」「検索する」「発見する」「調査する」「調べる」 よう求めた場合は、references/search.md を読んでください。SERP エンジンと Discover API のオプションを確認できます。
• ユーザーが 「一括データ」「過去のデータ」「データベース」「一覧」「データセット」 を求める場合や、大規模なデータを必要とする場合は、references/datasets-overview.md を読んでください。データセットのカテゴリーと、実行時に特定のデータセットを見つける方法を確認できます。
• ユーザーが 複数 URL のバッチ処理、ノンブロッキング実行、ブラウザーの自動化、JavaScript の実行、ログイン／セッション処理、カスタムスクレイピングテンプレート を必要としている場合、またはより簡単な方法でうまくいかなかった場合は、references/advanced.md を読んでください。実行パターン、バッチワークフロー、Web Unlocker、Browser API、Scraper Studio の詳細を確認できます。