web-scraper-api

Oxylabs Web Scraper API

身份验证

需要使用环境变量中的凭据进行 HTTP Basic Auth 身份验证：

curl -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" ...

端点

POST https://realtime.oxylabs.io/v1/queries   # immediate response
POST https://data.oxylabs.io/v1/queries       # Push-Pull jobs, callbacks, storage
Content-Type: application/json

核心参数

参数	必填	描述
source	是	目标抓取器（例如 universal、amazon_product、google_search）
url	有条件必填	要抓取的 URL（适用于 universal 和 *_url 来源）
query	有条件必填	搜索查询或商品 ID（适用于 *_search 和 *_product 来源）
parse	否	启用结构化数据解析（对于支持的来源，建议启用）
render	否	JavaScript 渲染：html 或 png
geo_location	否	地理定位：支持时可使用国家/州/城市、ZIP/邮政编码、坐标或 Criteria ID
session_id	否	在多个任务中复用同一代理 IP
content_encoding	否	通过 Realtime 或 Push-Pull 下载图片文件时，设为 base64
user_agent_type	否	设备/浏览器预设，例如 desktop_chrome、mobile_ios、tablet_android
locale	否	界面语言 / Accept-Language，例如 de-DE
callback_url	否	Push-Pull 回调端点
storage_type、storage_url	否	Push-Pull 云上传目标（gcs、s3、tos、s3_compatible）
markdown、xhr	否	启用 markdown 或捕获的 XHR 结果类型
browser_instructions	否	渲染后的浏览器操作；需要 render: "html"
parsing_instructions、parser_preset	否	自定义解析规则或已保存的预设；与 parse: true 配合使用
client_notes	否	与任务元数据一同保存的客户端任务标签
domain、subdomain、start_page、pages、limit、store_id、delivery_zip、fulfillment_type	依来源而定	市场/搜索/商店定位及分页字段

user_agent_type 的取值：desktop、desktop_chrome、desktop_edge、desktop_firefox、desktop_opera、desktop_safari、mobile、mobile_android、mobile_ios、tablet、tablet_android、tablet_ios。

上下文参数

在 context 中以 { "key": "...", "value": ... } 对象的形式添加以下参数：

键	用途
force_headers、headers	将自定义标头与托管标头合并
force_cookies、cookies	将自定义 Cookie 与托管 Cookie 合并
http_method、content	使用 post，并通过 Base64 编码请求正文内容
follow_redirects	跟随 3xx 重定向链
successful_status_codes	将指定的非标准 HTTP 状态码视为成功

如需多格式输出，请在负载中启用相应类型（parse、markdown、xhr、render: "png"），并通过 ?type=raw,parsed,png,markdown,xhr 请求这些类型。

对于批量 Push-Pull 任务，请使用 POST /v1/queries/batch，且仅对 query 或 url 使用数组；其他所有参数都应使用单个值。批量大小上限为 5,000 个值。

快速入门

抓取任意 URL：

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"source": "universal", "url": "https://example.com"}'

启用解析的 Google 搜索：

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"source": "google_search", "query": "best laptops", "parse": true}'

通过 ASIN 获取 Amazon 商品：

curl -X POST 'https://realtime.oxylabs.io/v1/queries' \
  -u "$OXY_WSA_USERNAME:$OXY_WSA_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"source": "amazon_product", "query": "B07FZ8S74R", "parse": true}'

选择合适的来源

1. 有可用的专用来源时优先使用（amazon_product、google_search）——解析效果更好，也更可靠
2. 对于不受支持的网站，使用 universal——适用于任意 URL
3. 启用 parse: true，以便在受支持的来源上获取结构化 JSON 输出

响应结构

{
  "results": [{
    "content": "...",
    "status_code": 200,
    "url": "https://..."
  }]
}

启用 parse: true 后，content 包含结构化数据（标题、价格、评论等），而非原始 HTML。

可用来源

按类别整理的 40 多种受支持来源的完整列表，请参阅 sources.md。

更多示例

如需包含地理定位、JavaScript 渲染和自定义标头的详细请求/响应示例，请参阅 examples.md。

错误处理

代码	含义
200	成功
400	参数无效
401	身份验证失败
403	拒绝访问
429	超出速率限制

关键指南

• 对受支持的来源，始终设置 parse: true 以获取结构化数据
• 美国电商地理定位使用 ZIP 邮编（例如，"90210"）
• 搜索引擎使用国家/州格式（例如，"California,United States"）
• 对 JavaScript 密集型页面添加 render: "html"
• 仅在强制渲染的页面上，为禁用自动强制渲染而设置 render: ""；对于已渲染的 Realtime 或 Proxy Endpoint 请求，将客户端超时设置为接近 180 秒
• 抓取图片 URL 时添加 content_encoding: "base64"，然后在保存文件前解码 results[0].content