{ "openapi": "3.0.1", "info": { "title": "Brightdata SERP API", "description": "将 Bright Data SERP API 集成到您的管道中，以确保高精度的数据抓取", "version": "1.0.0" }, "servers": [ { "url": "https://api.brightdata.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/request": { "get": { "description": "", "parameters": [ { "in": "query", "name": "zone", "description": "区域标识符，用于定义您的 Bright Data 产品配置。请在此查看您的区域: https://brightdata.com/cp/zones", "required": true, "schema": { "type": "string" } }, { "name": "url", "in": "query", "description": "要抓取的完整目标 URL。必须包含协议（http/https）。示例: `https://www.google.com/search?q=pizza`", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "format", "description": "响应格式：`raw` 返回 HTML 内容，`json` 返回结构化数据", "required": true, "schema": { "type": "string", "enum": ["raw", "json"] }, "example": "json" }, { "name": "method", "in": "query", "description": "请求的 HTTP 方法", "required": false, "schema": { "type": "string", "default": "GET" } }, { "name": "country", "in": "query", "description": "用于代理位置的两位 ISO 3166-1 国家代码", "required": false, "schema": { "type": "string", "pattern": "^[a-z]{2}$" }, "example": "us" }, { "name": "data_format", "description": "附加响应格式：`markdown` 将 HTML 转为 Markdown，`screenshot` 返回页面 PNG 截图", "required": false, "in": "query", "schema": { "type": "string", "enum": ["markdown", "screenshot"] } } ], "responses": { "200": { "description": "成功提取 SERP 数据", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SerpJsonResponse" } }, "text/html": { "schema": { "type": "string", "description": "当 format=raw 时返回原始 HTML 内容" } } } }, "400": { "description": "请求错误 - 缺少 zone 参数或 URL 无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing_zone": { "summary": "缺少区域参数", "value": { "error": "请求错误", "message": "缺少必需参数: zone", "code": "MISSING_ZONE" } } } } } }, "401": { "description": "未授权 - API Key 无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_api_key": { "summary": "无效 API Key", "value": { "error": "未授权", "message": "提供的 API Key 无效", "code": "INVALID_API_KEY" } } } } } } } }, "post": { "description": "", "parameters": [ { "in": "query", "name": "async", "description": "设置为 `true` 以异步执行", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP200" } } } }, "401": { "description": "未授权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP401" } } } }, "400": { "description": "请求错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP400" } } } } } } }, "/response": { "get": { "description": "", "parameters": [ { "in": "query", "name": "response_id", "description": "响应 ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP200" } } } }, "401": { "description": "未授权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP401" } } } }, "400": { "description": "请求错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTP400" } } } } } } } }, "components": { "schemas": { "PostBody": { "required": ["zone", "url", "format"], "type": "object", "properties": { "zone": { "description": "区域标识符，用于定义您的 Bright Data 产品配置。每个区域包含目标规则、输出偏好和访问权限。\n管理区域: https://brightdata.com/cp/zones", "type": "string", "example": "serp_api1" }, "url": { "description": "要抓取的完整目标 URL。必须包含协议（http/https），并可公开访问。", "type": "string", "example": "https://www.google.com/search?q=pizza" }, "format": { "description": "响应格式：`raw` 返回 HTML 字符串，`json` 返回结构化数据。", "type": "string", "enum": ["raw", "json"], "example": "json" }, "method": { "description": "通过代理请求 HTML 的方法为 `GET`。", "type": "string", "default": "GET", "example": "GET" }, "country": { "description": "用于代理位置的两位 ISO 3166-1 国家代码（如 `us`、`gb`、`de`、`ca`、`au`）。如果未指定，系统会根据区域配置自动选择最佳位置。\n国家代码列表: https://docs.brightdata.com/cn/general/faqs#where-can-i-see-the-list-of-country-codes", "type": "string", "example": "us" }, "data_format": { "description": "附加响应格式转换：`markdown` 将 HTML 转为干净的 Markdown，`screenshot` 截取页面 PNG 图片。", "type": "string", "enum": ["markdown", "screenshot"], "example": "markdown" } } }, "HTTP200": { "type": "string", "example": "OK" }, "HTTP401": { "type": "string", "example": "需要用户认证" }, "HTTP400": { "type": "string", "example": "请求错误" }, "SerpJsonResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" }, "next_page": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。\n\n**认证方法:**\n1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users\n2. 在请求的 Authorization 头中包含 API Key\n3. 格式: `Authorization: Bearer YOUR_API_KEY`\n\n**示例:**\n```\nAuthorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df\n```\n\n了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？", "bearerFormat": "API Key" } } } }