Google SERP API（同步搜索）

SERP 端点面向「即问即答」的搜索场景：提交查询后服务端阻塞等待并直接把结果返回，与 scraper 的「提交 → 轮询 → 取数」异步模型不同。小任务用它最省事；大任务超时会自动降级为可轮询的 run（见下）。

与 scraper 的三点不同

快速说明

• Base URL：https://api.antsdata.com/v1
• 方法与路径：POST /v1/serp/{platform}/{resource}。当前 platform 仅 google；resource 见下方端点一览。
• 鉴权：请求头 Authorization: Bearer ants_xxx（静态 API Key，与 scraper 同一套）
• Content-Type：application/json
• 提交体：查询字段平铺在顶层，另加两个可选的 run 级字段：
  • recordLimit：本次查询记录上限（省略/0 按可用积分反算）。
  • dataFormat：结果格式，json（默认，直返记录数组）/ csv / html / markdown（后三者返导出文本）。

返回码与响应体

统一信封 { code, message, data }，data 形状随终局分三种：

• 超时降级：大查询在服务端同步窗口内没跑完 → 返 202 + runId，run 继续后台跑，改用轮询：GET /v1/serp/runs/{id}，成功后 GET /v1/serp/runs/{id}/records 取数或 GET /v1/serp/runs/{id}/download?format=json|csv|excel 下载。
• 产物过大：同步直返产物 > 16 MiB 会报错，请改用 GET /v1/serp/runs/{id}/download 取全量。
• 计费：与 scraper 一致，按成功产出的记录条数结算；失败释放不计费（详见认证与错误处理）。

端点一览

Search — 网页搜索

POST /v1/serp/google/search

查询字段（平铺在 body 顶层）：

输出字段（records 每条一条结果）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/serp/google/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bitcoin",
    "searchType": "web",
    "geo_location": "California,United States",
    "host_language": "en",
    "recordLimit": 50
  }'

同步响应（HTTP 200）：

{
  "code": 0,
  "message": "ok",
  "data": {
    "runId": "1287345",
    "status": "succeeded",
    "records": [
      {
        "organic": {
          "pos": 1,
          "pos_overall": 1,
          "title": "Bitcoin - Open source P2P money",
          "url": "https://bitcoin.org/",
          "desc": "Bitcoin is an innovative payment network ..."
        }
      }
    ]
  }
}

Shopping — 购物

POST /v1/serp/google/shopping

查询字段：

输出字段（records.products[] 每条一件商品）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/serp/google/shopping" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "wireless earbuds",
    "gl": "us",
    "hl": "en",
    "minPrice": 50,
    "maxPrice": 300
  }'

News — 新闻

POST /v1/serp/google/news

查询字段：

输出字段（records.articles[] 每条一篇文章）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/serp/google/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI regulation EU",
    "timeRange": "7d",
    "cluster": true,
    "hl": "en",
    "gl": "us"
  }'

Maps — 地图

POST /v1/serp/google/maps

查询字段：

输出字段（records.places[] 每条一个地点）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/serp/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee shop",
    "location": "Manhattan, NY",
    "gl": "us",
    "hl": "en",
    "openNow": false
  }'

Ads-creatives — 广告创意

POST /v1/serp/google/ads-creatives

Google 广告透明度中心（Ads Transparency）的创意列表。拿到的 creative_id / sponsor_id 可作「创意详情」入参。

查询字段：

输出字段（records 每条一条创意）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/serp/google/ads-creatives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "nike.com",
    "regions": ["US"],
    "start_date": "2026-01-01",
    "end_date": "2026-06-30",
    "platform": 1
  }'

Ads-creative-details — 创意详情

POST /v1/serp/google/ads-creative-details

单条创意的曝光 / 花费 / 政治广告披露详情。sponsor_id 与 creative_id 请先从「广告创意」接口获取，勿硬编码。

查询字段：

输出字段（records 每条一条创意详情）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/serp/google/ads-creative-details" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sponsor_id": "AR00040546930815664129",
    "creative_id": "CR12886158981977866241"
  }'

FAQ

Q: SERP 和 /v1/scraper/google/* 有什么区别？

底层是同一套 Google 采集能力，但 SERP（/v1/serp/google/*）是同步直返 + 扁平入参的封装：一次调用直接拿结果，入参不用包 targets 数组、也不用轮询。追求异步批量、webhook 推送时用 /v1/scraper/google/*。

Q: 超时了（返回 202）怎么办？

202 说明查询较大、没在同步窗口内跑完，但 run 已在后台继续。拿返回里的 runId，转为轮询 GET /v1/serp/runs/{id}，到 succeeded 后 GET /v1/serp/runs/{id}/records 取数或 /download 下载。

Q: dataFormat 支持哪些格式？

json（默认，records 直返记录数组）、csv / html / markdown（返 content 导出文本 + format）。

Q: 结果很大取不全？

同步直返上限 16 MiB，超了会报错。改用 GET /v1/serp/runs/{id}/download?format=json|csv|excel 一次拿全量。

Q: 计费方式？

与 scraper 一致，按成功产出的记录条数结算，失败释放不计费。详见认证与错误处理。