API v3 迁移指南

POST /v3/serp/google/organic/live/regular

**面向当前 API v2 用户的重要说明：**自 2026 年 5 月 5 日起，API v2 将不再提供支持。为确保现有业务持续运行，请迁移至 API v3。本指南将介绍迁移所需的步骤、主要变化及 v2/v3 接口对应。

API v3 通过统一接口结构、标准化错误信息和更简洁的任务流程，提升了 API 的易用性、执行效率和扩展能力。迁移至 v3 需要完成以下四个步骤。

1. 登录新版控制台

API v3 使用独立的账户控制台。请通过本平台官网的登录或 v3 参考文档中的登录控制台。

登录后，请使用 v3 API 专用的访问凭据进行接口认证。认证示例：

http

Authorization: Bearer smt_live_YOUR_KEY

2. 更新代码示例

API v3 继续使用 REST 架构和 HTTP 协议，因此可以接几乎所有主流编程语言。

请根据项目技术栈更新以下：

API 基础地址：https://api.seermartech.cn
认证方式：使用 Bearer Token
请求体：POST 请求统一使用 JSON 数组格式，即 [{ ... }]
接口路径： v3 的资源、搜索引擎、数据类型和操作组织
响应处理：适 v3 的标准化状态码、错误码和响应结构

示例：

bash

curl -X POST 'https://api.seermartech.cn/v3/serp/google/organic/live/regular' \
  -H 'Authorization: Bearer smt_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "keyword": "seo tools",
      "location_code": 2840,
      "language_code": "en",
      "device": "desktop",
      "os": "windows"
    }
  ]'

3. 更新业务代码

v3 并非简单的增量升级。迁移时通常需要调整接口路径、请求参数、任务处理流程和响应解析逻辑。

建议在正式规划迁移前，重点检查以下差异：

v2 与 v3 的接口路径不同；
v3 将资源类型、搜索引擎和操作类型直接体现在 URL 中；
POST 请求参数会保留在响应的 data 数组中；
可通过 tag 自定义任务标识，便于将提交的任务与返回结果；
错误码和状态码已重新标准化；
部分 v2 接口已废弃，并提供了 v3 替代方案或迁移建议；
SERP、数据、数据实验室、评论和商品数据接口均采用新的任务模型。

4. 测试并逐步切换

首次登录新版账户后，账户通常会获得一笔用于测试 API v3 的等值测试额度。

迁移期间还可以使用 Sandbox 功能进行测试，以验证：

请求参数是否符合 v3 规范；
接口路径是否正确；
任务提交、状态查询和结果获取流程是否正常；
响应字段是否能被现有系统正确解析；
错误重试和异常处理逻辑是否符合预期。

完成测试并准备切换到 v3 后，如果 v2 账户仍有余额，可联系技术支持申请将余额转移至新的 v3 账户，因迁移造成资金损失。

涉及计费的接口，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

开发需要的主要改进

改进项	说明
统一错误码、状态码和错误消息	v3 使用标准化的错误与状态码集合，便于统一处理接口异常。
更晰的 API URL 结构	接口 URL 直接体现核心资源、搜索引擎、数据类型和操作类型。
更简单的任务标识	POST 请求中提交的参数会在响应的 `data` 数组中返回；还可以使用自定义 `tag` 将任务与结果进行匹。
新的计费模型	接口价格进行了调整，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。

v3 的新概念

概念	所属 API	说明
通过 SERP API 获取网站排名	SERP API	可以通过筛选 SERP 结果，或使用 `target` 字段获取指定网站的排名。
GET 请求中的 SERP 功能	SERP API	账户对 POST 请求计费。对 Organic、Advanced 和 HTML 结果接口发送 GET 请求时，可以获取同一 SERP 的三种格式。
更多搜索引擎类型	SERP API	支持 Google Organic、Google Maps、Google News、Google Images 等；支持 Bing Organic、Bing Local Pack 和 Yahoo Organic。
设备与操作系统	SERP API	`desktop` 设备可使用 `windows` 和 `macos`；`mobile` 设备可使用 `android` 和 `ios`。
地理位置坐标	SERP API、Keywords Data API	可通过 `location_coordinate` 字段指定 GPS 坐标，获取特定位置的数据。
支持批量查询的搜索量接口	Keywords Data API	单次最多可查询 700 个；查询 1 个或 700 个的价格相同。

v2/v3 核心接口对应

以下表格列出常用 v2 接口与 v3 接口的对应。迁移时，请将现有 v2 请求替换为对应的 v3 路径。

SERP API

v2 功能	v3 对应接口
Live SERP	Live Google Organic SERP Regular：`/v3/serp/google/organic/live/regular/`
创建 SERP 任务	创建 Google Organic SERP 任务：`/v3/serp/google/organic/task_post/`
获取已完成 SERP 任务	获取 Organic SERP 已完成任务：`/v3/serp/google/organic/tasks_ready/`
按 `task_id` 获取 SERP 结果	获取 Google Organic SERP 结果：`/v3/serp/google/organic/task_get/regular/`
创建 SERP HTML 任务	创建 Google Organic SERP 任务：`/v3/serp/google/organic/task_post/`
获取已完成 SERP HTML 任务	获取 Organic SERP 已完成任务：`/v3/serp/google/organic/tasks_ready/`
按 `task_id` 获取 SERP HTML 结果	获取 Google Organic HTML 结果：`/v3/serp/google/organic/task_get/html/`
Live Extra SERP	Live Google Organic SERP Advanced：`/v3/serp/google/organic/live/advanced/`
创建 Extra SERP 任务	创建 Google Organic SERP 任务：`/v3/serp/google/organic/task_post/`
获取已完成 Extra SERP 任务	获取 Organic SERP 已完成任务：`/v3/serp/google/organic/tasks_ready/`
按 `task_id` 获取 Extra SERP 结果	获取 Google Organic SERP Advanced 结果：`/v3/serp/google/organic/task_get/advanced/`
创建 Google Images 任务	创建 Google Images SERP 任务：`/v3/serp/google/images/task_post/`
获取已完成 Google Images 任务	获取 Images SERP 已完成任务：`/v3/serp/google/images/tasks_ready/`
按 `task_id` 获取 Google Images 结果	获取 Google Images SERP 结果：`/v3/serp/google/images/task_get/advanced/`
获取搜索位置列表	获取 Google SERP 位置列表：`/v3/serp/google/locations/`

Keywords Data API

v2 功能	v3 对应接口
批量搜索量：实时查询	实时创建 `Search Volume` 任务：`/v3/keywords_data/google_ads/search_volume/live/`
批量搜索量：创建任务	创建 `Search Volume` 任务：`/v3/keywords_data/google_ads/search_volume/task_post/`
批量搜索量：获取已完成任务	获取 `Search Volume` 已完成任务：`/v3/keywords_data/google_ads/search_volume/tasks_ready/`
批量搜索量：按 `task_id` 获取结果	获取 `Search Volume` 结果：`/v3/keywords_data/google_ads/search_volume/task_get/`
按域名获取：实时查询	实时创建 `Keywords For Site` 任务：`/v3/keywords_data/google_ads/keywords_for_site/live/`
按域名获取：创建任务	创建 `Keywords For Site` 任务：`/v3/keywords_data/google_ads/keywords_for_site/task_post/`
按域名获取：获取已完成任务	获取 `Keywords For Site` 已完成任务：`/v3/keywords_data/google_ads/keywords_for_site/tasks_ready/`
按域名获取：按 `task_id` 获取结果	获取 `Keywords For Site` 结果：`/v3/keywords_data/google_ads/keywords_for_site/task_get/`
按获取：实时查询	实时创建 `Keywords For Keywords` 任务：`/v3/keywords_data/google_ads/keywords_for_keywords/live/`
按获取：创建任务	创建 `Keywords For Keywords` 任务：`/v3/keywords_data/google_ads/keywords_for_keywords/task_post/`
按获取：获取已完成任务	获取 `Keywords For Keywords` 已完成任务：`/v3/keywords_data/google_ads/keywords_for_keywords/tasks_ready/`
按获取：按 `task_id` 获取结果	获取 `Keywords For Keywords` 结果：`/v3/keywords_data/google_ads/keywords_for_keywords/task_get/`
按获取广告流量：实时查询	实时创建 `Ads Traffic By Keywords` 任务：`/v3/keywords_data/google_ads/ad_traffic_by_keywords/live/`
按获取广告流量：创建任务	创建 `Ads Traffic By Keywords` 任务：`/v3/keywords_data/google_ads/ad_traffic_by_keywords/task_post/`
按获取广告流量：获取已完成任务	获取 `Ads Traffic By Keywords` 已完成任务：`/v3/keywords_data/google_ads/ad_traffic_by_keywords/tasks_ready/`
按获取广告流量：按 `task_id` 获取结果	获取 `Ads Traffic By Keywords` 结果：`/v3/keywords_data/google_ads/ad_traffic_by_keywords/task_get/`

本平台 Labs API

v2 功能	v3 对应接口
获取	实时创建 `Related Keywords` 任务：`/v3/dataforseo_labs/google/related_keywords/live/`
获取相似	实时创建 `Keyword Suggestions` 任务：`/v3/dataforseo_labs/google/keyword_suggestions/live/`
获取排名	实时创建 `Ranked Keywords` 任务：`/v3/dataforseo_labs/google/ranked_keywords/live/`
按词组获取	实时创建 `Keyword Ideas` 任务：`/v3/dataforseo_labs/google/keyword_ideas/live/`
获取 SERP 竞争对手	实时创建 `SERP Competitors` 任务：`/v3/dataforseo_labs/google/serp_competitors/live/`
获取页面	实时创建 `Relevant Pages` 任务：`/v3/dataforseo_labs/google/relevant_pages/live/`
获取子域名	实时创建 `Subdomains` 任务：`/v3/dataforseo_labs/google/subdomains/live/`
获取竞争对手域名	实时创建 `Competitors Domain` 任务：`/v3/dataforseo_labs/google/competitors_domain/live/`
获取域名所属分类	实时创建 `Categories For Domain` 任务：`/v3/dataforseo_labs/google/categories_for_domain/live/`
按分类获取	实时创建 `Keywords For Categories` 任务：`/v3/dataforseo_labs/google/keywords_for_categories/live/`
获取域名交集	实时创建 `Domain Intersection` 任务：`/v3/dataforseo_labs/google/domain_intersection/live/`
获取的位置和语言列表	`/v3/dataforseo_labs/locations_and_languages/`

Reviews API

v2 功能	v3 对应接口
创建 Google Reviews 任务	`/v3/reviews/google/task_post/`
获取 Google Reviews 已完成任务	`/v3/reviews/google/tasks_ready/`
按 `task_id` 获取 Google Reviews 结果	`/v3/reviews/google/task_get/`

Merchant API

v2 功能	v3 对应接口
创建 Google Shopping 商品任务	`/v3/merchant/google/products/task_post/`
获取 Google Shopping 商品已完成任务	`/v3/merchant/google/products/tasks_ready/`
按 `task_id` 获取 Google Shopping 商品结果	`/v3/merchant/google/products/task_get/advanced/`
创建 Google Shopping 商品 HTML 任务	`/v3/merchant/google/products/task_post/`
获取 Google Shopping 商品 HTML 已完成任务	`/v3/merchant/google/products/tasks_ready/`
按 `task_id` 获取 Google Shopping 商品 HTML 结果	`/v3/merchant/google/products/task_get/html/`
创建 Google Shopping 卖家任务	`/v3/merchant/google/sellers/task_post/`
获取 Google Shopping 卖家已完成任务	`/v3/merchant/google/sellers/tasks_ready/`
按 `task_id` 获取 Google Shopping 卖家结果	`/v3/merchant/google/sellers/task_get/advanced/`
创建 Google Shopping 商品规格任务	`/v3/merchant/google/product_spec/task_post/`
获取 Google Shopping 商品规格已完成任务	`/v3/merchant/google/product_spec/tasks_ready/`
按 `task_id` 获取 Google Shopping 商品规格结果	`/v3/merchant/google/product_spec/task_get/advanced/`
获取 Google Shopping 卖家广告 URL	`/v3/merchant/google/sellers/ad_url/`
创建 Amazon 商品任务	`/v3/merchant/amazon/products/task_post/`
获取 Amazon 商品已完成任务	`/v3/merchant/amazon/products/tasks_ready/`
按 `task_id` 获取 Amazon 商品结果	`/v3/merchant/amazon/products/task_get/advanced/`
创建 Amazon 商品 HTML 任务	`/v3/merchant/amazon/products/task_post/`
获取 Amazon 商品 HTML 已完成任务	`/v3/merchant/amazon/products/tasks_ready/`
按 `task_id` 获取 Amazon 商品 HTML 结果	`/v3/merchant/amazon/products/task_get/html/`
创建 Amazon ASIN 任务	`/v3/merchant/amazon/asin/task_post/`
获取 Amazon ASIN 已完成任务	`/v3/merchant/amazon/asin/tasks_ready/`
按 `task_id` 获取 Amazon ASIN 结果	`/v3/merchant/amazon/asin/task_get/advanced/`

已废弃的 v2 接口

API v3 已覆盖 v2 的大部分功能，但以下 v2 接口已废弃。迁移时，请从代码中移除这些接口，或根据业务需求使用对应的替代方案。

SERP API：搜索引擎列表

已废弃路径：

text

https://api.seermartech.cn/v2/cmn_se
https://api.seermartech.cn/v2/cmn_se/$country_iso_code

v3 会根据 POST 请求中的位置和语言参数自动确定搜索引擎域名，因此无需再单独获取搜索引擎列表。

搜索量

已废弃路径：

text

https://api.seermartech.cn/v2/kwrd_sv
https://api.seermartech.cn/v2/kwrd_sv_tasks_post
https://api.seermartech.cn/v2/kwrd_sv_tasks_get
https://api.seermartech.cn/v2/kwrd_sv_tasks_get/$task_id

迁移方式：使用 Google Search Volume 接口。v3 支持单次查询最多 700 个：

text

/v3/keywords_data/google_ads/search_volume/task_post/

按平台获取广告流量

已废弃路径：

text

https://api.seermartech.cn/v2/kwrd_ad_traffic_by_platforms
https://api.seermartech.cn/v2/kwrd_ad_traffic_by_platforms_tasks_post
https://api.seermartech.cn/v2/kwrd_ad_traffic_by_platforms_tasks_get
https://api.seermartech.cn/v2/kwrd_ad_traffic_by_platforms_tasks_get/$task_id

废弃原因：Google Ads API 不再支持按平台获取数据。

替代方案：当前暂无等效替代接口。

按分类获取

已废弃路径：

text

https://api.seermartech.cn/v2/kwrd_for_category
https://api.seermartech.cn/v2/kwrd_for_category_tasks_post
https://api.seermartech.cn/v2/kwrd_for_category_tasks_get
https://api.seermartech.cn/v2/kwrd_for_category_tasks_get/$task_id

废弃原因：Google Ads API 不支持分类维度。

替代接口：

text

/v3/dataforseo_labs/google/keywords_for_categories/live/

迁移检查单

[ ] 创建或启用 API v3 账户。
[ ] 将 API 基础地址替换为 https://api.seermartech.cn。
[ ] 将认证方式改为 Bearer smt_live_YOUR_KEY。
[ ] 将 POST 请求体改为 JSON 数组格式：[{ ... }]。
[ ] 根据 v2/v3 对应表替换接口路径。
[ ] 更新任务提交、任务状态查询和结果获取逻辑。
[ ] 适 v3 的错误码、状态码和响应结构。
[ ] 检查 task_id、tag 及 data 字段的处理方式。
[ ] 使用 Sandbox 或测试额度完成联调。
[ ] 在正式切换后，通过响应头 X-SeerMarTech-Charge-CNY 核对扣费。
[ ] 如 v2 账户仍有余额，联系技术支持申请余额转移。

实用场景

迁移现有排名监控系统至 /v3/serp/google/organic/，降低 v2 停止服务对排名、竞品排名和 SERP 特征监控的影响。
批量替换搜索量接口为 /v3/keywords_data/google_ads/search_volume/，一次处理最多 700 个，提升库更新效率。
重构异步任务队列，使用 task_post、tasks_ready 和 task_get 组合处理大规模 SERP 或数据，提升批量任务的稳定性。
统一处理v3 标准错误码和 tag 任务标识，准确定位失败任务并将返回结果到客户、项目或分组。
核对响应头 X-SeerMarTech-Charge-CNY 中的扣费，在 SEO 报告、客户账单和成本核算中实现人民币级别的用量追踪。

API v3 迁移指南 ​

1. 登录新版控制台 ​

2. 更新代码示例 ​

3. 更新业务代码 ​

4. 测试并逐步切换 ​

开发需要的主要改进 ​

v3 的新概念 ​

v2/v3 核心接口对应 ​

SERP API ​

Keywords Data API ​

本平台 Labs API ​

Reviews API ​

Merchant API ​

已废弃的 v2 接口 ​

SERP API：搜索引擎列表 ​

搜索量 ​

推荐 ​

按平台获取广告流量 ​

按分类获取 ​

迁移检查单 ​

实用场景 ​

API v3 迁移指南

1. 登录新版控制台

2. 更新代码示例

3. 更新业务代码

4. 测试并逐步切换

开发需要的主要改进

v3 的新概念

v2/v3 核心接口对应

SERP API

Keywords Data API

本平台 Labs API

Reviews API

Merchant API

已废弃的 v2 接口

SERP API：搜索引擎列表

搜索量

推荐

按平台获取广告流量

按分类获取

迁移检查单

实用场景