SeerMarTech API 文档

主题

Bing 排名（实时） ​

GET /v3/dataforseo_labs/locations_and_languages

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

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

用于查询指定域名或网页当前排名的，并返回对应的搜索结果页、排名、月搜索量、难度、预估流量及反向链接数据。

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

请求限制与计费 ​

  • 请求体使用 UTF-8 编码的 JSON。
  • 请求体格式为 JSON 数组：[{ ... }]。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时处理的请求数最多为 30 个。
  • 每个任务单独计费。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

任务参数 ​

参数类型填说明
targetstring是查询目标，可以是域名或网页 URL。域名不 https:// 和 www.；网页 URL须 https:// 或 www.。
location_namestring否地理位置名称。设置后无需设置 location_code。可通过 /v3/dataforseo_labs/locations_and_languages 查询可用值。忽略时返回所有可用位置的数据。本接口目前支持美国位置。示例：United States。
location_codeinteger否地理位置代码。设置后无需设置 location_name。本接口目前支持美国，示例值：2840。
language_namestring否语言名称。设置后无需设置 language_code。示例：English。
language_codestring否语言代码。设置后无需设置 language_name。示例：en。
item_typesarray否限定返回的搜索结果类型。可用值 organic、paid、featured_snippet、local_pack 等。若数组 organic 之外的类型，结果将优数组中的第一种类型排序。未的结果类型不能用于筛选或排序。
ignore_synonymsboolean否是否排除高度相似。为 true 时返回核心。默认值：false。
limitinteger否最多返回的数量。默认值：100，最大值：1000。
offsetinteger否结果偏移量，默认值：0。例如设置为 10 时，跳过前 10 个结果。
load_rank_absoluteboolean否是否返回基于 rank_absolute 的排名分布。默认值：false。设为 true 时，响应中会 metrics_absolute。
historical_serp_modestring否历史排名筛选模式。可选值：live、lost、all。默认值：live。
filtersarray否结果筛选条件。最多设置 8 个筛选条件，条件之间使用 and 或 or 连接。
order_byarray否结果排序规则。最多设置 3 条规则，排序值使用 asc 或 desc 指定升序或降序。
tagstring否自定义任务标识，最长 255 个字符。该值会原样返回在响应的 data 对象中。

historical_serp_mode 可选值 ​

值说明
live返回目标当前仍在搜索结果页中获得排名的。
lost返回目标此前获得过排名、但最近一次检查时已不再排名的。
all同时返回当前排名和已丢失排名的。

筛选器 ​

最多可同时使用 8 个筛选条件。支持的运算符如下：

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

like、not_like、ilike 和 not_ilike 支持使用 % 匹零个或多个字符。

筛选器格式 ​

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

如果需要查询某个网页排名的，可使用以下字段进行筛选：

json
[
  "ranked_serp_element.serp_item.relative_url",
  "=",
  "/example-page"
]

请求示例 ​

curl ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/bing/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"],
          "or",
          ["ranked_serp_element.serp_item.is_paid", "=", false]
        ]
      ],
      "limit": 3
    }
  ]'

Python ​

python
import requests

url = "https://api.seermartech.cn/v3/dataforseo_labs/bing/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"],
                "or",
                ["ranked_serp_element.serp_item.is_paid", "=", False],
            ],
        ],
        "limit": 3,
    }
]

response = requests.post(url, headers=headers, json=payload)
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"],
        "or",
        ["ranked_serp_element.serp_item.is_paid", "=", false],
      ],
    ],
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/bing/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 对象，顶层 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查询结果数组。

result 字段 ​

字段类型说明
se_typestring搜索引擎类型，固定为 bing。
targetstring请求中的目标域名或网页 URL。
location_codeinteger地理位置代码。无数据时为 null。
language_codestring语言代码。无数据时为 null。
total_countinteger数据库中符合条件的结果总数。
items_countinteger实返回的 items 数量。
metricsobject按 rank_group 统计的排名与流量数据。
metrics_absoluteobject按 rank_absolute 统计的排名分布。在 load_rank_absolute=true 时返回。
itemsarray排名及数据。

metrics 与 metrics_absolute ​

metrics 中的排名区间基于 rank_group，即在相同搜索结果类型中计算排名；metrics_absolute 基于 rank_absolute，即所有搜索结果的绝对位置计算。

两通常以下结果类型：

  • 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预估月流量。通常根据点击率（CTR）与搜索量计算。
countinteger含目标的对应搜索结果总数。
estimated_paid_traffic_costfloat将预估流量通过付费搜索获取所需的预估月成本。
is_newinteger新发现的排名数量。
is_upinteger排名上升的数量。
is_downinteger排名下降的数量。
is_lostinteger最近一次检查中丢失的排名数量。

对于 metrics_absolute，organic、paid、featured_snippet 和 local_pack 的结构为数组，并主要返回上述排名区间及排名变化字段。

items 字段 ​

每个 items素以下对象：

字段类型说明
keyword_dataobject返回的指标、搜索结果页及竞争数据。
ranked_serp_elementobject目标在该搜索结果页中的排名。

keyword_data ​

字段类型说明
se_typestring搜索引擎类型。
keywordstring返回的。
location_codeinteger地理位置代码。
language_codestring语言代码。
keyword_infoobject搜索量及竞价数据。
keyword_propertiesobject属性及同义词信息。
serp_infoobject对应的搜索结果页信息。
avg_backlinks_infoobject排名前 10 的自然结果的平均反向链接数据；无数据时为 null。

keyword_info ​

字段类型说明
se_typestring搜索引擎类型。
last_updated_timestring数据更新时间，UTC 格式：yyyy-mm-dd hh:mm:ss +00:00。
competitionfloat竞争度，取值范围为 0 至 1；无数据时为 null。
cpcfloat历史平均单次点击费用；无数据时为 null。
search_volumeinteger平均月搜索量；无数据时为 null。
monthly_searchesarray过去 12 个月的月度搜索量数据；无数据时为 null。

monthly_searches 数组：

字段类型说明
yearinteger年份。
monthinteger月份。
search_volumeinteger当月平均搜索量。

keyword_properties ​

字段类型说明
se_typestring搜索引擎类型。
core_keywordstring同义词分组中的核心；无匹时为 null。
synonym_clustering_algorithmstring同义词识别算法。keyword_metrics 表示基于指标，text_processing 表示基于文本处理；无匹时为 null。
keyword_difficultyinteger难度，范围为 0 至 100，表示自然搜索前 10 名的难度。
detected_languagestring系统识别出的语言。
is_another_languageboolean识别出的语言是否与请求设置的语言不同。

serp_info ​

字段类型说明
se_typestring搜索引擎类型。
check_urlstring对应搜索结果页的直接 URL，可用于人工核验结果。
serp_item_typesarray搜索结果页中出现的类型。
se_results_countinteger搜索结果数量。
keyword_difficultyinteger难度，范围为 0 至 100。
last_updated_timestring搜索结果页数据更新时间。
previous_updated_timestring上一次搜索结果页数据更新时间。

serp_item_types 可能：

answer_box、carousel、events、featured_snippet、hotels_pack、images、jobs、local_pack、map、organic、paid、people_also_ask、people_also_search、questions_and_answers、recipes、related_searches、shopping、top_stories、video、ai_overview

详细结果会针对以下返回：

  • organic
  • paid
  • featured_snippet
  • local_pack

该对象提供对应自然搜索前 10 个网站的平均反向链接指标。

字段类型说明
se_typestring搜索引擎类型。
backlinksfloat平均反向链接数量。
dofollowfloat平均 dofollow 链接数量。
referring_pagesfloat平均引荐页面数量。
referring_domainsfloat平均引荐域名数量。
referring_main_domainsfloat平均引荐主域名数量。
rankfloat平均页面排名。
main_domain_rankfloat平均主域名排名。
last_updated_timestring反向链接数据更新时间。

ranked_serp_element ​

字段类型说明
se_typestring搜索引擎类型。
serp_itemobject目标在搜索结果页中对应的。
check_urlstring搜索结果页直接 URL。
serp_item_typesarray搜索结果页类型。
se_results_countinteger搜索结果数量。
keyword_difficultyinteger难度。
is_lostboolean是否已丢失排名。
last_updated_timestring搜索结果页数据更新时间。
previous_updated_timestring上一次搜索结果页数据更新时间。

serp_item 通用字段 ​

不同搜索结果类型会返回不同字段，常见字段如下：

字段类型说明
typestring结果类型：organic、paid、featured_snippet 或 local_pack。
rank_groupinteger同类型搜索结果中的排名。
rank_absoluteinteger在所有搜索结果中的绝对排名。
positionstring素在页面中的位置，可为 left 或 right。
xpathstring素在页面中的 XPath。
domainstring搜索结果中的域名或子域名。
main_domainstring主域名。
relative_urlstring不协议和域名的相对 URL。
titlestring搜索结果标题。
descriptionstring搜索结果描述。
urlstring搜索结果 URL。
breadcrumbstring面屑路径。
etvfloat该带来的预估月流量。
estimated_paid_traffic_costfloat通过付费搜索获取相应流量的预估成本。
rank_changesobject与上一次检查相比的排名变化。
backlinks_infoobject目标页面或网站的反向链接信息。
rank_infoobject页面排名和主域名排名信息。

自然结果 organic ​

除通用字段外，可能：

字段类型说明
is_imageboolean是否图片。
is_videoboolean是否视频。
is_featured_snippetboolean是否为精选摘要。
is_maliciousboolean是否被标记为恶意结果。
pre_snippetstring描述前附加的信息。
extended_snippetstring描述后附加的信息。
amp_versionboolean是否存在 AMP 版本。
ratingobject评分信息。
highlightedarray描述中以粗体突出显示的词语。
linksarray附加站点链接；无链接时为 null。

付费结果 paid ​

除通用字段外，可能：

字段类型说明
highlightedarray描述中突出显示的词语。
extraobject广告附加信息。
ad_aclkstring广告标识。
description_rowsarray扩展描述；无数据时为 null。
linksarray广告附加链接；无链接时为 null。

本地结果 local_pack ​

除通用字段外，可能：

字段类型说明
phonestring电话号码。
is_paidboolean是否为广告结果。
ratingarray商家评分信息。

除通用字段外，可能：

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

评分字段 rating ​

评分对象或数组可能以下字段：

字段类型说明
rating_typestring评分类型，可为 Max5、Percents 或 CustomMax。
valueinteger评分值。
votes_countinteger评价数量。
rating_maxinteger当前评分类型的最大值。

rank_changes ​

字段类型说明
previous_rank_absoluteinteger上一次检查时的绝对排名；新为 null。
is_newboolean是否为新发现的搜索结果。
is_upboolean排名是否上升。
is_downboolean排名是否下降。
字段类型说明
referring_domainsinteger引荐域名数量，子域名会作为独立域名计算。
referring_main_domainsinteger引荐主域名数量。
referring_pagesinteger指向目标网站的页面数量。
dofollowintegerdofollow 链接数量。
backlinksinteger反向链接总数 dofollow 和 nofollow 链接。
time_updatestring反向链接数据更新时间，UTC 格式。

rank_info ​

字段类型说明
page_rankinteger页面排名指标。
main_domain_rankinteger主域名排名指标。

响应示例 ​

以下示例展示主要响应结构，部分数组已省略：

json
{
  "version": "0.1.20240313",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.7323 sec.",
  "cost": 0.0103,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.7000 sec.",
      "cost": 0.0103,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "bing",
        "ranked_keywords",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "ranked_keywords",
        "se_type": "bing",
        "target": "example.com",
        "language_name": "English",
        "location_name": "United States",
        "load_rank_absolute": true,
        "limit": 3
      },
      "result": [
        {
          "se_type": "bing",
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 3,
          "items_count": 3,
          "metrics": {
            "organic": {
              "pos_1": 1,
              "pos_2_3": 0,
              "pos_4_10": 2,
              "etv": 125.6,
              "count": 3,
              "is_new": 1,
              "is_up": 1,
              "is_down": 0,
              "is_lost": 0
            },
            "paid": null,
            "featured_snippet": null,
            "local_pack": null
          },
          "metrics_absolute": {
            "organic": [
              {
                "pos_1": 1,
                "pos_2_3": 0,
                "pos_4_10": 2,
                "is_new": 1,
                "is_up": 1,
                "is_down": 0,
                "is_lost": 0
              }
            ]
          },
          "items": [
            {
              "keyword_data": {
                "se_type": "bing",
                "keyword": "example keyword",
                "location_code": 2840,
                "language_code": "en",
                "keyword_info": {
                  "se_type": "bing",
                  "last_updated_time": "2024-03-28 09:54:52 +00:00",
                  "competition": 0.1,
                  "cpc": null,
                  "search_volume": 20,
                  "monthly_searches": [
                    {
                      "year": 2024,
                      "month": 3,
                      "search_volume": 20
                    }
                  ]
                },
                "keyword_properties": {
                  "se_type": "bing",
                  "core_keyword": null,
                  "synonym_clustering_algorithm": "text_processing",
                  "keyword_difficulty": 65,
                  "detected_language": "en",
                  "is_another_language": false
                },
                "serp_info": {
                  "se_type": "bing",
                  "check_url": "https://www.bing.com/search?q=example+keyword",
                  "serp_item_types": [
                    "organic",
                    "featured_snippet"
                  ],
                  "se_results_count": 100000,
                  "keyword_difficulty": 65,
                  "last_updated_time": "2024-03-29 06:20:59 +00:00",
                  "previous_updated_time": "2024-02-24 01:38:22 +00:00"
                },
                "avg_backlinks_info": null
              },
              "ranked_serp_element": {
                "se_type": "bing",
                "serp_item": {
                  "se_type": "bing",
                  "type": "organic",
                  "rank_group": 1,
                  "rank_absolute": 1,
                  "position": "left",
                  "domain": "example.com",
                  "title": "Example page",
                  "url": "https://example.com/page",
                  "relative_url": "/page",
                  "etv": 12.5,
                  "estimated_paid_traffic_cost": null,
                  "rank_changes": {
                    "previous_rank_absolute": 3,
                    "is_new": false,
                    "is_up": true,
                    "is_down": false
                  },
                  "backlinks_info": null,
                  "rank_info": {
                    "page_rank": 0,
                    "main_domain_rank": 0
                  }
                },
                "check_url": "https://www.bing.com/search?q=example+keyword",
                "serp_item_types": [
                  "organic"
                ],
                "se_results_count": 100000,
                "keyword_difficulty": 65,
                "is_lost": false,
                "last_updated_time": "2024-03-29 06:20:59 +00:00",
                "previous_updated_time": "2024-02-24 01:38:22 +00:00"
              }
            }
          ]
        }
      ]
    }
  ]
}

错误处理 ​

建议根据顶层和任务级别的 status_code、status_message 分别处理请求错误和任务错误。完整错误码请参考错误码文档。

成功响应通常：

json
{
  "status_code": 20000,
  "status_message": "Ok."
}

如果 tasks_error 大于 0，应逐项检查 tasks 数组中的任务状态。

实用场景 ​

  • 挖掘竞争对手的 Bing 排名，识别覆盖的搜索需求并扩展自身库。
  • 定位网页的排名词，筛选 relative_url 找出某个落地页获得流量的，优化页面主题与链接。
  • 监控排名变化，结合 is_new、is_up、is_down 和 is_lost 识别增长机会与流量损失。
  • 评估自然搜索流量潜力，使用 search_volume、etv、keyword_difficulty 和 estimated_paid_traffic_cost 排定及 SEO 优级。
  • 分析 SERP 特殊结果占位，通过 featured_snippet、local_pack 和 paid 数据评估精选摘要、本地搜索及竞价结果的竞争。

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

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