Google Ads 数据更新状态

接口说明

调用该接口可用于判断：Google 是否已经更新“上一个月”的数据。

通常，Google 会在每月中旬更新指标数据。 例如：

• 如果 Google 在 10 月完成更新，则你可以获取到 9 月的搜索量、点击单价（CPC）、竞争度等指标；
• 如果 10 月尚未更新，则当前最新可用的数据通常仍停留在 8 月。

该接口适合在批量拉取 Google Ads 指标前，判断最新月份数据是否已经可用。

接口地址

GET https://api.seermartech.cn/v3/keywords_data/google_ads/status

计费说明

本接口调用，不产生费用。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

返回结构

接口返回 JSON 数据，顶层 tasks 数组，每个任务中本次请求的结果信息。

顶层字段

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

建议在接时对异常状态和错误返回建立完整处理机制。

tasks 数组字段

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

result 数组字段

字段名	类型	说明
actual_data	boolean	是否已可获取上一个月的最新数据。true 表示 Google 已完成更新；false 表示上一个月的数据暂不可用
date_update	string	Google Ads 数据最近一次更新时间，表示搜索量、CPC 等指标最近更新的日期。示例：2020-05-15
last_year_in_monthly_searches	integer	当前可用月搜索量数据对应的最新年份
last_month_in_monthly_searches	integer	当前可用月搜索量数据对应的最新月份

返回逻辑说明

• 当 actual_data = true 时，表示本平台当前可提供“上一个月”的 Google Ads 指标数据；
• 当 actual_data = false 时，表示 Google 尚未完成该月份更新，本接口暂时无法提供上一个月的数据；
• 可结合 last_year_in_monthly_searches 和 last_month_in_monthly_searches，精确判断当前最新可分析的数据月份。

请求示例

cURL

curl --location --request GET "https://api.seermartech.cn/v3/keywords_data/google_ads/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_ads/status"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

# 可根据状态码判断请求是否成功
if result.get("status_code") == 20000:
 print(result)
else:
 print(f"error. Code: {result.get('status_code')} Message: {result.get('status_message')}")

TypeScript

import axios from "axios";

axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/keywords_data/google_ads/status",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
}).then((response) => {
 // 返回结果
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

响应示例

{
 "version": "0.1.20210917",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0881 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "8f4b7f4e-6c8d-4c98-9d08-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0201 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "keywords_data",
 "google_ads",
 "status"
 ],
 "data": {
 "api": "keywords_data",
 "function": "status",
 "se": "google_ads"
 },
 "result": [
 {
 "actual_data": true,
 "date_update": "2020-05-15",
 "last_year_in_monthly_searches": 2020,
 "last_month_in_monthly_searches": 4
 }
 ]
 }
 ]
}

响应字段解读示例

若响应结果为：

• actual_data: true
• date_update: 2020-05-15
• last_year_in_monthly_searches: 2020
• last_month_in_monthly_searches: 4

则表示：

• Google 已完成最近一次月度数据更新；
• 当前最新可用的月搜索量数据为 2020 年 4 月；
• 此时可以继续调用指标接口，获取该月份的搜索量、CPC、竞争度等数据。

常见状态码

状态码	说明
20000	请求成功
40000-60000	请求参数、认证、额或服务端处理异常，详见 /v3/appendix/errors

使用建议

在依赖 Google Ads 月度搜索量数据的业务中，建议调用本接口做“数据更新探测”，再决定是否执行后续批量任务。这可以：

• 拉取到非预期月份的数据；
• 在更新前重复跑数；
• 月报、环比分析出现数据时间错位。

实用场景

• 判断月度数据是否可用：在生成月报前确认上个月数据是否已更新，使用未更新月份导致报告失真。
• 控制批量采集任务触发时机：在 actual_data=true 后再启动搜索量、CPC、竞争度批量拉取，减少无效请求和重复计算。
• 校验数据仓库更新时间：将 date_update 与库时间对比，及时发现指标表是否需要刷新。
• 驱动自动化报表流程：把该接口作为月中自动任务的前置开，只有数据更新后才继续生成 SEO/投放分析报表。
• 识别分析月份边界：结合 last_year_in_monthly_searches 与 last_month_in_monthly_searches，准确界定当前可分析的最新月份，环比、同比口径错误。