SeerMarTech API 文档

主题

ranked_keywords/live：获取网站排名（旧版） ​

GET /v3/dataforseo_labs/locations_and_languages

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

POST https://api.seermartech.cn/v3/dataforseo_labs/ranked_keywords/live

> 容说明：本接口为 Ranked Keywords 旧版接口。虽然平台 API 已更新请求与响应结构，但该旧版接口仍保持容。新项目建议优使用新版接口。

本接口用于查询指定域名当前排名的，并返回对应的搜索结果页、排名、预估流量、月均搜索量、展示次数及指标。通过筛选 ranked_serp_element.serp_item.relative_url，还可以查询某个网页排名的。

计费与限制 ​

  • 每次成功提交请求均会产生费用。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 请求体使用 UTF-8 编码的 JSON 格式。
  • 单次请求最多返回 1000 个。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 请求体是 JSON 数组，即使只提交一个任务，也应使用 [{ ... }] 格式。

认证 ​

请求头使用 Bearer Token：

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

请求参数 ​

请求体是任务数组，每个代表一个查询任务。

参数类型填说明
targetstring是目标域名，不应 https:// 或 www.。例如：example.com。如果查询特定网页，需要结合 filters 使用 ranked_serp_element.serp_item.relative_url。
location_namestring否地理位置的完整名称，例如 United Kingdom。使用该参数时无需传 location_code。不传时返回所有可用地区的数据。
location_codeinteger否地理位置代码，例如 2840。使用该参数时无需传 location_name。不传时返回所有可用地区的数据。
language_namestring否语言完整名称，例如 English。使用该参数时无需传 language_code。不传时返回所有可用语言的数据。
language_codestring否语言代码，例如 en。使用该参数时无需传 language_name。不传时返回所有可用语言的数据。
item_typesarray否按搜索结果类型返回数据。可选值 organic、paid、featured_snippet、local_pack 等。若数组 organic 以外的类型，结果将按数组中的第一个类型排序；未返回的类型不能用于筛选或排序。
limitinteger否返回的最大数量。默认值为 100，最大值为 1000。
offsetinteger否结果偏移量，默认值为 0。例如传 10，将跳过前 10 条结果。
load_rank_absoluteboolean否是否返回基于绝对排名 rank_absolute 的排名分布。默认值为 false。设为 true 时，响应中将 metrics_absolute。
filtersarray否结果筛选条件。最多设置 8 个筛选条件，条件之间使用 and 或 or 连接。
order_byarray否结果排序规则。最多设置 3 条规则，支持 asc 和 desc。
tagstring否自定义任务标识，最长 255 个字符。该值会在响应的 data 对象中返回。

地区和语言参数 ​

location_name 与 location_code 二选一；language_name 与 language_code 二选一。可通过以下接口获取可用地区和语言：

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

item_types 可选值 ​

常见取值如下：

text
answer_box
app
carousel
multi_carousel
featured_snippet
google_flights
google_reviews
images
jobs
knowledge_graph
local_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

结果数据会针对以下四类搜索结果返回：

  • organic：自然搜索结果
  • paid：付费广告结果
  • featured_snippet：精选摘要
  • local_pack：本地结果

filters 格式 ​

筛选条件格式为：

json
["字段路径", "运算符", "值"]

多个条件示例：

json
[
  ["keyword_data.keyword_info.search_volume", ">", 0],
  "and",
  [
    ["ranked_serp_element.serp_item.type", "<>", "paid"],
    "or",
    ["ranked_serp_element.serp_item.is_malicious", "=", false]
  ]
]

支持的运算符：

text
<   <=   >   >=   =   <>   in   not_in   like   not_like

like 和 not_like 支持 % 通符，可匹零个或多个字符。

查询某个网页排名的时，可使用：

json
[
  ["ranked_serp_element.serp_item.relative_url", "=", "/blog/seo-guide/"]
]

order_by 格式 ​

排序规则格式为：

json
["字段路径", "asc"]

示例：

json
[
  ["keyword_data.keyword_info.search_volume", "desc"],
  ["ranked_serp_element.serp_item.rank_group", "asc"]
]

支持的排序方向：

  • asc：升序
  • desc：降序

请求示例 ​

cURL ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/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",
      "limit": 5,
      "filters": [
        ["keyword_data.keyword_info.search_volume", ">", 0],
        "and",
        [
          ["ranked_serp_element.serp_item.type", "<>", "paid"],
          "or",
          ["ranked_serp_element.serp_item.is_malicious", "=", false]
        ]
      ],
      "order_by": [
        ["keyword_data.keyword_info.search_volume", "desc"]
      ],
      "tag": "domain-keyword-report"
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/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",
        "limit": 5,
        "filters": [
            ["keyword_data.keyword_info.search_volume", ">", 0],
            "and",
            [
                ["ranked_serp_element.serp_item.type", "<>", "paid"],
                "or",
                ["ranked_serp_element.serp_item.is_malicious", "=", False],
            ],
        ],
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，错误码：%s，错误信息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/dataforseo_labs/ranked_keywords/live",
  [
    {
      target: "example.com",
      location_name: "United States",
      language_name: "English",
      limit: 5,
      filters: [
        ["keyword_data.keyword_info.search_volume", ">", 0],
        "and",
        [
          ["ranked_serp_element.serp_item.type", "<>", "paid"],
          "or",
          ["ranked_serp_element.serp_item.is_malicious", "=", false],
        ],
      ],
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    response.data.status_code,
    response.data.status_message
  );
}

响应结构 ​

响应为 JSON 对象，主要字段如下：

字段类型说明
versionstringAPI 当前版本。
status_codeinteger通用响应状态码。20000 表示成功。
status_messagestring通用状态信息。
timestring请求执行耗时，例如 0.6659 sec.。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数。
tasks_errorinteger执行失败的任务数量。
tasksarray任务结果数组。

tasks 字段 ​

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

result 字段 ​

字段类型说明
targetstring请求中的目标域名。
location_codeinteger / null地区代码。无对应数据时为 null。
language_codestring / null语言代码。无对应数据时为 null。
total_countinteger数据库中符合条件的结果总数。
items_countintegeritems 数组中的结果数量。
metricsobject按同类搜索结果排名统计的指标。
metrics_absoluteobject在 load_rank_absolute=true 时返回，按所有搜索结果的绝对排名统计。
itemsarray排名及数据。

排名指标：metrics ​

metrics 按搜索结果类型划分为 organic、paid、featured_snippet 和 local_pack。每个类型通常以下字段：

字段类型说明
pos_1integer排名第 1 的结果数量。
pos_2_3integer排名第 2 至第 3 的结果数量。
pos_4_10integer排名第 4 至第 10 的结果数量。
pos_11_20integer排名第 11 至第 20 的结果数量。
pos_21_30integer排名第 21 至第 30 的结果数量。
pos_31_40integer排名第 31 至第 40 的结果数量。
pos_41_50integer排名第 41 至第 50 的结果数量。
pos_51_60integer排名第 51 至第 60 的结果数量。
pos_61_70integer排名第 61 至第 70 的结果数量。
pos_71_80integer排名第 71 至第 80 的结果数量。
pos_81_90integer排名第 81 至第 90 的结果数量。
pos_91_100integer排名第 91 至第 100 的结果数量。
etvfloat预估月自然流量。通常按点击率与搜索量计算。
impressions_etvfloat基于展示次数估算的月流量。通常按点击率与展示次数计算。
countinteger含该域名的对应类型搜索结果总数。
estimated_paid_traffic_costfloat将预估流量转化为付费搜索流量所需的预估月成本。
is_newinteger新发现的排名数量。
is_upinteger排名上升的数量。
is_downinteger排名下降的数量。
is_lostinteger上次检查存在、本次检查未发现的排名数量。

metrics 中的排名区间基于 rank_group，即在相同搜索结果类型计算排名。

绝对排名指标：metrics_absolute ​

当请求参数 load_rank_absolute 设置为 true 时，响应会返回 metrics_absolute。结构与 metrics 类似，但 organic、paid、featured_snippet 和 local_pack 为数组，排名区间 rank_absolute 统计。

数组：

字段类型说明
pos_1 至 pos_91_100integer各绝对排名区间的结果数量。
is_newinteger新发现的排名数量。
is_upinteger排名上升的数量。
is_downinteger排名下降的数量。
is_lostinteger丢失的排名数量。

项目：items ​

每个 items素通常：

  • keyword_data：及指标。
  • ranked_serp_element：目标域名在该搜索结果页中的排名。

keyword_data ​

字段类型说明
keywordstring返回的。
location_codeinteger数据对应的地区代码。
language_codestring数据对应的语言代码。
keyword_infoobject搜索量、竞争度和点击价格等数据。
impressions_infoobject基于广告展示次数的数据。
bing_keyword_infoobject基于 Bing 广告数据的信息。部分地区和语言可能没有该数据。
serp_infoobject对应的搜索结果页信息。

keyword_info ​

字段类型说明
last_updated_timestring数据更新时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00。
competitionfloat / null相对竞争度，范围为 0 至 1。无数据时为 null。
cpcfloat / null历史平均每次点击费用。无数据时为 null。
search_volumeinteger / null平均月搜索量。无数据时为 null。
categoriesarray / null产品和服务分类。无数据时为 null。
monthly_searchesarray / null过去 12 个月的月度搜索量。无数据时为 null。

monthly_searches 数组：

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger对应月份的搜索量。

impressions_info ​

展示次数数据使用较高出价值估算，以降低账户个性化因素对结果的影响。该数据可作为搜索量的补参考。

字段类型说明
last_updated_timestring展示次数数据更新时间，UTC 格式。
bidinteger最高每次点击出价。该接口通常使用 999。
match / match_typestring匹类型：exact、broad 或 phrase。
ad_position_minfloat最低广告排名。
ad_position_maxfloat最高广告排名。
ad_position_averagefloat平均广告排名。
cpc_minfloat最低每次点击费用估算值。
cpc_maxfloat最高每次点击费用估算值。
cpc_averagefloat平均每次点击费用估算值。
daily_impressions_minfloat每日最低展示次数。
daily_impressions_maxfloat每日最高展示次数。
daily_impressions_averagefloat每日平均展示次数。
daily_clicks_minfloat每日最低点击次数。
daily_clicks_maxfloat每日最高点击次数。
daily_clicks_averagefloat每日平均点击次数。
daily_cost_minfloat每日最低广告成本。
daily_cost_maxfloat每日最高广告成本。
daily_cost_averagefloat每日平均广告成本。

> impressions_info 中的 cpc_min、cpc_max 和 cpc_average 是基于 bid=999 的估算值，并不代表 CPC。 CPC 应读取 keyword_info.cpc。

bing_keyword_info ​

字段类型说明
last_updated_timestringBing 数据更新时间，UTC 格式。
search_volumeintegerBing 月搜索量。
monthly_searchesarray指定地区的 Bing 月搜索量明细。

serp_info ​

字段类型说明
check_urlstring搜索结果页直接地址，可用于核验结果。
serp_item_typesarray当前搜索结果页的类型。
se_results_countstring / integer搜索结果数量。
keyword_difficultyinteger / null难度，范围为 0 至 100，数值越高表示自然搜索前 10 名越困难。
last_updated_timestring当前搜索结果数据更新时间，UTC 格式。
previous_updated_timestring上一次搜索结果数据更新时间，UTC 格式。

排名：ranked_serp_element ​

ranked_serp_element 描述目标域名在指定搜索结果页中的信息，主要：

字段类型说明
serp_itemobject目标域名对应的搜索结果。
check_urlstring搜索结果页直接地址。
serp_item_typesarray搜索结果页的类型。
se_results_countstring / integer搜索结果数量。
keyword_difficultyinteger / null难度。
last_updated_timestring当前排名数据更新时间。
previous_updated_timestring上一次排名数据更新时间。

通用 serp_item 字段 ​

自然结果、付费结果、本地结果和精选摘要会根据类型返回不同字段。常见字段如下：

字段类型说明
typestring素类型：organic、paid、local_pack 或 featured_snippet。
rank_groupinteger在同类型搜索结果中的排名。
rank_absoluteinteger在所有搜索结果中的绝对排名。
positionstring素在页面中的位置：left 或 right。
xpathstring素在页面中的 XPath。
domainstring搜索结果中的域名或子域名。
titlestring搜索结果标题。
urlstring搜索结果 URL。
breadcrumbstring搜索结果面屑。
descriptionstring搜索结果描述。
main_domainstring主域名。
relative_urlstring不协议和域名的相对 URL。
highlightedarray描述中被加粗显示的。
linksarray / null附加链接或站点链接。没有时为 null。
etvfloat该对应的预估自然流量。
impressions_etvfloat基于展示次数计算的预估流量。
estimated_paid_traffic_costfloat将该自然流量转化为付费流量的预估成本。
rank_changesobject与上次检查相比的排名变化。

自然结果 organic ​

当 type 为 organic 时，还可能返回：

字段类型说明
is_imageboolean是否图片。
is_videoboolean是否视频。
is_featured_snippetboolean是否为精选摘要。
is_maliciousboolean是否被标记为恶意结果。
pre_snippetstring / null描述前附加的信息。
extended_snippetstring / null描述后附加的信息。
amp_versionboolean是否存在 AMP 版本。
ratingobject / null评分信息。
about_this_resultobject该搜索结果的附加信息。

rating 字段：

  • rating_type：评分类型，可为 Max5、Percents 或 CustomMax。
  • value：评分值。
  • votes_count：评价数量。
  • rating_max：评分上限。

links素：

字段类型说明
typestring固定为 link_element。
titlestring链接标题。
descriptionstring链接描述。
urlstring链接地址。
main_domainstring主域名。
relative_urlstring相对 URL。

付费结果 paid ​

当 type 为 paid 时，还可能返回：

字段类型说明
domainstring广告结果中的域名。
breadcrumbstring广告面屑。
extraarray广告附加信息。
ad_aclkstring广告标识。
description_rowsarray / null扩展描述。没有时为 null。

付费结果的 links素通常：

  • type：固定为 ad_link_element
  • title：链接标题
  • description：链接描述
  • url：链接地址
  • ad_aclk：广告标识
  • main_domain：主域名
  • relative_url：相对 URL

本地结果 local_pack ​

当 type 为 local_pack 时，还可能返回：

字段类型说明
phonestring电话号码。
is_paidboolean是否为广告结果。
ratingobject商家评分信息。
main_domainstring主域名。
relative_urlstring相对 URL。

当 type 为 featured_snippet 时，还可能返回：

字段类型说明
featured_titlestring精选摘要来源页面标题。
tablearray / null精选摘要中的表格。没有时为 null。
table_headerarray表格列名。
table_contentarray表格，每个代表一行。

rank_changes ​

字段类型说明
previous_rank_absoluteinteger / null上一次检查时的绝对排名。新为 null。
is_newboolean本次新发现的。
is_upboolean相比上次检查排名是否上升。
is_downboolean相比上次检查排名是否下降。

响应示例 ​

json
{
  "version": "0.1.20210917",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.6659 sec.",
  "cost": 0.0102,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.6000 sec.",
      "cost": 0.0102,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "ranked_keywords",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "ranked_keywords",
        "target": "example.com",
        "language_name": "English",
        "location_code": 2840,
        "limit": 2
      },
      "result": [
        {
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 1250,
          "items_count": 2,
          "metrics": {
            "organic": {
              "pos_1": 12,
              "pos_2_3": 24,
              "pos_4_10": 86,
              "pos_11_20": 115,
              "pos_21_30": 140,
              "etv": 1520.4,
              "impressions_etv": 1680.2,
              "count": 377,
              "estimated_paid_traffic_cost": 8420.6,
              "is_new": 8,
              "is_up": 31,
              "is_down": 18,
              "is_lost": 5
            },
            "paid": {
              "pos_1": 2,
              "pos_2_3": 4,
              "pos_4_10": 7,
              "count": 13,
              "etv": 120.5,
              "impressions_etv": 135.2,
              "estimated_paid_traffic_cost": 980.4,
              "is_new": 1,
              "is_up": 2,
              "is_down": 1,
              "is_lost": 0
            }
          },
          "items": [
            {
              "keyword_data": {
                "keyword": "seo tools",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "last_updated_time": "2021-10-14 08:14:04 +00:00",
                  "competition": 0.1175,
                  "cpc": 8.8787,
                  "search_volume": 110,
                  "categories": null,
                  "monthly_searches": [
                    {
                      "year": 2021,
                      "month": 10,
                      "search_volume": 110
                    }
                  ]
                },
                "impressions_info": {
                  "last_updated_time": "2021-10-22 23:35:53 +00:00",
                  "bid": 999,
                  "match": "exact",
                  "ad_position_min": 1.11,
                  "ad_position_max": 1.0,
                  "ad_position_average": 1.06,
                  "cpc_min": 244.35,
                  "cpc_max": 298.65,
                  "cpc_average": 271.5,
                  "daily_impressions_min": 0.41,
                  "daily_impressions_max": 0.5,
                  "daily_impressions_average": 0.46,
                  "daily_clicks_min": 0.01,
                  "daily_clicks_max": 0.02,
                  "daily_clicks_average": 0.02,
                  "daily_cost_min": 4.85,
                  "daily_cost_max": 3.97,
                  "daily_cost_average": 4.41
                },
                "bing_keyword_info": {
                  "last_updated_time": "2021-10-08 18:55:52 +00:00",
                  "search_volume": 20,
                  "monthly_searches": []
                },
                "serp_info": {
                  "check_url": "https://www.google.com/search?q=seo%20tools&num=100&hl=en&gl=US",
                  "serp_item_types": [
                    "organic",
                    "paid",
                    "people_also_ask"
                  ],
                  "se_results_count": 606000000,
                  "keyword_difficulty": null,
                  "last_updated_time": "2021-10-23 12:49:59 +00:00",
                  "previous_updated_time": "2021-08-28 14:45:37 +00:00"
                }
              },
              "ranked_serp_element": {
                "serp_item": {
                  "type": "organic",
                  "rank_group": 1,
                  "rank_absolute": 1,
                  "position": "left",
                  "domain": "example.com",
                  "title": "SEO 工与营销数据平台",
                  "url": "https://example.com/",
                  "breadcrumb": "https://example.com",
                  "is_image": false,
                  "is_video": false,
                  "is_featured_snippet": false,
                  "is_malicious": false,
                  "description": "用于 SEO 研究和排名分析的。",
                  "main_domain": "example.com",
                  "relative_url": "/",
                  "etv": 15.2,
                  "impressions_etv": 24.44,
                  "estimated_paid_traffic_cost": 119.48,
                  "rank_changes": {
                    "previous_rank_absolute": 2,
                    "is_new": false,
                    "is_up": true,
                    "is_down": false
                  }
                },
                "check_url": "https://www.google.com/search?q=seo%20tools&num=100&hl=en&gl=US",
                "serp_item_types": [
                  "organic",
                  "paid"
                ],
                "se_results_count": 606000000,
                "keyword_difficulty": null,
                "last_updated_time": "2021-10-23 12:49:59 +00:00",
                "previous_updated_time": "2021-08-28 14:45:37 +00:00"
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理 ​

响应中的 status_code 和 status_message 用于判断请求及任务执行结果。建议客户端同时处理以下：

  • HTTP 层认证失败、请求格式错误或访问频率限。
  • 顶层 status_code 非 20000。
  • 某个任务的 status_code 非 20000。
  • tasks_error 大于 0。
  • 结果字段为 null 或返回结果数量少于预期。

实用场景 ​

  • 挖掘网站排名：获取域名覆盖的、搜索量和排名，评估自然搜索覆盖范围并制定扩展计划。
  • 定位单页优化机会：通过 relative_url 筛选指定网页的排名，发现页面已有排名但流量潜力尚未释放的词。
  • 监控排名区间变化：对比 metrics 和 rank_changes 中的上升、下降、新增及丢失数据，及时识别 SEO 风险和增长机会。
  • 评估搜索流量价值：结合 etv、impressions_etv 和 estimated_paid_traffic_cost，估算自然流量规模及对应的广告替代价值。
  • 分析 SERP 展现机会：区分 organic、paid、featured_snippet 和 local_pack 等结果类型，制定精选摘要、本地搜索和自然排名的专项优化策略。

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

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