AdWords 数据更新状态

本接口使用 GET 方法，路径为：

/v3/keywords_data/google/adwords_status

该接口用于查询 Google 是否已经更新上一个月的数据。Google 通常会在每月中旬更新数据。例如，如果 Google 在 10 月更新了数据，则可以获取 9 月的搜索量、每次点击费用（CPC）、竞争度等指标；如果 10 月尚未完成更新，则最新可用数据可能仍为 8 月数据。

> 说明：该接口属于旧版数据接口。对于新的数据业务，建议优使用 Google Ads 接口。

计费说明

本接口不收取调用费用。

如需核对扣费，请以响应头 X-SeerMarTech-Charge-CNY 为准。

请求

请求方法

GET /v3/keywords_data/google/adwords_status

请求地址

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

请求头

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

该接口为 GET 请求，无需请求体。

响应结构

接口返回 JSON 数据，顶层 tasks 数组。每个任务对象中本次调用的状态信息及数据更新状态。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	请求级状态码
status_message	string	请求级提示信息
time	string	请求执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
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 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量
path	array	当前请求的 URL 路径
data	object	本次 API 调用所使用的请求参数
result	array	任务返回结果数组

data 字段

字段	类型	说明
api	string	API 模块名称，值为 keywords_data
function	string	接口名称，值为 adwords_status
se	string	搜索引擎名称，值为 google

result 结果字段

字段	类型	说明
actual_data	boolean	Google 是否已更新上一个月的数据
date_update	string	AdWords 数据最近一次更新日期，格式为 YYYY-MM-DD
last_year_in_monthly_searches	integer	当前可获取搜索量数据的最新年份
last_month_in_monthly_searches	integer	当前可获取搜索量数据的最新月份

actual_data 字段取值

• true：Google 当前已提供上一个月的最新数据。
• false：当前无法提供上一个月的数据，返回的数据可能属于更早月份。

date_update 表示 Google 最近一次更新搜索量、CPC 及指标的日期，例如：

2020-05-15

请求示例

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)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
    # 在此处处理数据更新状态
else:
    print(
        "请求失败。状态码: %s，信息: %s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

import axios from "axios";

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

    if (result.status_code === 20000) {
      console.log(result);
      // 在此处处理数据更新状态
    } else {
      console.error(
        `请求失败。状态码: ${result.status_code}，信息: ${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("网络请求失败:", error.message);
  });

响应示例

{
  "version": "3.20191128",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1653 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 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
        }
      ]
    }
  ]
}

状态码与异常处理

请在业务系统中同时检查顶层 status_code 和任务级 tasks[].status_code：

• 20000：请求或任务处理成功。
• 状态码：表示请求或任务处理异常，应结合对应的 status_message 排查。

建议客户端实现以下异常处理机制：

1. 检查 HTTP 响应状态。
2. 检查顶层 status_code。
3. 检查每个任务的 status_code。
4. 在网络时或临时错误时执行有限次数重试。
5. 记录 id、status_code 和 status_message，便于问题追踪。

实用场景

• 判断数据是否已更新：在生成月度 SEO 报告前确认上月搜索量和 CPC 数据是否可用，使用过期指标。
• 控制数据同步任务：根据 actual_data 自动决定是否启动数据拉取，减少无效的数据处理和重复同步。
• 标记报告数据周期：结合 date_update、last_year_in_monthly_searches 和 last_month_in_monthly_searches，在报表中明确标注指标对应的最新月份。
• 安排月度数据刷新：监控 Google 的月度更新节奏，自动调整分析、竞品研究和预算评估任务的执行时间。
• 校验历史数据完整性：在 SEO 数据仓库中检查当前可用的最新年份和月份，及时发现搜索量数据缺失或滞后的。