Google Ads 数据状态

GET /v3/keywords_data/google_ads/status

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

/v3/keywords_data/google_ads/status

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

计费说明

本接口不收取调用费用。

请求

请求方法

http

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

本接口无需请求体。

请求头

http

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

响应

接口返回 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	结果数据数组

> 建议在业务系统中实现完善的异常和错误处理逻辑。

`result` 字段

字段	类型	说明
`actual_data`	boolean	是否已更新上个月的数据。`true` 表示当前可提供上个月的最新数据；`false` 表示暂时无法提供上个月的数据
`date_update`	string	Google Ads 数据最近一次更新日期，表示搜索量、CPC 及指标的最新更新时间，格式为 `YYYY-MM-DD`，例如 `2020-05-15`
`last_year_in_monthly_searches`	integer	当前可用搜索量数据的最新年份
`last_month_in_monthly_searches`	integer	当前可用搜索量数据的最新月份，取值范围为 `1` 至 `12`

请求示例

cURL

bash

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"

PHP

php

<?php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.seermartech.cn/v3/keywords_data/google_ads/status',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    echo '请求失败：' . curl_error($ch);
} else {
    $result = json_decode($response, true);

    if (($result['status_code'] ?? null) === 20000) {
        // 处理 Google Ads 数据状态
        print_r($result);
    } else {
        echo '错误：' .
            ($result['status_code'] ?? 'unknown') . ' ' .
            ($result['status_message'] ?? '');
    }
}

curl_close($ch);

TypeScript

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) => {
    const result = response.data;

    if (result.status_code === 20000) {
      // 处理 Google Ads 数据状态
      console.log(result);
    } else {
      console.error(
        `错误：${result.status_code} ${result.status_message}`,
      );
    }
  })
  .catch((error) => {
    console.error('请求失败：', error);
  });

Python

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:
    # 处理 Google Ads 数据状态
    print(result)
else:
    print(
        "错误：{} {}".format(
            result.get("status_code"),
            result.get("status_message"),
        )
    )

C#

csharp

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public static class Examples
{
    public static async Task GetGoogleAdsStatus()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue(
                "Bearer",
                "smt_live_YOUR_KEY"
            );

        var response = await httpClient.GetAsync(
            "https://api.seermartech.cn/v3/keywords_data/google_ads/status"
        );

        var content = await response.Content.ReadAsStringAsync();

        if (response.IsSuccessStatusCode)
        {
            // 处理返回的 Google Ads 数据状态
            Console.WriteLine(content);
        }
        else
        {
            Console.WriteLine(
                $"HTTP 请求失败：{(int)response.StatusCode} {content}"
            );
        }
    }
}

响应示例

json

{
  "version": "0.1.20210917",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0881 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "5f2c3c8e-7f35-4dfd-8f5e-123456789abc",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0412 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
        }
      ]
    }
  ]
}

实用场景

判断数据是否完成月度更新，使用过期搜索量和 CPC 指标制定投放或 SEO 策略。
确定当前可用的最新数据月份，为报告标注数据时间范围，提升分析结果的可信度。
触发月度数据同步任务，在 actual_data 为 true 时拉取或刷新指标，减少无效处理。
监控 Google Ads 数据更新周期，结合 date_update 识别数据延迟，并及时调整业务报表发布时间。
校验 SEO 数据仓库的数据新鲜度，通过最新年份和月份字段发现搜索量数据是否落后。

Google Ads 数据状态 ​

计费说明 ​

请求 ​

请求方法 ​

请求头 ​

响应 ​

顶层响应字段 ​

tasks 字段 ​

result 字段 ​

请求示例 ​

cURL ​

PHP ​

TypeScript ​

Python ​

C# ​

响应示例 ​

实用场景 ​