Google 可用历史日期接口

GET /v3/dataforseo_labs/google/available_history

接口说明

通过调用本接口，你可以获取一组可用日期列表，这些日期可用于 /v3/dataforseo_labs/google/domain_metrics_by_categories/live/ 接口中的 first_date 和 second_date 参数。

该接口适合在发起分类维度域名指标对比前，查询平台当前支持的历史时间点，传无效日期。

请求方式

GET https://api.seermartech.cn/v3/dataforseo_labs/google/available_history

计费说明

该接口不收费。

可理解为参考价约 ¥0.0000 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

响应结构

服务端返回 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	请求路径
data	object	本次请求的参数信息
result	array	结果数组

result[] 字段

字段名	类型	说明
date	string	可用日期，可用于 /v3/dataforseo_labs/google/domain_metrics_by_categories/live/ 接口中的日期范围参数，例如 2022-05-16

请求示例

cURL

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

Python

import requests

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

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

print(result)

TypeScript

import axios from "axios";

// 获取可用于分类域名指标对比的历史日期列表
axios({
 method: "get",
 url: "https://api.seermartech.cn/v3/dataforseo_labs/google/available_history",
 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.20220720",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0577 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "dataforseo_labs",
 "function": "available_history",
 "se": "google"
 },
 "result": [
 {
 "date": "2022-05-16"
 }
 ]
 }
 ]
}

使用建议

在调用 /v3/dataforseo_labs/google/domain_metrics_by_categories/live/ 之前，建议使用本接口获取支持的日期列表，再从中选择 first_date 与 second_date，以确保请求成功并获得可比的历史数据。

常见状态判断

• 顶层 status_code = 20000：请求成功
• tasks_error > 0：部分或任务执行失败，需要检查对应任务的 status_code 与 status_message
• cost = 0：本接口未产生费用

实用场景

• 校验历史日期参数：在调用分类维度域名指标接口前获取可选日期，因传无效 first_date、second_date 导致请求失败。
• 构建时间对比分析：基于平台支持的时间点生成“本期 vs 上期”分析任务，提高 SEO 趋势对比的稳定性。
• 驱动前端日期选择器：将返回的可用日期直接用于后台页或 BI 面板的日期下拉组件，减少人工维护。
• 批量生成回溯任务：按可用日期单自动遍历历史周期，批量拉取不同时间段的分类域名表现数据。
• 监控数据覆盖范围：定期检查可用历史日期是否有新增，及时扩展报表的时间跨度和趋势观察窗口。