Documentation Index
Fetch the complete documentation index at: https://docs.topify.ai/llms.txt
Use this file to discover all available pages before exploring further.
概览端点返回项目 GEO 表现的按搜索词摘要 —— 可见度、情感分析、位置，以及哪些竞争对手与您的品牌一同出现。可用于构建仪表盘或排行榜视图。
获取概览
GET /projects/{project_id}/overview
路径参数
| 参数 | 类型 | 描述 |
|---|
project_id | string (UUID) | 项目 ID |
查询参数
| 参数 | 类型 | 默认值 | 描述 |
|---|
duration_days | integer | 7 | 回溯天数 |
date_from | string | — | 起始日期（YYYY-MM-DD） |
date_to | string | — | 结束日期（YYYY-MM-DD） |
prompt_type | string | active | 按 active 或 suggested 进行筛选 |
providers | string | — | 以逗号分隔的 AI 服务商筛选 |
curl "https://topify-customer-api-production.up.railway.app/api/public/v1/projects/{project_id}/overview?duration_days=7&prompt_type=active" \
-H "X-API-Key: tk_live_..."
resp = client.get(f"/projects/{project_id}/overview", params={"duration_days": 7, "prompt_type": "active"})
const resp = await fetch(`${BASE}/projects/${projectId}/overview?duration_days=7&prompt_type=active`, { headers });
{
"success": true,
"data": {
"items": [
{
"prompt_id": "e5f6a7b8-...",
"content": "What is the best project management tool?",
"prompt_type": "active",
"created_at": "2026-01-15T10:30:00+00:00",
"topic_id": "t1u2v3w4-...",
"topic_name": "Product comparisons",
"visibility": 85.0,
"sentiment": 72.0,
"position": 2.3,
"volume": 2400,
"intent": "commercial",
"cvr": 45.0,
"competitors_mentioned": [
{
"competitor_id": "c1d2e3f4-...",
"name": "Competitor A",
"mention_count": 15,
"icon_url": "https://logo.clearbit.com/competitor-a.com",
"icon_urls": [
"https://logo.clearbit.com/competitor-a.com",
"https://www.google.com/s2/favicons?domain=competitor-a.com&sz=64"
]
}
]
}
]
}
}
OverviewPromptItem 字段
| 字段 | 类型 | 可空 | 描述 |
|---|
prompt_id | string (UUID) | No | 搜索词 ID |
content | string | No | AI 搜索查询文本 |
prompt_type | string | No | active、pending、suggested、inactive 或 url_recommended |
created_at | string (ISO 8601) | No | 搜索词创建时间 |
topic_id | string (UUID) | Yes | 该搜索词所属的主题 |
topic_name | string | Yes | 主题显示名称 |
visibility | float | No | 日期范围内的品牌可见度百分比（0—100） |
sentiment | float | No | 日期范围内的平均品牌情感分析评分 |
position | float | No | 在回复中的平均品牌位置 |
volume | integer | Yes | 此搜索词的预估 AI 搜索需求量 |
intent | string | Yes | informational、commercial、navigational 或 transactional |
cvr | float | Yes | 内容可见度率（百分比） |
competitors_mentioned | OverviewCompetitorMention[] | No | 在此搜索词的回复中出现的竞争对手 |
OverviewCompetitorMention 字段
| 字段 | 类型 | 可空 | 描述 |
|---|
competitor_id | string (UUID) | No | 竞争对手 ID |
name | string | No | 出现时所用的竞争对手品牌名称 |
mention_count | integer | No | 此搜索词回复中的总提及次数 |
icon_url | string | Yes | 主要 logo URL |
icon_urls | string[] | No | 多个 logo URL 来源 |
| 状态 | 详情 | 原因 |
|---|
400 | prompt_type must be 'active' or 'suggested' | 无效的 prompt_type 查询参数 |
