実装

Lv2 は、Bright Data の各 API を「機能単位」で使い分ける段階です。Lv1 で認証と最小コールを理解したら、ここでは どの要件にどの API を当てるか を学びます。検索結果なら SERP API、保護ページの単発取得なら Web Unlocker、ブラウザ実行が必要なら Browser API、ドメイン全体なら Crawl API、という判断ができるようになるのが目標です。

前提

• 認証ガイド
• 基礎 / 認証方式
• 基礎 / API グループ
• ロードマップ Lv1

達成基準

• SERP API、Web Unlocker、Browser API、Crawl API の役割の違いを説明できる
• 単発の検索取得を実装できる
• JS-heavy サイトに Browser API を選ぶ判断ができる
• ドメイン単位の収集に Crawl API を選べる
• curl、SDK、CLI のどれを使うかを目的で決められる
• 403、CAPTCHA、timeout が出たときの API 切替案を出せる
• 小さなミニ機能を 1 つ作れる

代表ユースケース

• UC-SERP-001 Organic Keyword Tracking
• UC-WEB-001 保護サイトの安定収集基盤
• UC-WEB-002 JS-heavy サイトのブラウザ自動抽出
• UC-CRAWL-001 AI / LLM 学習データ収集

推奨ハンズオン

• Step 2 SERP API で順位監視
• Step 5 Browser API + Playwright

検索系とブラウザ系を 1 本ずつやると、Lv2 の代表パターンを早くつかめます。

API 選択の基準

実装パターン 1: SERP API でミニ機能を作る

Lv2 の最初の題材として、SERP API は扱いやすいです。検索キーワードを固定して、結果を保存するだけでも立派な機能になります。

curl -X POST https://api.brightdata.com/request \
  -H "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone": "serp_api1",
    "url": "https://www.google.com/search?q=bright+data",
    "format": "raw"
  }'

Lv2 では、この最小例を出発点にして次を足します。

• キーワードを配列で持つ
• 結果をファイルや DB に保存する
• 失敗したキーワードだけ再試行する

Python での最小保存

import json
import os
import requests
 
response = requests.post(
    "https://api.brightdata.com/request",
    headers={"Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}"},
    json={
        "zone": "serp_api1",
        "url": "https://www.google.com/search?q=bright+data",
        "format": "raw",
    },
    timeout=60,
)
 
response.raise_for_status()
with open("serp-result.html", "w", encoding="utf-8") as f:
    f.write(response.text)

最初は HTML 保存で十分です。Lv2 の目的は「取れたものを後で読める形で残す」ことです。

実装パターン 2: Browser API で JS-heavy サイトに切り替える

HTML 取得だけでは情報が出そろわないサイトでは、Browser API へ切り替えます。Playwright 経由で扱うと、既存のブラウザ自動化知識を流用しやすいです。

import { chromium } from "playwright";
 
const browser = await chromium.connectOverCDP(process.env.BRIGHTDATA_BROWSER_WS);
const page = await browser.newPage();
await page.goto("https://example.com", { waitUntil: "networkidle" });
console.log(await page.title());
await browser.close();

Lv2 で重要なのは、Browser API を「万能な正解」と見なさないことです。重い処理なので、SERP や Unlocker で済む要件にまで広げない判断が必要です。

CLI と SDK をどう使い分けるか

CLI

• 手元で素早く試す
• HTML、Markdown、スクリーンショットをざっと確認する
• チームに「まずこれで再現して」と共有する

SDK

• 複数 API を同じコードベースにまとめる
• 再試行、ログ、保存処理を組み込みたい
• Python か Node.js で継続実装する

curl

• 最小再現
• 認証確認
• ドキュメントの例を手元でそのまま試す

Lv2 でよくある判断ミス

SERP API で取れるものを Browser API で取ろうとする

検索結果が欲しいだけなら、まず SERP API を優先します。構造化しやすく、運用負荷も低いからです。

Crawl API を URL 1 本の確認に使う

Lv2 では、Crawl API は「広く回るもの」と理解するだけで十分です。単発確認にまで広げると、逆に全体像をつかみにくくなります。

取得失敗をすべて retry で押し切ろうとする

403、CAPTCHA、timeout は意味が違います。失敗理由を見て API を切り替える発想が必要です。

Lv2 を終える判断

次の状態になったら Lv3 に進めます。

• SERP、Unlocker、Browser、Crawl のどれを使うか説明できる
• 小さい用途に対して 1 つ API を選び、実装まで通せる
• 手元の検証コードを保存用スクリプトに育てられる
• 失敗時に「別の API を使うべきか」を考えられる

次に学ぶこと

Lv3 では、単発 API から一段進みます。Scrapers、Data Feeds、非同期ジョブ、Webhook、外部ストレージ連携を組み合わせて、「大量件数でも回る形」を身につけます。

• Lv3 応用
• Step 3 Crawl API で RAG データ収集
• Step 4 EC 分析データ収集