搜索可见性报告列表

搜索可见性报告列表。新购额度包按全部关键词与来源组合相加：Google/Bing 的 Top10/20/50 各消耗 1/2/5 额度，Baidu 各消耗 10/20/50；Google 高级操作符乘以 5。年付含120,000 credits，月付含10,000 credits；读取免费。旧调用包创建报告或任务各计1次。

当前接口契约

接口详情：https://www.gugudata.com/api/details/search-visibility

功能说明

年度套餐 2999 元/年，包含 120,000 credits/年；

支持 Google、Bing、Baidu 多搜索来源的关键词排名观测；

支持 Top10、Top20、Top50 三种观测深度，按深度折算 credits；

返回可见性评分、最佳排名、Top10/Top20 覆盖率和来源覆盖率；

支持品牌别名和竞品域名配置，输出品牌匹配和竞品差距；

报告创建后自动发起首个观测任务，后续可手动重跑并分页查询结果；

新购额度包按搜索组合计费，读取免费；旧调用包保留原计次权益；

请求参数

参数	类型	必填	默认值	说明
appkey	string	否	无	咕咕数据开发者中心分配的 APPKEY。建议通过 X-GUGUDATA-APPKEY、X-API-Key 或 Authorization: Bearer 传递；也兼容 Query 参数 appkey。 AppKey 整体必填；在本操作已声明支持的鉴权位置任选一个提供，本位置无需重复填写。多处填写时须一致。
brand	string	是	无	品牌或产品名称，长度 1-120。用于匹配标题、摘要和结果链接中的品牌信号。
domain	string	是	无	需要观测的主域名，长度 1-255。可传 gugudata.com 或 https://www.gugudata.com，系统会按主域名规范化。
queries	array	是	无	搜索关键词，1-50 个，每个不超过 700 字符。创建报告含首次观测；额度按所有关键词与来源组合相加。
sources	array	是	无	搜索来源，1-3 个；支持 google_web、bing_web、baidu_web。预占 credits 上限 = 关键词数量 × 各搜索来源单次消耗之和；终态仅结算成功组合。Google/Bing 在 maxRank=10/20/50 时分别消耗 1/2/5 credits；Baidu 在 maxRank=10/20/50 时分别消耗 10/20/50 credits。Google 关键词包含 site:、intitle:、filetype: 等高级搜索操作符时，该组合额度乘以 5。
displayName	string	否	无	报告显示名称，便于在列表中识别，不传时可由业务侧使用 brand/domain 展示。
aliases	array	否	无	品牌别名列表，最多 20 个；用于补充匹配英文名、简称、产品名等品牌信号。
competitors	array	否	无	竞品域名定义列表，最多 10 个；每项支持 domain、name、aliases，用于计算竞品排名和差距。
locale	string	否	无	语言区域提示，如 zh-CN、en-US。不同搜索来源会尽量按该提示观测。
region	string	否	无	地域提示，如 CN、US、HK。不同地域的排名可能不同。
maxRank	integer	否	20	观测排名深度，仅支持 10、20、50，默认 20。Google/Bing 分别消耗 1/2/5 credits，Baidu 分别消耗 10/20/50 credits。
includeRawResponse	boolean	否	false	是否在问题排查场景保留扩展返回引用。普通业务接入建议保持 false。
pageSize	integer	否	20	每页数量；0 使用默认值 20。
pageToken	string	否	无	分页令牌。
filter	string	否	无	过滤表达式。报告列表支持 brand/domain；任务列表支持 state；结果列表支持 source/query。
orderBy	string	否	无	排序表达式，如 createdAt desc、updatedAt desc、checkedAt desc。

正常响应字段

字段	类型	说明
name	string	报告资源名，格式为 searchVisibilityReports/{reportId}。
reportId	string	报告 ID，后续查询报告、创建观测任务时使用。
displayName	string	报告显示名称。
brand	string	品牌或产品名称。
domain	string	需要观测的主域名，系统会按规范域名返回。
aliases	array	品牌别名列表。
competitors	array	竞品定义列表，包含 domain、name、aliases。
queries	array	报告内需要持续观测的搜索关键词。
sources	array	搜索来源列表，支持 google_web、bing_web、baidu_web。
locale	string	语言区域提示，如 zh-CN、en-US。
region	string	地域提示，如 CN、US。
maxRank	integer	观测排名深度，仅支持 10、20、50。
latestRunId	string	最近一次观测任务 ID。创建报告时会自动创建首个观测任务。
latestRunStatus	string	最近一次观测任务状态，可能为 PENDING、RUNNING、SUCCEEDED、FAILED、PARTIALLY_FAILED、CANCELLED。
latestMetrics	object	最近一次观测任务聚合指标，任务完成前可能为空对象。
createdAt	string	报告创建时间，UTC RFC3339 格式。
updatedAt	string	报告最近更新时间，UTC RFC3339 格式。

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

搜索观测资源。

Bodyapplication/json

示例

{
    "nextPageToken": "string",
    "reports": [
        {
            "queries": [
                "string"
            ],
            "createdAt": "2019-08-24T14:15:22.123Z",
            "aliases": [
                "string"
            ],
            "updatedAt": "2019-08-24T14:15:22.123Z",
            "maxRank": 10,
            "competitors": [
                {
                    "name": "string",
                    "domain": "string",
                    "aliases": [
                        "string"
                    ]
                }
            ],
            "domain": "string",
            "region": "string",
            "latestRunStatus": "string",
            "latestRunId": "string",
            "name": "string",
            "reportId": "string",
            "sources": [
                "string"
            ],
            "latestMetrics": {},
            "locale": "string",
            "displayName": "string",
            "brand": "string"
        }
    ]
}

🟠400INVALID_ARGUMENT

🟠401UNAUTHENTICATED

🟠403PERMISSION_DENIED

🟠404NOT_FOUND

🟠429RESOURCE_EXHAUSTED

🔴500INTERNAL

🔴503UNAVAILABLE

当前接口契约#

功能说明#

请求参数#

正常响应字段#

请求参数

请求示例代码

返回响应

当前接口契约

功能说明

请求参数

正常响应字段