| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| appkey | string | 否 | 无 | 咕咕数据开发者中心分配的 APPKEY。 AppKey 整体必填;在本操作已声明支持的鉴权位置任选一个提供,本位置无需重复填写。多处填写时须一致。 |
| resultId | string | 是 | 无 | 观测结果 ID。 |
application/json。| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | |
| resultId | string | |
| reportId | string | |
| runId | string | |
| query | string | |
| source | string | |
| checkedAt | string | |
| cacheHit | boolean | |
| metrics | object | |
| searchMetadata | object | |
| observedItems | object[] | |
| brandMatches | object[] | |
| competitorMatches | object[] |
{
"name": "searchVisibilityResults/svres_example",
"resultId": "svres_example",
"reportId": "svrpt_example",
"runId": "svrun_example",
"query": "gugudata api",
"source": "google_web",
"checkedAt": "2026-07-01T10:01:20Z",
"cacheHit": false,
"metrics": {
"visible": true,
"top10": true,
"top20": true,
"bestRank": 1,
"averageRankWithPenalty": 1,
"bestCompetitorRank": 5,
"competitorGap": 4,
"matchedUrlCount": 1,
"visibilityScore": 100
},
"searchMetadata": {},
"observedItems": [
{
"rank": 1,
"title": "咕咕数据 - 专业的数据提供商",
"url": "https://www.gugudata.com/",
"domain": "gugudata.com",
"snippet": "提供结构化数据接口、网站工具和自动化数据服务。",
"source": "google_web"
},
{
"rank": 5,
"title": "示例竞品",
"url": "https://example.com/",
"domain": "example.com",
"snippet": "示例竞品搜索结果。",
"source": "google_web"
}
],
"brandMatches": [
{
"rank": 1,
"url": "https://www.gugudata.com/",
"domain": "gugudata.com",
"registrableDomain": "gugudata.com",
"title": "咕咕数据 - 专业的数据提供商"
}
],
"competitorMatches": [
{
"rank": 5,
"url": "https://example.com/",
"domain": "example.com",
"registrableDomain": "example.com",
"title": "示例竞品",
"competitorDomain": "example.com",
"competitorName": "示例竞品"
}
]
}locale(语言区域提示)和 region(地域提示)。要比较不同地区,可分别创建报告,使用相同的品牌、域名、关键词、搜索来源和 maxRank,再按关键词和来源对照结果。比较同一地区的历史变化时,也应保持这些设置一致,并用 checkedAt 确认各条结果的实际观测时间。bestRank 是品牌排名,还是自有网站的排名?metrics.bestRank 是本条结果里品牌匹配项的最佳排名。系统会匹配配置的域名及其子域名,也会在标题、摘要和链接中匹配品牌名或别名,因 此第三方页面也可能计入。只统计自有网站时,可以按 brandMatches[].domain 筛选目标域名及所需子域名,再取最小的 rank。bestRank 是 null,算没上榜还是任务失败?visible=false 且 bestRank=null,表示这次在所选排名范围内未匹配到品牌。比如 maxRank=20 时,averageRankWithPenalty 会用 21 参与统计。观测是否失败应查看任务的 state 和 errorSummary。cacheHit=true 是什么意思?forceRefresh: true 会跳过短期结果复用,重新执行观测。结果中的 cacheHit=true 表示复用了已有观测,checkedAt 是该次采样的时间。创建新的观测任务按所购权益计费。runId 后,调用 GET /v1/searchVisibilityRuns/{runId}/results。每条明细对应一个关键词和一个搜索来源。响应的 nextPageToken 非空时,将它作为下一次请求的 pageToken,沿用同一任务和筛选、排序条件。令牌为空时,表示已读到最后一页。observedItems、brandMatches 和排名指标。正式接口需要对应的 AppKey,创建时返回报告和首个观测任务 ID,搜索结果通过任务结果 接口读取。