Python SDK

安装软件包

打开终端并运行：

pip install brightdata-sdk

在你的代码文件中，导入该软件包并发起你的第一个请求：

from brightdata import BrightDataClient

# Initialize client (auto-loads from BRIGHTDATA_API_TOKEN env var)
client = BrightDataClient()

# Search Google
results = client.search.google(query="best selling shoes")

if results.success:
    print(f"Found {len(results.data)} results")
    for item in results.data[:5]:
        print(f"{item['position']}. {item['title']}")

SDK 会自动从 BRIGHTDATA_API_TOKEN 环境变量或 .env 文件加载你的 API token。你也可以直接传入：BrightDataClient(token="your_token")

启动抓取和网络搜索

尝试以下示例，在你的 IDE 中使用 Bright Data 的 SDK 功能

from brightdata import BrightDataClient

client = BrightDataClient()

# Google search
results = client.search.google(
    query="best shoes of 2025",
    location="United States",
    language="en",
    num_results=20
)

# Bing search
results = client.search.bing(
    query="python tutorial",
    location="United States"
)

# Yandex search
results = client.search.yandex(
    query="latest news",
    location="Germany"
)

if results.success:
    print(f"Cost: \${results.cost:.4f}")
    print(f"Time: {results.elapsed_ms():.2f}ms")

当处理多个查询或 URL 时，请求会并发处理以获得最佳性能。

使用平台特定抓取器获取结构化数据

从流行平台提取结构化数据，如 Amazon、LinkedIn、ChatGPT、Facebook 和 Instagram

from brightdata import BrightDataClient
from brightdata.payloads import AmazonProductPayload

client = BrightDataClient()

# Scrape Amazon product with type-safe payload
payload = AmazonProductPayload(
    url="https://amazon.com/dp/B0CRMZHDG8",
    reviews_count=50
)

result = client.scrape.amazon.products(**payload.to_dict())

if result.success:
    product = result.data[0]
    print(f"Title: {product['title']}")
    print(f"Price: \${product['final_price']}")
    print(f"Rating: {product['rating']}")

# Scrape reviews with filters
result = client.scrape.amazon.reviews(
    url="https://amazon.com/dp/B0CRMZHDG8",
    pastDays=30,
    keyWord="quality",
    numOfReviews=100
)

在你的 IDE 中，将鼠标悬停在 BrightDataClient 类或其任何方法上，即可查看可用参数、类型提示和使用示例。SDK 提供完整的 IntelliSense 支持！

使用 dataclass payloads 以保证类型安全

SDK 包含带运行时验证和辅助属性的 dataclass payloads

from brightdata import BrightDataClient
from brightdata.payloads import (
    AmazonProductPayload,
    LinkedInJobSearchPayload,
    ChatGPTPromptPayload
)

client = BrightDataClient()

# Amazon product with validation
amazon_payload = AmazonProductPayload(
    url="https://amazon.com/dp/B123456789",
    reviews_count=50  # 运行时验证!
)
print(f"ASIN: {amazon_payload.asin}")  # 辅助属性
print(f"Domain: {amazon_payload.domain}")

# LinkedIn job search
linkedin_payload = LinkedInJobSearchPayload(
    keyword="python developer",
    location="San Francisco",
    remote=True
)
print(f"远程搜索: {linkedin_payload.is_remote_search}")

# Use with client
result = client.scrape.amazon.products(**amazon_payload.to_dict())

连接抓取浏览器

使用 SDK 轻松连接到 Bright Data 的抓取浏览器

from brightdata import BrightDataClient
from playwright.sync_api import Playwright, sync_playwright

client = BrightDataClient(
    token="your_api_token",
    browser_username="username-zone-browser_zone1",
    browser_password="your_password"
)

def scrape(playwright: Playwright, url='https://example.com'):
    browser = playwright.chromium.connect_over_cdp(client.connect_browser())
    try:
        print(f'已连接! 正在导航到 {url}...')
        page = browser.new_page()
        page.goto(url, timeout=2*60_000)
        print('已导航! 正在抓取页面内容...')
        data = page.content()
        print(f'抓取完成! 数据长度: {len(data)}')
    finally:
        browser.close()

def main():
    with sync_playwright() as playwright:
        scrape(playwright)

if __name__ == '__main__':
    main()

使用 CLI 工具

SDK 包含一个强大的命令行界面，可在终端使用

# 搜索操作
brightdata search google "python tutorial" --location "United States"
brightdata search linkedin jobs --keyword "python developer" --remote

# 抓取操作
brightdata scrape amazon products "https://amazon.com/dp/B123"
brightdata scrape linkedin profiles "https://linkedin.com/in/johndoe"

# 通用网页抓取
brightdata scrape generic "https://example.com" --output-format pretty

# 保存结果到文件
brightdata search google "AI news" --output-file results.json

异步使用以提高性能

对于并发操作，请使用异步 API：

import asyncio
from brightdata import BrightDataClient

async def scrape_multiple():
    # 使用异步上下文管理器
    async with BrightDataClient() as client:
        # 并发抓取多个 URL
        results = await client.scrape.generic.url_async([
            "https://example1.com",
            "https://example2.com",
            "https://example3.com"
        ])
        
        for result in results:
            if result.success:
                print(f"成功: {result.elapsed_ms():.2f}ms")

asyncio.run(scrape_multiple())

使用 *_async 方法时，请始终使用异步上下文管理器 (async with BrightDataClient() as client)。同步封装会自动处理此问题。

参数

客户端初始化

配置 BrightDataClient

client = BrightDataClient(
    token="your_token",                    # 自动从 BRIGHTDATA_API_TOKEN 加载
    customer_id="your_customer_id",        # 可选 - 自动从 BRIGHTDATA_CUSTOMER_ID 加载
    timeout=30,                            # 默认超时时间（秒）
    web_unlocker_zone="sdk_unlocker",      # Web Unlocker 区域名称
    serp_zone="sdk_serp",                  # SERP API 区域名称
    browser_zone="sdk_browser",            # Browser API 区域名称
    auto_create_zones=False,               # 自动创建缺失的区域
    validate_token=False                   # 初始化时验证 token
)

搜索操作

SERP API 参数

使用结构化结果的搜索引擎（Google、Bing、Yandex）

client.search.google(
    query="搜索词",           # 搜索查询（必填）
    location="United States", # 地理位置
    language="en",            # 语言代码
    num_results=20,           # 返回结果数量
    timeout=30                # 请求超时
)

client.search.bing(query="...", location="...")
client.search.yandex(query="...", location="...")

抓取操作

网页抓取参数

从 URL 提取数据，支持多种响应格式

client.scrape.generic.url(
    url="https://example.com",     # 单个 URL 或 URL 列表（必填）
    response_format="raw",         # "raw" 或 "json"
    timeout=30,                    # 请求超时
    country="US"                   # 两位国家代码
)

平台抓取器

Amazon, LinkedIn, ChatGPT, Facebook, Instagram

平台特定抓取器，输出结构化数据Amazon:

client.scrape.amazon.products(url="...", reviews_count=50)
client.scrape.amazon.reviews(url="...", pastDays=30, numOfReviews=100)
client.scrape.amazon.sellers(url="...")

LinkedIn:

# URL 抓取 (scrape namespace)
client.scrape.linkedin.profiles(url="...")
client.scrape.linkedin.companies(url="...")
client.scrape.linkedin.jobs(url="...")

# 搜索 (search namespace)
client.search.linkedin.jobs(keyword="...", location="...", remote=True)
client.search.linkedin.profiles(firstName="...", lastName="...")
client.search.linkedin.posts(profile_url="...", start_date="...")

Facebook & Instagram:

client.scrape.facebook.posts_by_profile(url="...", num_of_posts=10)
client.scrape.facebook.comments(url="...", num_of_comments=100)
client.scrape.instagram.profiles(url="...")
client.search.instagram.posts(url="...", post_type="reel")

ChatGPT:

client.scrape.chatgpt.prompt(prompt="...", web_search=True)
client.scrape.chatgpt.prompts(prompts=["...", "..."])

结果对象

带元数据的丰富结果模型

所有操作返回包含时间和费用信息的结果对象

result = client.scrape.amazon.products(url="...")

# 访问数据
result.success       # bool - 操作是否成功
result.data          # Any - 抓取的数据
result.error         # str | None - 错误信息
result.cost          # float | None - 美元花费
result.platform      # str | None - 平台名称
result.method        # str | None - 使用的方法

# 时间信息
result.elapsed_ms()              # 总耗时（毫秒）
result.get_timing_breakdown()    # 详细时间字典

# 序列化
result.to_dict()                 # 转为字典
result.to_json(indent=2)         # JSON 字符串
result.save_to_file("result.json")  # 保存到文件

错误处理与测试

连接测试

测试 API 连接性

from brightdata import BrightDataClient

client = BrightDataClient()

# 测试连接
is_valid = client.test_connection_sync()
print(f"连接有效: {is_valid}")

# 获取账户信息
info = client.get_account_info_sync()
print(f"区域数量: {info['zone_count']}")
print(f"活跃区域: {[z['name'] for z in info['zones']]}")

区域管理

管理 API 区域

SDK 可以自动创建所需区域，也可以手动管理

# 启用自动创建
client = BrightDataClient(auto_create_zones=True)

# 手动列出区域
zones = client.list_zones_sync()
for zone in zones:
    print(f"区域: {zone['name']} (类型: {zone.get('type', 'unknown')})")

错误处理

处理常见错误

from brightdata import BrightDataClient
from brightdata.exceptions import SSLError

try:
    client = BrightDataClient()
    result = client.scrape.generic.url("https://example.com")
    
    if result.success:
        print("成功!")
    else:
        print(f"错误: {result.error}")
        
except SSLError as e:
    # 提供平台相关的帮助信息
    print(f"SSL 错误: {e}")
except Exception as e:
    print(f"意外错误: {e}")

认证

设置 API 凭证

创建 Bright Data 账户并获取 API token选项 1：环境变量

export BRIGHTDATA_API_TOKEN="your_token"

选项 2：.env 文件

# .env
BRIGHTDATA_API_TOKEN=your_token
BRIGHTDATA_CUSTOMER_ID=your_customer_id  # 可选

选项 3：直接传入

client = BrightDataClient(token="your_token")

前往账户设置并确保你的 API key 拥有 管理员权限。

资源

GitHub 仓库

查看源代码、示例并参与贡献

代码示例

10+ 个可用示例，涵盖所有功能

API 文档

完整的 API 参考和指南

v2.0.0 新功能

🎨 Dataclass Payloads

类型安全的请求 payloads

运行时验证并提供有用的错误信息
IDE 自动补全支持
辅助属性 (.asin, .is_remote_search, .domain)
与结果模型一致

🖥️ CLI 工具

命令行界面

brightdata 命令可在终端使用
抓取和搜索操作
多种输出格式（JSON、pretty、minimal）
支持文件输出

📓 Jupyter 笔记本

交互式教程

5 个全面的笔记本
Pandas 集成示例
数据分析工作流程
批处理指南

🆕 新平台

Facebook & Instagram

Facebook 抓取器（帖子、评论、Reels）
Instagram 抓取器（个人资料、帖子、评论、Reels）
Instagram 搜索（帖子和 Reels 发现）

⚡ 性能

架构改进

单一共享 AsyncEngine（效率提升 8 倍）
减少内存占用
更好的资源管理
502+ 个全面测试

企业级 SDK，提供 100% 类型安全、异步优先架构和全面测试。专为数据科学家和开发者打造。

概览

产品

管理 API

安装软件包

启动抓取和网络搜索

使用平台特定抓取器获取结构化数据

使用 dataclass payloads 以保证类型安全

连接抓取浏览器

使用 CLI 工具

异步使用以提高性能

参数

错误处理与测试

资源

GitHub 仓库

代码示例

API 文档

v2.0.0 新功能

概览

产品

管理 API

​安装软件包

​启动抓取和网络搜索

​使用平台特定抓取器获取结构化数据

​使用 dataclass payloads 以保证类型安全

​连接抓取浏览器

​使用 CLI 工具

​异步使用以提高性能

​参数

​错误处理与测试

​资源

GitHub 仓库

代码示例

API 文档

​v2.0.0 新功能

安装软件包

启动抓取和网络搜索

使用平台特定抓取器获取结构化数据

使用 dataclass payloads 以保证类型安全

连接抓取浏览器

使用 CLI 工具

异步使用以提高性能

参数

错误处理与测试

资源

v2.0.0 新功能