SeerMarTech API 文档

主题

Google 历史 SERP 实时查询 ​

POST /v3/dataforseo_labs/google/historical_serps/live

本接口使用 POST /v3/dataforseo_labs/google/historical_serps/live，用于查询指定、地区和语言在历史时间范围的 Google 搜索结果页（SERP）。响应每个月采集到的 SERP、自然结果、广告结果、精选摘要、知识面板、本地结果、图片、购物、新闻、AI Overview 等 SERP 特征及排名变化。

历史数据最长可查询最近 12 个月。

接口信息 ​

http
POST https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live

认证方式 ​

http
Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

调用限制 ​

  • 所有 POST 请求体使用 UTF-8 编码的 JSON。
  • 请求体是 JSON 数组，即使只查询一个任务，也需要使用数组格式。
  • 每个 Live API 请求只能一个任务。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时进行的请求数量最多为 30 个。

计费 ​

本接口按请求计费。示例响应中的 cost 为任务成本，原始示例值 0.0005 美折算后约为 ¥0.0036 / 次，供参考。

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

请求参数 ​

请求体示例：

json
[
  {
    "keyword": "albert einstein",
    "location_code": 2840,
    "language_code": "en",
    "date_from": "2021-08-01",
    "date_to": "2021-10-01"
  }
]
参数类型填说明
keywordstring是查询，最长 700 个字符。参数中的 %## 编码会被解码，字符 + 会被解码为空格。若本身需要使用 %，请编码为 %25；若需要使用 +，请编码为 %2B。
date_fromstring否查询起始日期，格式为 yyyy-mm-dd。未传时，默认查询从当前时间起向前 365 天的数据。可用的最早日期为当前时间前 365 天。
date_tostring否查询结束日期，格式为 yyyy-mm-dd。未传时默认为当天日期。示例：2021-09-01。
location_namestring条件填地区的完整名称。未指定 location_code 时填。location_name 与 location_code 至少指定一个。
location_codeinteger条件填地区唯一编号。未指定 location_name 时填。location_name 与 location_code 至少指定一个。
language_namestring条件填语言完整名称。未指定 language_code 时填。language_name 与 language_code 至少指定一个。
language_codestring条件填语言唯一代码。未指定 language_name 时填。language_name 与 language_code 至少指定一个。
tagstring否自定义任务标识，最长 255 个字符。该值会原样返回在响应任务的 data 对象中，可用于请求和结果。

可通过以下接口查询可用的地区和语言：

http
GET https://api.seermartech.cn/v3/dataforseo_labs/locations_and_languages

常用示例：

text
location_name: United Kingdom
location_code: 2840
language_name: English
language_code: en

响应结构 ​

接口返回 JSON 对象，顶层 tasks 数组。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。成功通常为 20000。
status_messagestring通用状态说明。
timestring请求执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorinteger返回错误的任务数量。
tasksarray任务结果数组。

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger任务状态码，通常在 10000–60000 范围。
status_messagestring任务状态说明。
timestring任务执行耗时。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray请求路径信息。
dataobject请求中提交的任务参数。
resultarray按月份返回的历史 SERP 结果。

结果字段 ​

result 数组中的每个对应一个时间点或月份的 SERP 数据。

字段类型说明
se_typestring搜索引擎类型，通常为 google 或 organic。
keywordstring查询。返回值中的编码字符会被解码。
location_codeinteger地区编号。
language_codestring语言代码。
total_countinteger数据库中与请求的结果总数。
items_countintegeritems 数组中的结果数量。
itemsarray当前日期采集到的历史 SERP 及数据。

历史 SERP 项通常以下通用字段：

字段类型说明
typestringSERP素类型。
se_domainstring搜索引擎域名。
location_codeinteger地区编号。
language_codestring语言代码。
check_urlstring可直接打开的搜索结果页 URL，可用于核验结果准确性。
datetimestring结果采集时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
spellobject/null搜索引擎自动纠错信息。
item_typesarray当前 SERP 中出现的类型。
se_results_countintegerSERP 中结果总数。
items_countinteger当前 SERP素数量。
itemsarraySERP素明细。

spell 自动纠错 ​

当搜索引擎对进行了纠正时，spell 会返回：

字段类型说明
keywordstring自动纠正后的。
typestring纠错类型，可选值为 did_you_mean、showing_results_for、no_results_found_for。

SERP素类型 ​

item_types 和 items[].type 可能以下值：

text
answer_box
carousel
multi_carousel
featured_snippet
google_flights
google_reviews
google_posts
images
jobs
knowledge_graph
local_pack
hotels_pack
map
organic
paid
people_also_ask
related_searches
people_also_search
shopping
top_stories
twitter
video
events
mention_carousel
recipes
top_sights
scholarly_articles
popular_products
podcasts
questions_and_answers
find_results_on
stocks_box
visual_stories
commercial_units
local_services
google_hotels
math_solver
ai_overview

排名与流量字段 ​

自然结果、广告、本地结果、精选摘要、购物结果等可能以下字段：

字段类型说明
rank_groupinteger同类型中的组排名。不同类型之间不参与该排名。
rank_absoluteinteger素在整个 SERP 中的绝对排名。
positionstring素对齐位置，可为 left 或 right。
xpathstring素在 SERP 页面中的 XPath。
domainstring结果域名。
main_domainstring主域名。
relative_urlstring不协议和域名的相对 URL。
titlestring结果标题。
urlstring结果 URL。
descriptionstring结果描述或摘要。
breadcrumbstring面屑路径。
etvfloat预估流量，通常表示该 URL 每月可获得的预估自然流量。一般根据点击率和搜索量计算。
estimated_paid_traffic_costfloat预估付费流量成本，表示通过广告获得相同流量所需的月度费用估算值。
rank_changesobject与前一个月相比的排名变化。即使请求的时间范围不前一个月，也会计算该变化。

rank_changes 排名变化 ​

字段类型说明
previous_rank_absoluteinteger/null上一个月的绝对排名。如果该为新出现，则为 null。
is_newboolean是否为新出现的 SERP素。
is_upboolean排名是否提升。
is_downboolean排名是否下降。

organic 自然结果 ​

字段类型说明
typestring固定为 organic。
titlestring自然结果标题。
urlstring自然结果 URL。
domainstring结果域名。
descriptionstring结果描述。
pre_snippetstring描述前附加的文本。
extended_snippetstring描述后附加的文本。
is_imageboolean是否图片。
is_videoboolean是否视频。
is_featured_snippetboolean是否为精选摘要来源。
is_maliciousboolean是否被标记为恶意结果。
amp_versionboolean是否存在 AMP 版本。
highlightedarray描述中被突出显示的词语。
linksarray/null站点链接。每项通常 type、title、description、url。
about_this_resultobject/null“此结果”面板信息， type、url、source、source_info、source_url、language、location、search_terms 和 related_terms。
ratingobject/null评分信息。
backlinks_infoobject/null结果网站的反向链接信息。
rank_infoobject/null页面和主域名排名信息。

评分对象 rating ​

字段类型说明
rating_typestring评分类型：Max5、Percents 或 CustomMax。
valuefloat评分值。
votes_countinteger评价数量。
rating_maxinteger评分上限。
字段类型说明
referring_domainsinteger引用域名数量，子域名会作为独立域名计算。
referring_main_domainsinteger引用主域名数量。
referring_pagesinteger指向该网站的页面数量。
dofollowintegerDofollow 链接数量。
backlinksinteger反向链接总数 Dofollow 和 Nofollow 链接。
time_updatestring反向链接数据更新时间，UTC 格式。

页面排名信息 rank_info ​

字段类型说明
page_rankinteger页面排名，根据链接数据库中的节点排名方法计算。
main_domain_rankinteger主域名排名。

付费结果通常：

text
se_type
type = paid
rank_group
rank_absolute
position
xpath
title
domain
description
breadcrumb
url
highlighted
extra
description_rows
links
main_domain
relative_url
etv
estimated_paid_traffic_cost
rank_changes

：

  • extra.ad_aclk：广告标识。
  • description_rows：扩展描述，没有时为 null。
  • links：广告站点链接，没有时为 null。
  • 广告链接项通常 type = ad_link_element、title、description、url 和 ad_aclk。

SERP 特征字段 ​

以下均使用通用排名字段：

text
se_type
type
rank_group
rank_absolute
position
xpath

扩展字段如下。

字段类型说明
domainstring精选摘要来源域名。
titlestring结果标题。
featured_titlestring来源页面标题。
descriptionstring摘要。
urlstring来源 URL。
tableobject/null摘要中的表格， table_header 和 table_content。
main_domainstring主域名。
relative_urlstring相对 URL。
etvfloat预估自然流量。
estimated_paid_traffic_costfloat预估付费流量成本。
rank_changesobject排名变化。

answer_box 答案框 ​

：

  • text：答案文本数组。
  • links：链接数组。
  • rank_group、rank_absolute、position、xpath：排名和页面定位信息。
  • carousel.items：轮播项目数组，每项通常 type = carousel_element、title 和 sub_title。
  • multi_carousel.items：多层轮播项目数组，每项通常 type = multi_carousel_element 和 title。
  • multi_carousel_snippets：多层轮播摘要数组，每项 type = multi_carousel_snippet 和 title。

local_pack 本地结果 ​

字段类型说明
titlestring本地商家或地点名称。
descriptionstring商家描述。
domainstring/null域名。
phonestring/null电话号码。
urlstring/nullURL。
is_paidboolean是否为广告。
ratingobject/null评分信息。
main_domainstring主域名。
relative_urlstring相对 URL。
etvfloat预估流量。
estimated_paid_traffic_costfloat预估付费流量成本。
rank_changesobject排名变化。

hotels_pack 与 google_hotels ​

hotels_pack含住宿结果及日期：

  • title
  • date_from
  • date_to
  • items

住宿项目通常：

text
type = hotels_pack_element
title
desription
hotel_identifier
domain
url
is_paid
rating
price

price 对象：

text
current
regular
max_value
currency
is_price_range
displayed_price

google_hotels 主要：

  • hotel_identifier：住宿唯一标识。
  • url：住宿 URL。

knowledge_graph 知识面板 ​

知识面板可能：

text
title
sub_title
description
card_id
url
image_url
logo_url
cid
items

items 中可能出现以下类型：

text
knowledge_graph_images_item
knowledge_graph_description_item
knowledge_graph_row_item
knowledge_graph_list_item
knowledge_graph_carousel_item
knowledge_graph_part_item
knowledge_graph_expanded_item
knowledge_graph_shopping_item

常见字段：

  • title、sub_title、text
  • data_attrid
  • url、domain、image_url
  • rank_group、rank_absolute、position、xpath
  • link： type、title、url、domain、snippet、xpath
  • links：链接数组
  • items：嵌套项目数组
  • expanded_element：展开
  • table：表格对象， table_element、table_header 和 table_content

这两类均可能：

  • rank_group
  • rank_absolute
  • position
  • xpath
  • items

items 通常：

text
type
title

people_also_ask 问题 ​

people_also_ask.items 中通常：

字段类型说明
typestring通常为 people_also_ask_element。
titlestring问题标题。
xpathstring页面 XPath。
expanded_elementarray展开后的答案。

展开可能：

text
type = people_also_ask_expanded_element
featured_title
url
domain
title
description
timestamp
table

images 图片结果 ​

图片模块：

  • title
  • url
  • items
  • related_image_searches

图片项目字段：

text
type = images_element
alt
url
image_url

related_image_searches 中的项目：

text
type = related_image_searches_element
title
alt
url
image_url

shopping、popular_products 与 commercial_units ​

商品类通常：

text
title
items

商品项目可能：

text
type
title
description
url
source
marketplace
marketplace_url
price
rating

价格对象字段：

text
current
regular
max_value
currency
is_price_range
displayed_price

jobs 招聘结果 ​

jobs.items 中的招聘项目可能：

text
type = jobs_element
title
description
author
job_posted_time
timestamp
contract_type
salary
url

top_stories、video、twitter 与 podcasts ​

top_stories.items 常见字段：

text
type = top_stories_element
source
domain
title
date
amp_version
timestamp
url

video.items 常见字段：

text
type = video_element
source
title
timestamp
url

twitter.items 常见字段：

text
type = twitter_element
tweet
date
timestamp
url

podcasts.items 常见字段：

text
type = podcasts_element
title
url
description
timestamp
time_to_play

events、recipes、top_sights 与 scholarly_articles ​

事件项目：

text
type = events_element
title
description
URL

食谱项目：

text
type = recipes_element
title
url
domain
source
description
time
rating

景点项目：

text
type = top_sights_element
title
url
description
rating

学术文章项目：

text
type = scholarly_articles_element
title
url
author
description

google_flights 航班结果 ​

航班模块：

  • title
  • url
  • items

航班项目通常：

text
type = google_flights_element
description
url

google_reviews 与 google_posts ​

google_reviews含：

text
reviews_count
rating
place_id
feature
cid

google_posts含：

text
posts_id
feature
cid

place_id 和 cid 可用于地点或进一步获取评价数据。

map 地图结果 ​

地图通常：

text
title
url
rank_group
rank_absolute
position
xpath

项目可能：

text
type = mention_carousel_element
title
price
rating
mentioned_in

mentioned_in 为来源数组，每项通常：

text
type = link_element
title
snippet
URL

questions_and_answers 问答结果 ​

问答项目可能：

text
type = questions_and_answers_element
url
question_text
answer_text
source
domain

find_results_on ​

项目通常：

text
type = find_results_on_element
title
domain
url
source

stocks_box 股票信息 ​

股票模块：

text
title
source
snippet
price
url
domain
table
graph

graph.items 与 graph.previous_items 中的项目：

text
type = graph_element
date
value

date 使用 ISO 8601 格式：yyyy-mm-ddThh:mm:ss。

visual_stories 视觉 ​

项目通常：

text
type = visual_stories_element
title
url
domain

local_services 本地服务 ​

模块及项目可能：

text
title
url
domain
description
rating
image_url

math_solver 数学解题 ​

数学解题模块：

text
title
result
items
links

解题步骤项目：

text
type = math_solver_expanded_element
title
solution

ai_overview AI Overview ​

AI Overview 可能以下字段：

字段类型说明
typestring固定为 ai_overview。
rank_groupinteger组排名。
rank_absoluteinteger绝对排名。
pageinteger所在搜索结果页码。
positionstring对齐位置，left 或 right。
xpathstring页面 XPath。
asynchronous_ai_overviewboolean是否异步加载。true 表示异步加载，false 表示从缓存加载。
markdownstringAI Overview 的 Markdown。
itemsarrayAI Overview部项目。
linksarray中的网站链接。
imagesarray/null中的图片。
referencesarray生成时引用的网页。
rectangleobject/nullSERP 中的像素坐标和尺寸。未设置 calculate_rectangles=true 时为 null。

AI Overview 项目类型：

text
ai_overview_element
ai_overview_reference
ai_overview_video_element
ai_overview_table_element
ai_overview_expanded_element
ai_overview_expanded_component

引用对象 ai_overview_reference含：

text
source
domain
url
title
text

视频项目可能：

text
position
title
snippet
url
domain
image_url
source
date
timestamp

表格对象：

text
table_header
table_content

展开组件可能：

text
title
text
markdown
images
links
references

rectangle 坐标 ​

当请求中设置 calculate_rectangles 为 true 时，响应可能返回：

字段类型说明
xfloat素左上角的 X 坐标。
yfloat素左上角的 Y 坐标。
widthfloat素宽度，单位为像素。
heightfloat素高度，单位为像素。

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "albert einstein",
      "location_code": 2840,
      "language_code": "en",
      "date_from": "2021-08-01",
      "date_to": "2021-10-01"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live"

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

# 请求体是 JSON 数组
payload = [
    {
        "keyword": "albert einstein",
        "location_name": "United States",
        "language_name": "English",
        "date_from": "2021-08-01",
        "date_to": "2021-10-01",
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败。Code: %s Message: %s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const postArray = [
  {
    keyword: "albert einstein",
    location_code: 2840,
    language_code: "en",
    date_from: "2021-08-01",
    date_to: "2021-10-01",
  },
];

axios({
  method: "post",
  url: "https://api.seermartech.cn/v3/dataforseo_labs/google/historical_serps/live",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  data: postArray,
})
  .then((response) => {
    // 处理接口响应
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应示例 ​

以下示例展示了主要响应层级及型 SERP素。响应可能根据、日期、地区和 Google SERP 布局返回不同的类型。

json
{
  "version": "0.1.20220216",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "23.9825 sec.",
  "cost": 0.0005,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "23.9825 sec.",
      "cost": 0.0005,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "historical_serps",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "historical_serps",
        "se_type": "google",
        "keyword": "albert einstein",
        "language_name": "English",
        "location_code": 2840,
        "date_from": "2021-08-01",
        "date_to": "2021-10-01"
      },
      "result": [
        {
          "keyword": "albert einstein",
          "type": "organic",
          "se_domain": "google.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://www.google.com/search?q=albert%20einstein",
          "datetime": "2021-10-01 03:37:47 +00:00",
          "spell": null,
          "item_types": [
            "organic",
            "featured_snippet",
            "people_also_ask",
            "images",
            "ai_overview"
          ],
          "se_results_count": 2070000000,
          "items_count": 3,
          "items": [
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 1,
              "position": "left",
              "domain": "example.com",
              "title": "示例搜索结果",
              "url": "https://example.com/page",
              "description": "示例结果描述",
              "is_image": false,
              "is_video": false,
              "is_featured_snippet": false,
              "rank_changes": {
                "previous_rank_absolute": 2,
                "is_new": false,
                "is_up": true,
                "is_down": false
              }
            },
            {
              "type": "featured_snippet",
              "rank_group": 1,
              "rank_absolute": 2,
              "position": "left",
              "domain": "example.org",
              "title": "精选摘要示例",
              "featured_title": "来源页面标题",
              "description": "精选摘要",
              "url": "https://example.org/article",
              "table": null
            },
            {
              "type": "ai_overview",
              "rank_group": 1,
              "rank_absolute": 1,
              "page": 1,
              "position": "left",
              "asynchronous_ai_overview": false,
              "markdown": "AI Overview 示例",
              "items": [],
              "links": [],
              "images": [],
              "references": [],
              "rectangle": null
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

请根据以下字段判断请求是否成功：

  • 顶层 status_code
  • 任务级 tasks[].status_code
  • 对应的 status_message

当 status_code 不等于 20000 时，应记录错误码和错误信息，并根据业务需要进行重试、告警或人工处理。完整错误码可参考本平台的错误码文档。

实用场景 ​

  • 追踪月度排名：按月获取目标的自然结果及排名变化，评估 SEO 优化、更新和外链建设的长期效果。
  • 监测 SERP 特征变化：统计精选摘要、People Also Ask、本地、图片、购物和 AI Overview 等的出现，调整结构和富媒体策略。
  • 分析竞争对手可见度：对比多个历史月份中的竞争域名、排名位置、预估流量和排名升降，定位竞争对手增长节点。
  • 复盘算法或更新影响：结合 datetime、rank_changes 和 check_url，分析特定日期前后的排名波动，为 SEO 复盘提供证据。
  • 评估本地与商业搜索机会：针对地区化查询 local_pack、local_services、shopping 和 commercial_units，判断本地获客或电商 SERP 的流量机会。

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

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