Google 排名（实时）

POST /v3/dataforseo_labs/google/ranked_keywords/live

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

/v3/dataforseo_labs/google/ranked_keywords/live

用于查询指定域名、子域名或网页当前排名的，并返回排名、搜索结果页、月均搜索量、流量估算、搜索意图、反向链接及排名变化等数据。

数据通常每周更新，最新更新时间可通过 /v3/dataforseo_labs/status/ 查询。

接口信息

请求方法：POST
请求地址：https://api.seermartech.cn/v3/dataforseo_labs/google/ranked_keywords/live
请求格式：JSON，UTF-8 编码
请求体格式：JSON 数组，每次 Live API 请求只能 1 个任务
并发限制：最多同时发送 30 个请求平台限流以认证说明中的 30/60/120 次/分钟规则为准/分钟
单次任务结果数：默认 100，最多 1000

计费说明

每个请求按任务计费。启用 include_clickstream_data 后，该请求按标准价格的 2 倍计费。

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

请求参数

请求体是数组，数组中的每个对象代表一个任务。

参数	类型	填	说明
`target`	string	是	查询目标，可以是域名、子域名或网页 URL。域名不得 `https://` 或 `www.`；子域名不得 `https://`；网页 URL须 `https://` 或 `www.`。如果网页 URL 未协议或 `www.`，接口会按整个域名查询。
`location_name`	string	否	地理位置名称，例如 `United Kingdom`。与 `location_code` 二选一。省略时返回所有可用地区的数据。
`location_code`	integer	否	地理位置代码，例如 `2840`。与 `location_name` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。
`language_name`	string	否	语言名称，例如 `English`。与 `language_code` 二选一。省略时返回所有可用语言的数据。
`language_code`	string	否	语言代码，例如 `en`。与 `language_name` 二选一。可通过 `/v3/dataforseo_labs/locations_and_languages` 获取。
`ignore_synonyms`	boolean	否	是否排除高度相似的。设为 `true` 时返回核心。默认值：`false`。
`item_types`	array	否	指定需要返回的搜索结果类型。结果会优按数组中的第一种类型排序。未在该数组中的结果类型不能用于筛选或排序。
`include_clickstream_data`	boolean	否	是否返回点击流指标。设为 `true` 时，响应会增加点击流搜索量、点击流估算流量及性别、年龄分布等字段。默认值：`false`。
`limit`	integer	否	返回的最大数量。默认值：`100`，最大值：`1000`。
`offset`	integer	否	结果偏移量。默认值：`0`。例如设置为 `10`，将跳过前 10 条结果。
`load_rank_absolute`	boolean	否	是否返回按 `rank_absolute` 统计的排名分布。设为 `true` 时，响应 `metrics_absolute`。默认值：`false`。
`historical_serp_mode`	string	否	历史排名筛选模式。可选值：`live`、`lost`、`all`。默认值：`live`。
`filters`	array	否	结果筛选条件，最多 8 个。多个条件之间使用 `and` 或 `or`。
`order_by`	array	否	结果排序规则。最多设置 3 条规则，使用 `asc` 或 `desc` 指定升序或降序。
`tag`	string	否	自定义任务标识，最多 255 个字符。该值会原样返回在响应任务的 `data` 对象中。

`historical_serp_mode` 取值

值	说明
`live`	返回目标当前仍出现在搜索结果页中的。
`lost`	返回目标曾经排名，但最近一次检查已不再排名的。
`all`	同时返回当前排名和已丢失排名的。

`item_types` 可选值

搜索结果类型：

answer_box、app、carousel、multi_carousel、featured_snippet、google_flights、google_reviews、third_party_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、currency_box、product_considerations、found_on_web、short_videos、refine_products、explore_brands、perspectives、discussions_and_forums、compare_sites、courses、ai_overview。

本接口返回详细排名的类型主要：

organic
paid
featured_snippet
local_pack
ai_overview_reference

`filters` 语法

支持以下运算符：

regex、not_regex、<、<=、>、>=、=、<>、in、not_in、match、not_match、ilike、not_ilike、like、not_like

使用 like、not_like、ilike 或 not_ilike 时，可以使用 % 匹零个或多个字符。

示例：

json

[
  {
    "target": "example.com",
    "location_code": 2840,
    "language_code": "en",
    "filters": [
      [
        "keyword_data.keyword_info.search_volume",
        ">",
        100
      ],
      "and",
      [
        "ranked_serp_element.serp_item.type",
        "<>",
        "paid"
      ]
    ],
    "order_by": [
      "keyword_data.keyword_info.search_volume,desc"
    ],
    "limit": 3
  }
]

如果需要查询某个网页的排名，可以直接将网页 URL 作为 target，也可以使用以下字段进行筛选：

ranked_serp_element.serp_item.relative_url

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/ranked_keywords/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "example.com",
      "location_name": "United States",
      "language_name": "English",
      "filters": [
        [
          "keyword_data.keyword_info.search_volume",
          ">",
          10
        ],
        "and",
        [
          "ranked_serp_element.serp_item.type",
          "<>",
          "paid"
        ]
      ],
      "limit": 3
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "target": "example.com",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            [
                "keyword_data.keyword_info.search_volume",
                ">",
                10,
            ],
            "and",
            [
                "ranked_serp_element.serp_item.type",
                "<>",
                "paid",
            ],
        ],
        "limit": 3,
    }
]

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

result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        f"请求失败，错误码：{result.get('status_code')}，"
        f"错误信息：{result.get('status_message')}"
    )

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    target: "example.com",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["keyword_data.keyword_info.search_volume", ">", 10],
      "and",
      ["ranked_serp_element.serp_item.type", "<>", "paid"],
    ],
    limit: 3,
  },
];

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

响应结构

接口返回 JSON 对象，主要结构如下：

json

{
  "version": "0.1.20250526",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.3363 sec.",
  "cost": 0.011,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "task-uuid",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.3200 sec.",
      "cost": 0.011,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "ranked_keywords",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "ranked_keywords",
        "se_type": "google",
        "target": "example.com",
        "location_name": "United States",
        "language_name": "English",
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1250,
          "items_count": 3,
          "metrics": {},
          "items": []
        }
      ]
    }
  ]
}

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	整体响应状态码。`20000` 表示成功。
`status_message`	string	整体状态信息。
`time`	string	请求执行时间，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	执行失败的任务数量。
`tasks`	array	任务结果数组。
`tasks[].id`	string	任务唯一标识，通常为 UUID 格式。
`tasks[].status_code`	integer	任务状态码，通常在 `10000` 至 `60000` 范围。
`tasks[].status_message`	string	任务状态信息。
`tasks[].time`	string	任务执行时间。
`tasks[].cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks[].result_count`	integer	`result` 数组中的数量。
`tasks[].path`	array	请求 API 的路径。
`tasks[].data`	object	请求中提交的任务参数。
`tasks[].result`	array	查询结果数组。

完整响应码请参考错误码文档。客户端应针对 HTTP 错误、整体 status_code 和任务级 status_code 分别进行异常处理。

`result` 字段

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`target`	string	请求中指定的域名、子域名或网页。
`location_code`	integer/null	地理位置代码。无对应数据时为 `null`。
`language_code`	string/null	语言代码。无对应数据时为 `null`。
`total_count`	integer	数据库中符合请求条件的结果总数。
`items_count`	integer	本次返回的数量。
`metrics`	object	按 `rank_group` 统计的排名、流量及变化指标。
`metrics_absolute`	object	按 `rank_absolute` 统计的排名分布。在 `load_rank_absolute=true` 时返回。
`items`	array	排名及数据。

`metrics` 与 `metrics_absolute`

两类指标对象均可能以下搜索结果类型：

organic：自然搜索
paid：付费搜索
featured_snippet：精选摘要
local_pack：本地结果
ai_overview_reference：AI 概览引用

每种类型通常以下字段：

字段	类型	说明
`pos_1`	integer	排名第 1 的结果数量。
`pos_2_3`	integer	排名第 2 至第 3 的结果数量。
`pos_4_10`	integer	排名第 4 至第 10 的结果数量。
`pos_11_20` 至 `pos_91_100`	integer	对应排名区间的结果数量。
`etv`	float	估算月流量，通常按点击率与搜索量计算。
`count`	integer	含目标的搜索结果总数。
`estimated_paid_traffic_cost`	float	将估算自然流量转化为付费流量所需的月度预估成本。
`is_new`	integer	新发现的排名数量。
`is_up`	integer	排名上升的数量。
`is_down`	integer	排名下降的数量。
`is_lost`	integer	最近一次检查中已丢失的排名数量。
`clickstream_etv`	integer	基于点击流搜索量计算的估算流量。需要启用 `include_clickstream_data`。
`clickstream_gender_distribution`	object	点击流用户性别分布。
`clickstream_age_distribution`	object	点击流用户年龄分布。

排名区间字段：

pos_1、pos_2_3、pos_4_10、pos_11_20、pos_21_30、pos_31_40、pos_41_50、pos_51_60、pos_61_70、pos_71_80、pos_81_90、pos_91_100。

点击流分布字段

clickstream_gender_distribution 和 gender_distribution含：

female：点击流数据集中女性用户数量
male：点击流数据集中男性用户数量

clickstream_age_distribution 和 age_distribution含：

18-24
25-34
35-44
45-54
55-64

这些字段分别表示对应年龄段的用户数量。只有启用 include_clickstream_data=true 时，点击流字段才会返回。

`items` 字段

每个 items素代表一个排名。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword_data`	object	及指标。
`keyword_properties`	object	附加属性。
`serp_info`	object	该对应的搜索结果页信息。
`avg_backlinks_info`	object	该自然排名前 10 个页面的平均反向链接指标。
`search_intent_info`	object	搜索意图信息。
`ranked_serp_element`	object	目标在该搜索结果页中的排名。

`keyword_data`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`keyword`	string	返回的。
`location_code`	integer	地理位置代码。
`language_code`	string	语言代码。
`keyword_info`	object	搜索量、竞争度和点击价格等数据。
`keyword_info_normalized_with_bing`	object/null	使用 Bing 搜索量归一化后的数据。
`keyword_info_normalized_with_clickstream`	object/null	使用点击流数据归一化后的数据。
`clickstream_keyword_info`	object/null	点击流数据在启用点击流数据时返回。

`keyword_info`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`last_updated_time`	string	数据更新时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`competition`	float/null	广告竞争度，范围为 `0` 至 `1`。
`competition_level`	string/null	付费搜索竞争等级：`LOW`、`MEDIUM`、`HIGH`。
`cpc`	float/null	平均每次点击费用。
`search_volume`	integer	平均月搜索量。
`low_top_of_page_bid`	float/null	广告出现在首页顶部所需的较低估算出价。
`high_top_of_page_bid`	float/null	广告出现在首页顶部所需的较高估算出价。
`categories`	array/null	产品和服务分类。
`monthly_searches`	array/null	过去 12 个月的月度搜索量。
`search_volume_trend`	object	搜索量变化趋势。

search_volume_trend 字段：

字段	类型	说明
`monthly`	integer	较上月的搜索量变化百分比。
`quarterly`	integer	较上季度的搜索量变化百分比。
`yearly`	integer	较上年度的搜索量变化百分比。

monthly_searches 数组中的：

字段	类型	说明
`year`	integer	年份。
`month`	integer	月份。
`search_volume`	integer	当月搜索量。

归一化与点击流字段

启用 include_clickstream_data=true 后，可能返回以下对象：

keyword_info_normalized_with_bing
keyword_info_normalized_with_clickstream
clickstream_keyword_info

这些对象通常：

字段	类型	说明
`last_updated_time`	string	数据集更新时间。
`search_volume`	integer	当前或月均搜索量。
`is_normalized`	boolean	是否已使用对应数据源进行归一化。
`monthly_searches`	array	按年月划分的搜索量数据。
`gender_distribution`	object	性别分布。
`age_distribution`	object	年龄分布。

`keyword_properties`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`core_keyword`	string/null	同义词分组中的核心。
`synonym_clustering_algorithm`	string/null	同义词聚类算法：`keyword_metrics` 或 `text_processing`。
`keyword_difficulty`	integer	自然搜索前 10 名的难度，范围为 `0` 至 `100`。
`detected_language`	string	系统识别出的语言。
`is_another_language`	boolean	识别出的语言是否与请求指定语言不同。

`serp_info`

字段	类型	说明
`se_type`	string	搜索引擎类型。
`check_url`	string	对应搜索结果页的直接 URL，可用于人工核验结果。
`serp_item_types`	array	搜索结果页中出现的类型。
`se_results_count`	integer/string	搜索结果数量。
`keyword_difficulty`	integer	自然排名难度。
`is_lost`	boolean	目标是否已不再出现在搜索结果页。
`last_updated_time`	string	当前搜索结果页数据更新时间。
`previous_updated_time`	string	上一次搜索结果页数据更新时间。

`avg_backlinks_info`

该对象描述该自然搜索前 10 个页面的平均反向链接。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`backlinks`	float	平均反向链接数量。
`dofollow`	float	平均 Dofollow 链接数量。
`referring_pages`	float	平均引用页面数量。
`referring_domains`	float	平均引用域名数量。
`referring_main_domains`	float	平均引用主域名数量。
`rank`	float	平均页面排名。
`main_domain_rank`	float	平均主域名排名。
`last_updated_time`	string	反向链接数据更新时间。

`search_intent_info`

字段	类型	说明
`se_type`	string	搜索引擎类型，通常为 `google`。
`main_intent`	string	主要搜索意图：`informational`、`navigational`、`commercial`、`transactional`。
`foreign_intent`	array/null	补搜索意图。
`last_updated_time`	string	搜索意图数据更新时间。

`ranked_serp_element`

该对象描述目标在对应搜索结果页中找到的排名。

字段	类型	说明
`se_type`	string	搜索引擎类型。
`serp_item`	object	排名的详细信息。
`check_url`	string	搜索结果页直接 URL。
`serp_item_types`	array	搜索结果页类型。
`se_results_count`	integer/string	搜索结果数量。
`keyword_difficulty`	integer	自然排名难度。
`is_lost`	boolean	该排名结果是否已经丢失。
`last_updated_time`	string	当前排名数据更新时间。
`previous_updated_time`	string	上一次排名数据更新时间。

`serp_item` 通用字段

不同结果类型的字段略有差异，但通常：

字段	类型	说明
`se_type`	string	搜索引擎类型。
`type`	string	结果类型，如 `organic`、`paid`、`local_pack`、`featured_snippet`、`ai_overview_reference`。
`rank_group`	integer	同类型结果中的相对排名。
`rank_absolute`	integer	所有搜索结果中的绝对排名。
`position`	string	页面位置：`left` 或 `right`。
`xpath`	string	结果的 XPath。
`domain`	string	搜索结果域名或子域名。
`title`	string	结果标题。
`url`	string	结果 URL。
`breadcrumb`	string	面屑路径。
`website_name`	string	网站名称。
`description`	string	结果描述。
`main_domain`	string	主域名。
`relative_url`	string	不协议和域名的相对 URL。
`etv`	float	该对应的估算月流量。
`estimated_paid_traffic_cost`	float/null	通过付费广告获得相应流量的月度预估成本。
`clickstream_etv`	integer/null	基于点击流数据的估算流量。
`rank_changes`	object	与上次检查相比的排名变化。
`backlinks_info`	object/null	目标页面的反向链接数据。
`rank_info`	object	页面排名和主域名排名。

自然结果 `organic`

除通用字段外，还可能：

字段	类型	说明
`is_image`	boolean	是否图片。
`is_video`	boolean	是否视频。
`is_featured_snippet`	boolean	是否为精选摘要。
`is_malicious`	boolean	是否被标记为恶意结果。
`pre_snippet`	string/null	描述前附加的信息。
`extended_snippet`	string/null	描述后附加的信息。
`amp_version`	boolean	是否存在 AMP 版本。
`rating`	object/null	评分信息。
`highlighted`	array	描述中加粗显示的词语。
`links`	array/null	站点链接。
`about_this_result`	object/null	“此结果”面板信息。

付费结果 `paid`

除通用字段外，还可能：

字段	类型	说明
`domain`	string	广告结果中的域名。
`breadcrumb`	string	广告结果的面屑。
`highlighted`	array	描述中加粗显示的词语。
`extra`	object	广告附加信息。
`extra.ad_aclk`	string	广告标识符。
`extra.description_rows`	array/null	扩展广告描述。
`links`	array/null	广告站点链接。

本地结果 `local_pack`

除通用字段外，还可能：

字段	类型	说明
`phone`	string	电话号码。
`is_paid`	boolean	是否为广告结果。
`rating`	object/null	评分及评价数量。

精选摘要 `featured_snippet`

除通用字段外，还可能：

字段	类型	说明
`featured_title`	string	精选摘要来源页面标题。
`table`	object/null	精选摘要中的表格。
`table.table_header`	array	表格列名。
`table.table_content`	array	表格，每个代表一行。

AI 概览引用 `ai_overview_reference`

字段	类型	说明
`type`	string	固定为 `ai_overview_reference`。
`rank_group`	integer	同类型中的相对排名。
`rank_absolute`	integer	所有搜索结果中的绝对排名。
`position`	string	页面位置。
`source`	string	引用来源名称或标题。
`domain`	string	引用来源域名。
`title`	string	引用页面标题。
`url`	string	引用页面 URL。
`text`	string	用于生成 AI 概览结果的引用文本。
`main_domain`	string	主域名。
`relative_url`	string	相对 URL。
`etv`	float	估算月流量。
`estimated_paid_traffic_cost`	float/null	付费流量成本估算。
`rank_changes`	object	排名变化。
`backlinks_info`	object/null	反向链接数据。
`rank_info`	object	页面及主域名排名。

排名变化 `rank_changes`

字段	类型	说明
`previous_rank_absolute`	integer/null	上一次检查中的绝对排名。新结果为 `null`。
`is_new`	boolean	是否为新发现的结果。
`is_up`	boolean	排名是否较上次上升。
`is_down`	boolean	排名是否较上次下降。

反向链接与页面排名

`backlinks_info`

字段	类型	说明
`referring_domains`	integer	引用域名数量，子域名按独立域名计算。
`referring_main_domains`	integer	引用主域名数量。
`referring_pages`	integer	指向目标页面的页面数量。
`dofollow`	integer	Dofollow 链接数量。
`backlinks`	integer	反向链接总数 Dofollow 和 Nofollow。
`time_update`	string	反向链接数据更新时间。

`rank_info`

字段	类型	说明
`page_rank`	integer	页面排名指标。
`main_domain_rank`	integer	主域名排名指标。

这些排名指标基于链接数据库中的节点排名方法计算，用于衡量页面和域名在链接中的相对重要性。

评分字段 `rating`

部分自然结果或本地结果可能评分对象：

字段	类型	说明
`rating_type`	string	评分类型：`Max5`、`Percents` 或 `CustomMax`。
`value`	integer	评分值。
`votes_count`	integer	评价数量。
`rating_max`	integer	评分上限。

常见状态码

状态码	说明
`20000`	请求成功。
状态码	请求或任务执行失败，请结合 `status_message` 定位原因。

建议同时检查以下字段：

HTTP 状态码
顶层 status_code
tasks[].status_code
tasks_error
status_message

实用场景

盘点网站排名：批量获取域名、子域名或网页的排名，评估自然搜索覆盖范围并制定扩展计划。
发现流量增长机会：筛选搜索量较高但排名处于第 11 至第 20 位的，优优化接近首页的页面以提升自然流量。
监控流失：使用 historical_serp_mode=lost 识别已丢失排名的，及时排查页面变更、衰退或竞争对手增长。
分析搜索结果类型占位：结合 organic、featured_snippet、local_pack 和 ai_overview_reference，评估网站在不同搜索结果中的可见度。
制定竞争策略：结合难度、搜索意图、前 10 名页面的平均反向链接和估算流量，判断目标的竞争强度与优级。

Google 排名（实时） ​

接口信息 ​

计费说明 ​

请求参数 ​

historical_serp_mode 取值 ​

item_types 可选值 ​

filters 语法 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

result 字段 ​

metrics 与 metrics_absolute ​

点击流分布字段 ​

items 字段 ​

keyword_data ​

keyword_info ​

归一化与点击流字段 ​

keyword_properties ​

serp_info ​

avg_backlinks_info ​

search_intent_info ​

ranked_serp_element ​

serp_item 通用字段 ​

自然结果 organic ​

付费结果 paid ​

本地结果 local_pack ​

精选摘要 featured_snippet ​

AI 概览引用 ai_overview_reference ​

Google 排名（实时）

接口信息

计费说明

请求参数

`historical_serp_mode` 取值

`item_types` 可选值

`filters` 语法

请求示例

cURL

Python

TypeScript

响应结构

顶层响应字段

`result` 字段

`metrics` 与 `metrics_absolute`

点击流分布字段

`items` 字段

`keyword_data`

`keyword_info`

归一化与点击流字段

`keyword_properties`

`serp_info`

`avg_backlinks_info`

`search_intent_info`

`ranked_serp_element`

`serp_item` 通用字段

自然结果 `organic`

付费结果 `paid`

本地结果 `local_pack`

精选摘要 `featured_snippet`

AI 概览引用 `ai_overview_reference`