| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| appkey | string | 否 | 无 | 咕咕数据开发者中心分配的 APPKEY。 AppKey 整体必填;在本操作已声明支持的鉴权位置任选一个提供,本位置无需重复填写。多处填写时须一致。 |
| runId | string | 是 | 无 | 观测任务 ID。 |
application/json。| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | |
| runId | string | |
| reportId | string | |
| state | string | |
| forceRefresh | boolean | |
| creditCost | integer | 处理中为预占额度,终态为成功组合实际额度。新购额度包及订阅按此结算,失败组合释放;旧调用包按原创建次数计费。 |
| tasksTotal | integer | |
| tasksSucceeded | integer | |
| tasksFailed | integer | |
| metrics | 见响应定义 | |
| errorSummary | object[] | |
| createdAt | string | |
| updatedAt | string | |
| completedAt | string / null |
metrics.bestRank:本次观测中品牌匹配项的最佳排名,包括域名或品牌名、别名匹配。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,搜索结果通过任务结果接口读取。