CLI セットアップ リファレンス

Bright Data CLI (bdata) のインストール、認証、トラブルシューティングは、単一の規範的なドキュメント場所で管理されています:

→ references/cli-setup.md

bdata をシェルアウトするタスクを実行する前に、このドキュメントを参照してください。

Bright Data APIs

Bright Data は、大規模なウェブデータ抽出のためのインフラストラクチャを提供します。4 つの主要な API が異なるユースケースをカバーしており、常にジョブに最も適切なツールを選択してください。

適切な API を選択する

ユースケース	API	理由
URL でページをスクレイプ (操作なし)	Web Unlocker	HTTP ベース、自動的にボット検出をバイパス、最も安い
Google / Bing / Yandex 検索結果	SERP API	SERP 抽出に特化、構造化データを返す
Amazon、LinkedIn、Instagram、TikTok などから構造化データを取得	Web Scraper API	事前構築されたスクレイパー、パース不要
クリック、スクロール、フォーム入力、JS 実行、XHR インターセプト	Browser API	完全なブラウザオートメーション
Puppeteer / Playwright / Selenium オートメーション	Browser API	CDP/WebDriver 経由で接続

認証パターン (すべての API)

すべての API は同じ認証モデルを共有しています。以下の環境変数は、REST API の直接統合に適用されます。bdata CLI を使用している場合、bdata login がこれらすべてを自動的に処理します (参照: references/cli-setup.md)。

export BRIGHTDATA_API_KEY="your-api-key"         # コントロールパネル > アカウント設定から取得
export BRIGHTDATA_UNLOCKER_ZONE="zone-name"       # Web Unlocker ゾーン名
export BRIGHTDATA_SERP_ZONE="serp-zone-name"      # SERP API ゾーン名
export BROWSER_AUTH="brd-customer-ID-zone-NAME:PASSWORD"  # Browser API 認証情報

Web Unlocker および SERP API の REST API 認証ヘッダー:

Authorization: Bearer YOUR_API_KEY

---

Web Unlocker API

HTTP ベースのスクレイピングプロキシ。ブラウザ操作なしで簡単なページ取得に最適です。

エンドポイント: POST https://api.brightdata.com/request

import requests

response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "zone": "YOUR_ZONE_NAME",
        "url": "https://example.com/product/123",
        "format": "raw"
    }
)
html = response.text

キーパラメータ

パラメータ	型	説明
zone	string	ゾーン名 (必須)
url	string	ターゲット URL (http:// または https:// を含む) (必須)
format	string	"raw" (HTML) または "json" (構造化ラッパー) (必須)
method	string	HTTP メソッド、デフォルト "GET"
country	string	地理的ターゲティング用 2 文字 ISO コード (例: "us"、"de")
data_format	string	変換: "markdown" または "screenshot"
async	boolean	非同期モード用 true

クイックパターン

# Markdown を取得 (LLM 入力に最適)
response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"zone": ZONE, "url": url, "format": "raw", "data_format": "markdown"}
)

# 地理的ターゲティング付きリクエスト
json={"zone": ZONE, "url": url, "format": "raw", "country": "de"}

# デバッグ用スクリーンショット
json={"zone": ZONE, "url": url, "format": "raw", "data_format": "screenshot"}

# バルク処理用非同期
json={"zone": ZONE, "url": url, "format": "raw", "async": True}

重要なルール: Web Unlocker を Puppeteer、Playwright、Selenium、または anti-detect ブラウザと一緒に使用しないでください。代わりに Browser API を使用してください。

references/web-unlocker.md を参照して、プロキシインターフェース、特殊ヘッダー、非同期フロー、機能、課金を含む完全なリファレンスを確認してください。

---

SERP API

Google、Bing、Yandex、DuckDuckGo の構造化検索エンジン結果抽出。

エンドポイント: POST https://api.brightdata.com/request (Web Unlocker と同じ)

response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "zone": "YOUR_SERP_ZONE",
        "url": "https://www.google.com/search?q=python+web+scraping&brd_json=1&gl=us&hl=en",
        "format": "raw"
    }
)
data = response.json()
for result in data.get("organic", []):
    print(result["rank"], result["title"], result["link"])

必須 Google URL パラメータ

パラメータ	説明	例
q	検索クエリ	q=python+web+scraping
brd_json	パース済み JSON 出力	brd_json=1 (データパイプラインでは常に使用)
gl	検索対象国	gl=us
hl	言語	hl=en
start	ページネーション オフセット	start=10 (ページ 2)、start=20 (ページ 3)
tbm	検索タイプ	tbm=nws (ニュース)、tbm=isch (画像)、tbm=vid (ビデオ)
brd_mobile	デバイス	brd_mobile=1 (モバイル)、brd_mobile=ios
brd_browser	ブラウザ	brd_browser=chrome
brd_ai_overview	AI Overview をトリガー	brd_ai_overview=2
uule	エンコードされたジオロケーション	正確なロケーション ターゲティング用

注: num パラメータは 2025 年 9 月時点で 廃止予定 です。ページネーションには start を使用してください。

パース済み JSON レスポンス構造

{
  "organic": [{"rank": 1, "global_rank": 1, "title": "...", "link": "...", "description": "..."}],
  "paid": [],
  "people_also_ask": [],
  "knowledge_graph": {},
  "related_searches": [],
  "general": {"results_cnt": 1240000000, "query": "..."}
}

Bing キーパラメータ

パラメータ	説明
q	検索クエリ
setLang	言語 (4 文字推奨: en-US)
cc	国コード
first	ページネーション (10 ずつ増分: 1、11、21...)
safesearch	off、moderate、strict
brd_mobile	デバイスタイプ

バルク SERP 用非同期

# 送信
response = requests.post(
    "https://api.brightdata.com/request",
    params={"async": "1"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"zone": SERP_ZONE, "url": "https://www.google.com/search?q=test&brd_json=1", "format": "raw"}
)
response_id = response.headers.get("x-response-id")

# 取得 (取得呼び出しは課金されません)
result = requests.get(
    "https://api.brightdata.com/serp/get_result",
    params={"response_id": response_id},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

課金: 成功したリクエスト 1,000 件ごとに支払い。非同期取得呼び出しは課金されません。

references/serp-api.md を参照して、Maps、Trends、Reviews、Lens、Hotels、Flights パラメータを含む完全なリファレンスを確認してください。

---

Web Scraper API

100 以上のプラットフォームから構造化データを抽出するための事前構築スクレイパー。パース ロジックは不要です。

同期エンドポイント: POST https://api.brightdata.com/datasets/v3/scrape 非同期エンドポイント: POST https://api.brightdata.com/datasets/v3/trigger

# 同期 (最大 20 URL、すぐに結果を返す)
response = requests.post(
    "https://api.brightdata.com/datasets/v3/scrape",
    params={"dataset_id": "YOUR_DATASET_ID", "format": "json"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"input": [{"url": "https://www.amazon.com/dp/B09X7M8TBQ"}]}
)

if response.status_code == 200:
    data = response.json()  # 結果は即座に利用可能
elif response.status_code == 202:
    snapshot_id = response.json()["snapshot_id"]  # 完了をポーリング

パラメータ

パラメータ	型	説明
dataset_id	string	スクレイパー ライブラリのスクレイパー識別子 (必須)
format	string	json (デフォルト)、ndjson、jsonl、csv
custom_output_fields	string	パイプ区切りフィールド: url|title|price
include_errors	boolean	結果にエラー情報を含める

リクエスト ボディ

{
  "input": [
    { "url": "https://www.amazon.com/dp/B09X7M8TBQ" },
    { "url": "https://www.amazon.com/dp/B0B7CTCPKN" }
  ]
}

非同期結果のポーリング

import time

# トリガー
snapshot_id = requests.post(
    "https://api.brightdata.com/datasets/v3/trigger",
    params={"dataset_id": DATASET_ID, "format": "json"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"input": [{"url": u} for u in urls]}
).json()["snapshot_id"]

# ポーリング
while True:
    status = requests.get(
        f"https://api.brightdata.com/datasets/v3/progress/{snapshot_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()["status"]

    if status == "ready": break
    if status == "failed": raise Exception("Job failed")
    time.sleep(10)

# ダウンロード
data = requests.get(
    f"https://api.brightdata.com/datasets/v3/snapshot/{snapshot_id}",
    params={"format": "json"},
    headers={"Authorization": f"Bearer {API_KEY}"}
).json()

進捗ステータス値: starting → running → ready | failed データ保持: 30 日間。 課金: 配信されたレコード単位。失敗した無効な入力 URL も課金対象です。

references/web-scraper-api.md を参照して、スクレイパー タイプ、出力形式、配信オプション、課金詳細を含む完全なリファレンスを確認してください。

---

Browser API (Scraping Browser)

CDP/WebDriver を使用した完全ブラウザオートメーション。CAPTCHA、フィンガープリント、anti-bot 検出を自動的に処理します。

接続:

• Playwright/Puppeteer: wss://${AUTH}@brd.superproxy.io:9222
• Selenium: https://${AUTH}@brd.superproxy.io:9515

const { chromium } = require("playwright-core");

const AUTH = process.env.BROWSER_AUTH;
const browser = await chromium.connectOverCDP(`wss://${AUTH}@brd.superproxy.io:9222`);
const page = await browser.newPage();
page.setDefaultNavigationTimeout(120000); // 常に 2 分に設定

await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
const html = await page.content();
await browser.close();

from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp(f"wss://{AUTH}@brd.superproxy.io:9222")
    page = await browser.new_page()
    page.set_default_navigation_timeout(120000)
    await page.goto("https://example.com", wait_until="domcontentloaded")
    html = await page.content()
    await browser.close()

カスタム CDP 関数

関数	目的
Captcha.solve	手動で CAPTCHA を解く
Captcha.setAutoSolve	CAPTCHA 自動解決を有効/無効にする
Proxy.setLocation	正確なジオロケーションを設定 (goto の前に呼び出し)
Proxy.useSession	セッション間で同じ IP を保持
Emulation.setDevice	デバイス プロファイルを適用 (iPhone 14 など)
Emulation.getSupportedDevices	利用可能なデバイス プロファイルを一覧表示
Unblocker.enableAdBlock	広告をブロックして帯域幅を節約
Unblocker.disableAdBlock	広告を再度有効にする
Input.type	バルク フォーム入力用の高速テキスト入力
Browser.addCertificate	セッション用のクライアント SSL 証明書をインストール
Page.inspect	ライブ セッション用の DevTools デバッグ URL を取得

// カスタム関数用 CDP セッション パターン
const client = await page.target().createCDPSession();

// タイムアウト付き CAPTCHA 解決
const result = await client.send("Captcha.solve", { timeout: 30000 });

// 正確なジオロケーション (goto の前に必須)
await client.send("Proxy.setLocation", {
  latitude: 37.7749,
  longitude: -122.4194,
  distance: 10,
  strict: true
});

// 不要なリソースをブロック
await client.send("Network.setBlockedURLs", { urls: ["*google-analytics*", "*.ads.*"] });

// デバイス エミュレーション
await client.send("Emulation.setDevice", { deviceName: "iPhone 14" });

セッション ルール

• セッションあたり 1 回の初期ナビゲーション — 新しい URL = 新しいセッション
• アイドル タイムアウト: 5 分
• 最大期間: 30 分

ジオロケーション

• 国レベル: 認証情報ユーザー名に -country-us を追加
• EU 全体: -country-eu を追加 (29 以上のヨーロッパ諸国をルーティング)
• 正確: Proxy.setLocation CDP コマンドを使用 (ナビゲーション前)

エラーコード

コード	問題	修正
407	ポート番号が間違っている	Playwright/Puppeteer → 9222、Selenium → 9515
403	不正な認証	認証情報形式とゾーン タイプを確認
503	サービス スケーリング	1 分待機して再接続

課金: トラフィック ベースのみ。画像/CSS/フォントをブロックしてコストを削減します。

references/browser-api.md を参照して、すべての CDP 関数、帯域幅最適化、CAPTCHA パターン、デバッグを含む完全なリファレンスを確認してください。

---

詳細リファレンス

• references/web-unlocker.md — Web Unlocker: 完全なパラメータ リスト、プロキシ インターフェース、特殊ヘッダー、非同期フロー、機能、課金、アンチパターン
• references/serp-api.md — SERP API: すべての Google パラメータ (Maps、Trends、Reviews、Lens、Hotels、Flights)、Bing パラメータ、パース済み JSON 構造、非同期、課金
• references/web-scraper-api.md — Web Scraper API: 同期対非同期、すべてのパラメータ、ポーリング、スクレイパー タイプ、出力形式、課金
• references/browser-api.md — Browser API: 接続文字列、セッション ルール、すべての CDP 関数、ジオターゲティング、帯域幅最適化、CAPTCHA、デバッグ、エラー コード