SeerMarTech API 文档

主题

Google 页面实时排名与流量数据 ​

POST /v3/dataforseo_labs/google/relevant_pages/live

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

/v3/dataforseo_labs/google/relevant_pages/live

用于查询指定域名下页面的排名与流量数据。接口会返回各页面在不同排名区间的分布、自然搜索与付费搜索的预估月流量，以及页面排名变化。

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

接口限制与计费 ​

  • 每次请求按请求量计费。
  • 单次 Live API 请求只能 1 个任务。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时处理的请求数最多为 30 个。
  • 开启 include_clickstream_data 后，当前请求按标准价格的 2 倍计费。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数 ​

请求体使用 UTF-8 编码的 JSON 数组格式：

json
[
  {
    "target": "example.com",
    "location_name": "United States",
    "language_name": "English",
    "item_types": ["organic"],
    "limit": 100
  }
]
参数类型说明
targetstring填。目标域名，不应 https:// 或 www.。例如：example.com
location_namestring可选。完整地区名称。使用此参数时无需传 location_code。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区。省略时返回所有可用地区的数据。例如：United Kingdom
location_codeinteger可选。地区代码。使用此参数时无需传 location_name。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用地区代码。省略时返回所有可用地区的数据。例如：2840
language_namestring可选。完整语言名称。使用此参数时无需传 language_code。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言。例如：English
language_codestring可选。语言代码。使用此参数时无需传 language_name。可通过 /v3/dataforseo_labs/locations_and_languages 获取可用语言代码。例如：en
item_typesarray可选。指定返回的搜索结果类型。可选值 organic、paid、featured_snippet、local_pack。如果数组中 organic 以外的类型，结果将数组中的第一个类型排序。未在数组中的结果类型不能用于过滤或排序。
include_clickstream_databoolean可选。是否返回基于点击流数据计算的指标。设为 true 时，响应中会 clickstream_etv、clickstream_gender_distribution 和 clickstream_age_distribution。默认值为 false。开启后按标准价格的 2 倍计费。
limitinteger可选。最多返回的页面数量。默认值为 100，最大值为 1000。
offsetinteger可选。结果数组的偏移量。默认值为 0。例如设置为 10 时，将跳过前 10 条结果。
historical_serp_modestring可选。历史搜索结果筛选模式。live：返回目标域名当前仍有排名的搜索结果；lost：返回目标域名过去有排名、但最近一次检查中已丢失排名的搜索结果；all：返回以上两类结果。默认值为 live。
ignore_synonymsboolean可选。是否忽略高度相似的。设为 true 时返回核心，排除高度相似。默认值为 false。
filtersarray可选。结果过滤条件，最多设置 8 个过滤条件。支持使用 and 或 or 连接条件。支持的运算符：regex、not_regex、<、<=、>、>=、=、<>、in、not_in。
order_byarray可选。结果排序规则。可使用与 filters 相同的字段，并使用 asc 或 desc 指定升序或降序。单次请求最多设置 3 条排序规则。
tagstring可选。用户自定义任务标识，最长 255 个字符。该值会原样返回在响应的 data 对象中，可用于请求与结果。

过滤器示例 ​

以下示例返回自然搜索排名位于第 1 位或第 2～3 位的页面：

json
"filters": [
  ["metrics.organic.pos_1", "<>", 0],
  "or",
  ["metrics.organic.pos_2_3", "<>", 0]
]

排序示例 ​

json
"order_by": [
  "metrics.organic.etv,desc",
  "page_address,asc"
]

响应字段 ​

接口返回 JSON 对象 tasks 数组。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码。成功通常为 20000。完整错误码请参考错误码文档。
status_messagestring通用状态消息
timestring请求执行耗时，例如 4.1423 sec.
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务总数
tasks_errorintegertasks 数组中返回错误的任务数量
tasksarray任务结果数组

任务字段 ​

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

result 字段 ​

字段类型说明
se_typestring搜索引擎类型，此接口通常为 google
targetstring请求中的目标域名
location_codeinteger请求中的地区代码；没有数据时为 null
language_codestring请求中的语言代码；没有数据时为 null
total_countinteger数据库中与请求条件的结果总数
items_countinteger本次 items 数组返回的结果数量
itemsarray页面及指标

items 字段 ​

字段类型说明
se_typestring搜索引擎类型
page_addressstring页面的完整 URL
metricsobject页面排名与流量指标
metrics.organicobject自然搜索排名与流量指标
metrics.paidobject付费搜索排名与流量指标
metrics.featured_snippetobjectGoogle 搜索结果精选摘要中的排名与流量指标
metrics.local_packobject搜索结果本地服务中的排名与流量指标

排名与流量指标 ​

以下字段适用于 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预估流量。表示页面的预估月流量，通常根据的点击率与搜索量计算。
countinteger含该页面的搜索结果总数
estimated_paid_traffic_costfloat预估流量成本。表示通过付费搜索获得相同月流量所需的预估成本，金额字段以人民币计。
is_newinteger新增排名数量
is_upinteger排名上升的排名数量
is_downinteger排名下降的排名数量
is_lostinteger已丢失的排名数量，即此前出现在搜索结果中、但最近一次检查未发现的排名
clickstream_etvinteger基于点击流数据计算的预估流量。当 include_clickstream_data 为 true 时返回。
clickstream_gender_distributionobject基于点击流指标的性别分布。当 include_clickstream_data 为 true 时返回。
clickstream_age_distributionobject基于点击流指标的年龄分布。当 include_clickstream_data 为 true 时返回。

性别分布字段 ​

字段类型说明
femaleinteger点击流数据集中女性用户数量
maleinteger点击流数据集中男性用户数量

年龄分布字段 ​

字段类型说明
18-24integer18～24 岁用户数量
25-34integer25～34 岁用户数量
35-44integer35～44 岁用户数量
45-54integer45～54 岁用户数量
55-64integer55～64 岁用户数量

> 注意：clickstream_etv、clickstream_gender_distribution 和 clickstream_age_distribution 在请求参数 include_clickstream_data 设置为 true 时返回。

cURL 示例 ​

bash
curl --location --request POST \
  "https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/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": [
        ["metrics.organic.pos_1", "<>", 0],
        "or",
        ["metrics.organic.pos_2_3", "<>", 0]
      ],
      "limit": 3
    }
  ]'

Python 示例 ​

python
import requests

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

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

payload = [
    {
        "target": "example.com",
        "location_name": "United States",
        "language_name": "English",
        "filters": [
            ["metrics.organic.pos_1", "<>", 0],
            "or",
            ["metrics.organic.pos_2_3", "<>", 0],
        ],
        "limit": 3,
    }
]

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 payload = [
  {
    target: "example.com",
    location_name: "United States",
    language_name: "English",
    filters: [
      ["metrics.organic.pos_1", "<>", 0],
      "or",
      ["metrics.organic.pos_2_3", "<>", 0],
    ],
    limit: 3,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/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);
  });

PHP 示例 ​

php
<?php

$url = 'https://api.seermartech.cn/v3/dataforseo_labs/google/relevant_pages/live';

$payload = [
    [
        'target' => 'example.com',
        'location_name' => 'United States',
        'language_name' => 'English',
        'filters' => [
            ['metrics.organic.pos_1', '<>', 0],
            'or',
            ['metrics.organic.pos_2_3', '<>', 0],
        ],
        'limit' => 3,
    ],
];

$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($payload, JSON_UNESCAPED_UNICODE),
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if (($result['status_code'] ?? null) === 20000) {
    print_r($result);
} else {
    echo '请求失败：' . ($result['status_message'] ?? '未知错误');
}

响应示例 ​

json
{
  "version": "0.1.20240514",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "4.1423 sec.",
  "cost": 0.0742,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": " ಒಂದು-task-uuid",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "4.1423 sec.",
      "cost": 0.0742,
      "result_count": 1,
      "path": [
        "v3",
        "dataforseo_labs",
        "google",
        "relevant_pages",
        "live"
      ],
      "data": {
        "api": "dataforseo_labs",
        "function": "relevant_pages",
        "se_type": "google",
        "target": "example.com",
        "language_name": "English",
        "location_code": 2840,
        "filters": [
          ["metrics.organic.pos_1", "<>", 0],
          "or",
          ["metrics.organic.pos_2_3", "<>", 0]
        ],
        "limit": 3
      },
      "result": [
        {
          "se_type": "google",
          "target": "example.com",
          "location_code": 2840,
          "language_code": "en",
          "total_count": 120,
          "items_count": 3,
          "items": [
            {
              "se_type": "google",
              "page_address": "https://example.com/page",
              "metrics": {
                "organic": {
                  "pos_1": 5,
                  "pos_2_3": 12,
                  "pos_4_10": 28,
                  "pos_11_20": 35,
                  "etv": 15420.5,
                  "count": 80,
                  "estimated_paid_traffic_cost": 28600.0,
                  "is_new": 3,
                  "is_up": 8,
                  "is_down": 2,
                  "is_lost": 1
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

> 示例中的 id 用于展示字段结构，响应会返回符合 UUID 格式的任务标识。生产环境应根据 status_code 和 status_message 处理异常。

实用场景 ​

  • 识别高价值页面：按 metrics.organic.etv 和排名分布筛选页面，优优化能够带来较大自然流量的 URL。
  • 定位排名下滑页面：通过 is_down 和 is_lost 发现排名下降或丢失的页面，及时开展更新和技术排查。
  • 分析竞争域名的页面结构：批量获取目标域名的页面与排名数据，评估竞争对手的流量和布局。
  • 挖掘精选摘要机会：查看 featured_snippet 数据，识别已经接近精选摘要排名区间的页面，制定结构化优化方案。
  • 规划付费与自然流量预算：结合 etv 与 estimated_paid_traffic_cost，估算通过广告替代或补自然搜索流量所需的预算。

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

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