Google Scraper 指南：地图、网页搜索、购物、新闻与广告透明度

采集为异步：提交 run → 轮询 → 取数，流程见快速开始；统一信封、run 状态机、计费与错误见认证与错误处理。

快速说明

• Base URL：https://api.antsdata.com/v1
• 鉴权：请求头 Authorization: Bearer ants_xxx（静态 API Key）
• Content-Type：application/json
• 请求体：所有端点均为 POST /v1/scraper/google/<资源>，请求体统一为 { "deliveryMode": "async", "recordLimit": 1000, "targets": [ … ] }；targets[] 每个元素即一次查询（字段见各端点「target 字段」）。

💡 也可用 deliveryMode: "sync" 同步模式（小任务阻塞等终态，超时自动 fallback 转轮询）——详见 快速开始 · 同步模式。

• 提交回执：成功返回 HTTP 201 + Run 对象（含 id、status: "queued"），记下 id。
• 取数：按 id 轮询 GET /v1/scraper/runs/{id} 至 succeeded，再 GET /v1/scraper/runs/{id}/records?page=&pageSize= 分页取记录，或 GET /v1/scraper/runs/{id}/download?format=json|csv|excel 下载。完整端到端流程见快速开始。
• 计费：按成功产出的数据条数计费，失败目标释放冻结、不计费；细节见认证与错误处理。

端点总览

地图搜索（Maps）

POST /v1/scraper/google/maps

采集 Google 地图的地点 / 商家信息，支持关键词搜索、经纬度反查（reverse）与地理编码（geocode）。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "query": "coffee shop", "location": "San Francisco, CA", "resultsLimit": 20 }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

网页搜索（Search）

POST /v1/scraper/google/search

采集 Google 网页搜索的自然结果（organic）。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "query": "best web scraping tools", "geo_location": "California,United States", "host_language": "en" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

购物（Shopping）

POST /v1/scraper/google/shopping

采集 Google Shopping 商品列表。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/shopping" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "query": "wireless earbuds", "gl": "us", "sortBy": "price_asc", "resultsLimit": 30 }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

新闻（News）

POST /v1/scraper/google/news

采集 Google News 结果，支持关键词、头条、主题与媒体多种 feed。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "feedType": "keyword", "query": "artificial intelligence", "timeRange": "7d", "gl": "US" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

广告透明度（Ads Transparency）

采集 Google 广告透明度中心（Ads Transparency Center）：广告主、广告创意及其投放 / 花费 / 曝光信息。典型链路：先用广告联想拿 sponsor_id → 广告创意列出 creative_id → 创意详情看花费 / 曝光区间；广告主查主体信息。

广告联想（Ads Suggestions）

POST /v1/scraper/google/ads-suggestions

按搜索词联想广告主 / 关键词，用于定位 sponsor_id。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-suggestions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "keyword": "nike" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

广告创意（Ads Creatives）

POST /v1/scraper/google/ads-creatives

按广告主或关键词拉取广告创意列表。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-creatives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "advertiser_id": "AR16735076323512287233", "regions": ["US"], "platform": 1, "limit": 100 }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

创意详情（Ads Creative Details）

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

单条创意的完整详情，含花费与曝光区间。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-creative-details" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "sponsor_id": "AR16735076323512287233", "creative_id": "CR12886158981977866241" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

广告主（Ads Advertiser）

POST /v1/scraper/google/ads-advertiser

广告主主体信息。

target 字段（targets[] 每个元素）：

输出字段（取数时每条记录）：

提交示例：

curl -X POST "https://api.antsdata.com/v1/scraper/google/ads-advertiser" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "async",
    "recordLimit": 1000,
    "targets": [
      { "advertiser_id": "AR16735076323512287233" }
    ]
  }'

→ 201 { "id": <run_id>, "status": "queued" }，随后按 id 轮询取数（见快速开始）。

取数与计费

提交任一端点后：

1. 轮询 GET /v1/scraper/runs/{id} 至 status: "succeeded"（建议退避 1s→2s→5s）。
2. GET /v1/scraper/runs/{id}/records?page=1&pageSize=20 分页取记录，每条 items[] 的字段即上文各端点「输出字段」；或 GET /v1/scraper/runs/{id}/download?format=csv 下载整份产物。
3. 计费按成功产出的数据条数结算（run 对象的 chargedCredits）；全部目标失败释放冻结、不计费。

端到端示例与 run 状态机见快速开始与认证与错误处理。

下一步

• 平台指南：TikTok · X · Instagram · Facebook · LinkedIn ·· YouTube · Amazon
• 同步搜索：Google SERP
• 认证与错误处理 — 统一响应信封、run 状态机、计费与错误码

FAQ

Q: 提交后为什么没有直接返回数据？

采集是异步的：提交拿 run id，后台执行，你轮询 id 到 succeeded 再取记录 / 下载。流程见快速开始。

Q: 一次能查多个目标吗？

可以。targets 是数组，一个 run 可含多个查询（如多个搜索词 / 多个广告主），逐目标成败见轮询返回的 tasks[]。

Q: 网页搜索一定有 AI Overview 吗？

不一定。search 端点返回自然结果（organic：pos / title / url / desc 等）；AI Overview 等富媒体区块仅在 Google 展示该话题时才可能出现，不保证有。pos_overall 会体现整页含非 organic 区块的全局排名。

Q: 广告透明度的花费 / 曝光是精确值吗？

不是。Google 官方只披露区间：spend_lower / spend_upper、impressions_lower / impressions_upper，且通常仅政治 / EU 广告披露，普通广告这些字段为 null。本 API 原样返回。

Q: 广告创意的 creative_id 从哪来？

先调广告联想拿 sponsor_id，再调广告创意列出 creative_id，最后用二者查创意详情。请勿硬编码 creative_id。

Q: 采集失败会扣费吗？

不会。全部目标失败释放冻结、不计费；部分成功只按成功产出的条数结算。详见认证与错误处理。

Q: 本页的 Google 和「Google SERP」有什么区别？

本页是 scraper 产品线（/v1/scraper/google/*）：异步 run，入参为 targets[] 数组，提交后轮询取数。若你要的是同步直返搜索结果（扁平入参、一次调用直接拿数据），用 Google SERP（/v1/serp/google/*）。两者端点同名（search / shopping / news / maps / ads-creatives / ads-creative-details），但入参形态与必填项不同：以各自文档为准。