SeerMarTech API 文档

主题

面向 AI 的优化 API 响应 ​

本功能通过在接口路径末尾追加 .ai，返回更适合大语言模型（LLM）和 AI 应用处理的精简 JSON 响应。支持的主接口契约如下：

  • POST https://api.seermartech.cn/v3/$path.ai
  • GET https://api.seermartech.cn/v3/$path/$id.ai

，POST 请求体使用 JSON 数组格式：[{ ... }]。

响应特性 ​

与标准 API 响应相比，AI 优化响应以下特点：

  • 服务状态信息保留三个字段：id、status_code 和 status_message。
  • items 数组会移除值为空、null 或 false 的字段。
  • float 类型的数值最多保留三位小数。
  • 移除 position 和 xpath 字段。
  • monthly_searches 对象改为以下格式：
json
{
  "2025-03": 201000,
  "2025-04": 201000
}
  • 对于任务设置中支持 depth 和/或 limit 参数的接口，如果请求中未指定，这些参数默认设置为 10。
  • Location 接口在使用默认路径时返回带有默认 URL 的国家，例如：
text
/locations.ai

如需获取某个国家下的城市，需要在路径中追加国家代码，例如：

text
/locations/US.ai

支持的接口 ​

AI 优化响应适用于所有 Live 接口和 Task GET 接口。

，以下接口通常更适合使用 AI 优化响应：

  • SERP API
  • 本平台 Labs API
  • 返回结构较复杂、需要交由 LLM 或 AI 应用处理的接口

容路径：

  • /v3/serp/
  • /v3/dataforseo_labs/
  • /v3/keywords_data/dataforseo_trends/

计费说明 ​

使用 AI 优化响应不收取额外费用，对应接口的正常规则计费。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

动态路径参数 ​

参数类型说明
pathstring接口路径。填写需要调用的接口路径。示例：_serp/google/organic/live/regular_
idstring任务标识符。用于 Task GET 接口的唯一任务 ID。示例：05281810-1535-0121-0000-014aadae6b3a

AI 优化响应结构 ​

接口服务器会返回 JSON 编码的 AI 优化响应数组顶层字段如下：

字段类型说明
idstring任务标识符，采用 UUID 格式表示任务在系统中的唯一 ID。
status_codeinteger通用状态码。完整状态码列表请参考错误码文档。建议客户端针对异常和错误状态设计专门的处理机制。
status_messagestring通用提示信息。
itemsarray与当前任务的数据项数组。

请求示例 ​

以下示例调用 Google Organic Live Regular SERP 接口，并返回 AI 优化响应。

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "language_code": "en",
      "location_code": 2840,
      "keyword": "albert einstein"
    }
  ]'

TypeScript ​

typescript
import axios from "axios";

axios({
  method: "post",
  url: "https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  data: [
    {
      language_code: "en",
      location_code: 2840,
      keyword: "albert einstein",
    },
  ],
})
  .then((response) => {
    // 处理 AI 优化响应
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error.response?.data || error.message);
  });

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# POST 请求体是 JSON 数组
post_data = [
    {
        "language_code": "en",
        "location_code": 2840,
        "keyword": "albert einstein",
    }
]

response = requests.post(url, headers=headers, json=post_data)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败。状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

PHP ​

php
<?php

$url = 'https://api.seermartech.cn/v3/serp/google/organic/live/regular.ai';

$postData = [
    [
        'language_code' => 'en',
        'location_code' => 2840,
        'keyword' => 'albert einstein',
    ],
];

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer smt_live_YOUR_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($postData, JSON_UNESCAPED_UNICODE),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

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

curl_close($ch);

C# ​

csharp
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class Demo
{
    public static async Task Main()
    {
        using var httpClient = new HttpClient
        {
            BaseAddress = new Uri("https://api.seermartech.cn/")
        };

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

        // POST 请求体是 JSON 数组
        var postData = new[]
        {
            new
            {
                language_code = "en",
                location_code = 2840,
                keyword = "albert einstein"
            }
        };

        var json = JsonSerializer.Serialize(postData);
        using var content = new StringContent(
            json,
            Encoding.UTF8,
            "application/json"
        );

        var response = await httpClient.PostAsync(
            "/v3/serp/google/organic/live/regular.ai",
            content
        );

        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

响应示例 ​

以下为 Google Organic Regular SERP 接口的 AI 优化响应示例：

json
{
  "id": "05281810-1535-0121-0000-014aadae6b3a",
  "status_code": 20000,
  "status_message": "Ok.",
  "items": []
}

错误处理 ​

客户端应重点检查以下字段：

  • status_code：判断请求是否成功以及错误类型。
  • status_message：获取错误或状态说明。
  • HTTP 状态码：判断网络层或网层是否发生异常。

当 status_code 不等于成功状态码 20000 时，建议记录任务 ID、状态码和状态消息，并根据业务需要执行重试、告警或人工排查。

实用场景 ​

  • 压缩 SERP 结果并提交给 LLM 分析：减少无效字段和响应体积，降低上下文占用与模型处理成本。
  • 批量生成 SEO 搜索结果摘要：使用精简后的 items 数据提取排名、标题和摘要信息，提高分析效率。
  • 构建趋势分析流程：将 monthly_searches 的日期键值结构直接转换为图表或趋势数据，简化数据洗。
  • 获取指定国家或城市的可用位置数据：通过 /locations.ai 或 /locations/US.ai 获取适合 AI 应用消费的地点列表。
  • 优化自动化 SEO 任务监控：读取 id、status_code 和 status_message，快速判断任务状态并触发后续流程。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API