> ## 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 服务商筛选               |

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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_..."
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = client.get(f"/projects/{project_id}/overview", params={"duration_days": 7, "prompt_type": "active"})
    ```
  </Tab>

  <Tab title="Node.js（服务端）">
    ```javascript theme={null}
    const resp = await fetch(`${BASE}/projects/${projectId}/overview?duration_days=7&prompt_type=active`, { headers });
    ```
  </Tab>
</Tabs>

### 响应

```json theme={null}
{
  "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` 查询参数 |