bright-data-best-practices

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

Bright Data CLI（bdata）のインストール、認証、トラブルシューティングは、次の単一の正式なドキュメントに記載されています。

→ references/cli-setup.md

bdata をシェルから実行するタスクに取りかかる前に、必ず参照してください。

Bright Data API

Bright Data は、大規模なウェブデータ抽出のためのインフラを提供しています。主な API は、用途別に 4 種類あります。常に、タスクに最も適したツールを選んでください。

適切な 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 経由で接続します
独自の HTTP クライアントを生のプロキシ（DC／ISP／Residential／Mobile）経由でルーティングする	Proxy networks	マネージド API ではなく、独自のリクエストロジックでプロキシに直接アクセスする必要がある場合は、proxy.md スキルを参照してください

認証パターン（全 API 共通）

すべての API で同じ認証方式を使用します。以下の環境変数は、REST API を直接統合する場合に適用されます。bdata CLI を使用する場合は、bdata login がこれらをすべて自動的に処理します（references/cli-setup.md を参照）。

export BRIGHTDATA_API_KEY="your-api-key"         # From Control Panel > Account Settings
export BRIGHTDATA_UNLOCKER_ZONE="zone-name"       # Web Unlocker zone name
export BRIGHTDATA_SERP_ZONE="serp-zone-name"      # SERP API zone name
export BROWSER_AUTH="brd-customer-ID-zone-NAME:PASSWORD"  # Browser API credentials

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	http:// または https:// を含む対象 URL（必須）
format	string	"raw"（HTML）または "json"（構造化されたラッパー）（必須）
method	string	HTTP メソッド。デフォルトは "GET"
country	string	地域ターゲティング用の 2 文字の ISO コード（例："us"、"de"）
data_format	string	変換形式："markdown" または "screenshot"
async	boolean	非同期モードの場合は true

よく使うパターン

# Get markdown (best for LLM input)
response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"zone": ZONE, "url": url, "format": "raw", "data_format": "markdown"}
)

# Geo-targeted request
json={"zone": ZONE, "url": url, "format": "raw", "country": "de"}

# Screenshot for debugging
json={"zone": ZONE, "url": url, "format": "raw", "data_format": "screenshot"}

# Async for bulk processing
json={"zone": ZONE, "url": url, "format": "raw", "async": True}

重要なルール： Puppeteer、Playwright、Selenium、またはアンチ検出ブラウザーで Web Unlocker を使用しないでください。代わりに 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 用の非同期処理

# Submit
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")

# Retrieve (retrieve calls are NOT billed)
result = requests.get(
    "https://api.brightdata.com/serp/get_result",
    params={"response_id": response_id},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

課金： 成功したリクエスト 1,000 件ごとに課金されます。非同期の取得呼び出しは課金対象外です。

Maps、Trends、Reviews、Lens、Hotels、Flights のパラメーターを含む完全なリファレンスについては、references/serp-api.md をご覧ください。

---

Web Scraper API

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

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

# Sync (up to 20 URLs, returns immediately)
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()  # Results ready
elif response.status_code == 202:
    snapshot_id = response.json()["snapshot_id"]  # Poll for completion

パラメーター

パラメーター	型	説明
dataset_id	string	Scraper Library のスクレーパー識別子（必須）
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

# Trigger
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"]

# Poll
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)

# Download
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、フィンガープリンティング、ボット対策検出に自動で対応します。

接続：

• 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); // Always set to 2 minutes

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 session pattern for custom functions
const client = await page.target().createCDPSession();

// CAPTCHA solve with timeout
const result = await client.send("Captcha.solve", { timeout: 30000 });

// Precise geo location (must be before goto)
await client.send("Proxy.setLocation", {
  latitude: 37.7749,
  longitude: -122.4194,
  distance: 10,
  strict: true
});

// Block unnecessary resources
await client.send("Network.setBlockedURLs", { urls: ["*google-analytics*", "*.ads.*"] });

// Device emulation
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、フォントをブロックしてください。

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

---

詳細なリファレンス

• 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、デバッグ、エラーコード

関連スキル

• brightdata-proxy — 管理対象 API ではなく独自の HTTP クライアントを使って、Bright Data の生のプロキシネットワーク（Datacenter、ISP、Residential、Mobile）経由でリクエストをルーティングする場合に使用します。ネットワーク／IP プールの選択、brd-customer-... ユーザー名の形式、ターゲティングとスティッキーセッションのパラメーター、Residential／Mobile 用の SSL CA 設定、cURL、Python（requests/httpx/aiohttp/Scrapy）、Node（fetch/axios）、Playwright、Puppeteer、Selenium との統合について説明します。タスクが Web Unlocker／SERP／Web Scraper／Browser API ではなく、生のプロキシアクセスの場合は必ずこちらに引き継いでください。プロキシで継続的にブロックされる場合のエスカレーション順：生のプロキシ → Web Unlocker → Browser API → Web Scraper API。