> ## 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.

# 可见度趋势

> 按竞争对手的时间序列可见度、情感分析和位置数据。

可见度趋势端点返回项目中每个活跃竞争对手的每日时间序列指标。可用于绘制品牌可见度、情感分析和位置随时间在不同 AI 服务商之间的变化情况。

## 获取可见度趋势

```
GET /projects/{project_id}/visibility
```

返回每个活跃竞争对手在所选 AI 服务商上的每日可见度、情感分析和位置值（取平均）。

### 路径参数

| 参数           | 类型            | 描述    |
| ------------ | ------------- | ----- |
| `project_id` | string (UUID) | 项目 ID |

### 查询参数

| 参数              | 类型      | 默认值 | 描述                 |
| --------------- | ------- | --- | ------------------ |
| `duration_days` | integer | `7` | 回溯天数               |
| `date_from`     | string  | --  | 起始日期（`YYYY-MM-DD`） |
| `date_to`       | string  | --  | 结束日期（`YYYY-MM-DD`） |
| `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}/visibility?duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

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

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

### 响应

```json theme={null}
{
  "success": true,
  "data": {
    "dates": ["2026-02-28", "2026-03-01", "2026-03-02", "2026-03-03"],
    "period": "2026-02-28 to 2026-03-03",
    "series": [
      {
        "competitor_id": "00000000-0000-0000-0000-000000000000",
        "name": "Acme Corp",
        "website": "https://acme.com",
        "icon_url": "https://logo.clearbit.com/acme.com",
        "is_own_brand": true,
        "visibility": [82.5, 85.0, 83.2, 86.1],
        "sentiment": [70.0, 72.0, 71.5, 73.0],
        "position": [1.8, 1.6, 1.9, 1.5]
      },
      {
        "competitor_id": "c1d2e3f4-...",
        "name": "Competitor A",
        "website": "https://competitor-a.com",
        "icon_url": "https://logo.clearbit.com/competitor-a.com",
        "is_own_brand": false,
        "visibility": [60.0, 62.5, null, 65.0],
        "sentiment": [55.0, 58.0, null, 60.0],
        "position": [3.2, 3.0, null, 2.8]
      }
    ]
  }
}
```

### VisibilityTrendsResponse 字段

| 字段       | 类型                  | 描述                                       |
| -------- | ------------------- | ---------------------------------------- |
| `dates`  | string\[]           | 已排序的日期字符串，格式为 `YYYY-MM-DD`               |
| `period` | string              | 人类可读的日期范围（例如 `2026-02-28 to 2026-03-03`） |
| `series` | CompetitorSeries\[] | 每个活跃竞争对手对应一项                             |

### CompetitorSeries 字段

| 字段              | 类型            | 可空  | 描述                                   |
| --------------- | ------------- | --- | ------------------------------------ |
| `competitor_id` | string (UUID) | No  | 竞争对手 ID                              |
| `name`          | string        | No  | 竞争对手品牌名称                             |
| `website`       | string        | No  | 竞争对手网站 URL                           |
| `icon_url`      | string        | Yes | 主要 logo URL                          |
| `is_own_brand`  | boolean       | No  | 如果这是您自己的品牌则为 `true`                  |
| `visibility`    | float\[]      | No  | 与 `dates` 对齐的每日可见度评分。无数据的日期为 `null`  |
| `sentiment`     | float\[]      | No  | 与 `dates` 对齐的每日情感分析评分。无数据的日期为 `null` |
| `position`      | float\[]      | No  | 与 `dates` 对齐的每日位置值。无数据的日期为 `null`    |

<Note>
  当同一天有多个 AI 服务商的数据时，会取平均值。`null` 表示当天该竞争对手没有收集到数据。
</Note>

### 应用场景

<Tabs>
  <Tab title="按时间绘制图表">
    将每个竞争对手作为一条线绘制在时间序列图上。`dates` 数组提供 x 轴标签，每个 series 的 `visibility`、`sentiment` 和 `position` 数组提供 y 轴值。
  </Tab>

  <Tab title="比较竞争对手">
    使用 `is_own_brand` 突出显示您的品牌与其他竞争对手的对比。比较趋势以查看您的可见度增长是否快于或慢于竞争对手。
  </Tab>

  <Tab title="按 AI 服务商筛选">
    传入 `?providers=chatgpt` 以隔离单个 AI 服务商的趋势，并比较其在不同平台上的表现。
  </Tab>
</Tabs>