数据更新状态

GET /v3/keywords_data/google/adwords_status

接口说明

该接口用于查询：平台搜索广告数据是否已经更新到“上一个自然月”。

通常，平台数据会在每月中旬更新一次。 例如：

• 如果 10 月已经完成更新，则你可以获取到 9 月的真实搜索量、CPC、竞争度等指标；
• 如果 10 月尚未更新，则最新可用数据可能仍停留在 8 月。

该接口适合在批量拉取搜索量、点击成本等指标前，判断最新月份数据是否已经可用。

说明：该接口对应的是历史容能力，广告数据能力已逐步由新版广告数据接口替代。但 /v3/keywords_data/google/adwords_status 路径仍可用于容查询。

请求方式

GET https://api.seermartech.cn/v3/keywords_data/google/adwords_status

计费说明

该接口不收费。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准；通常返回为 0。

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	接口总体状态码
status_message	string	接口总体状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	任务结果数组

建议在接时为异常状态、时、空结果等设计完整的错误处理逻辑。 错误码与状态信息请参考错误码附录。

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，通常范围为 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径
data	object	本次调用的请求数据
result	array	返回结果数组

result[] 字段

字段名	类型	说明
actual_data	boolean	是否已更新到上一个自然月的数据
date_update	string	最近一次数据更新时间，格式如 2020-05-15
last_year_in_monthly_searches	integer	当前可获得搜索量数据的最新年份
last_month_in_monthly_searches	integer	当前可获得搜索量数据的最新月份

actual_data 说明

值	含义
true	当前已可获取上一个自然月的最新数据
false	当前尚无法获取上一个自然月的数据，通常仍需使用更早月份的数据

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/keywords_data/google/adwords_status" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/keywords_data/google/adwords_status"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

async function getAdwordsStatus {
 const response = await axios.get(
 "https://api.seermartech.cn/v3/keywords_data/google/adwords_status",
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
 }
 );

 // 输出返回结果
 console.log(response.data);
}

getAdwordsStatus.catch(console.error);

响应示例

{
 "version": "3.20191128",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1653 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0123 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "keywords_data",
 "google",
 "adwords_status"
 ],
 "data": {
 "api": "keywords_data",
 "function": "adwords_status",
 "se": "google"
 },
 "result": [
 {
 "actual_data": true,
 "date_update": "2020-05-15",
 "last_year_in_monthly_searches": 2020,
 "last_month_in_monthly_searches": 4
 }
 ]
 }
 ]
}

返回结果解读

当返回结果中：

• actual_data = true：表示平台已经完成最近一次月度更新，你可以继续拉取上一个自然月的指标；
• actual_data = false：表示最新月份尚未开放，建议延后抓取，或继续使用更早月份的数据；
• date_update：可用于记录游更新时间，便于建立数据同步日志；
• last_year_in_monthly_searches 与 last_month_in_monthly_searches：可直接确定“当前最晚能拿到哪一个月份”的搜索量数据。

状态码说明

顶层状态码

状态码	说明
20000	请求成功

任务状态码

任务级 status_code 用于表示任务执行。常见成功状态为：

状态码	说明
20000	任务执行成功

如返回非成功状态，请结合 status_message 排查认证、权限、参数或服务异常问题。错误码明细请参考错误码附录。

使用建议

在执行以下操作前，建议调用本接口进行状态确认：

1. 批量抓取月搜索量；
2. 生成月度 SEO 趋势报告；
3. 刷新 CPC、竞争度等广告指标；
4. 触发自动化数据同步任务。

这样可以在平台尚未更新时重复抓取旧数据。

实用场景

• 判断月度数据是否可拉取：在每月固定时间检查是否已更新到上个月，报告使用旧搜索量数据。
• 触发自动同步任务：当 actual_data=true 时自动启动指标抓取，提高数据管道的时效性。
• 校验报表月份完整性：结合 last_year_in_monthly_searches 与 last_month_in_monthly_searches，确认仪表盘展示的月份是否最新。
• 记录平台更新时间：保存 date_update 作为数据审计依据，便于追踪月度流量波动是否由数据源更新时间引起。
• 优化批量采集成本与时机：在大规模拉取搜索量、CPC 前做更新检查，减少无效任务调度。