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

# 来源分析

> 来源域名的丰富分析数据：类别分布、表现趋势及机会点。

来源分析端点返回来源域名活动的全面视图 —— 总体统计、类别分布、热门域名的每日表现，以及您的品牌尚未被提及的机会域名。

## 获取来源分析

```
GET /projects/{project_id}/sources/analytics
```

返回来源统计、类别分布、前 10 个域名的表现图、按引用次数排名的前 20 个域名，以及机会域名。

### 路径参数

| 参数           | 类型            | 描述    |
| ------------ | ------------- | ----- |
| `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}/sources/analytics?duration_days=7" \
      -H "X-API-Key: tk_live_..."
    ```
  </Tab>

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

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

### 响应

```json theme={null}
{
  "success": true,
  "data": {
    "stats": {
      "total_sources": 245,
      "total_citations": 1832
    },
    "category_breakdown": {
      "corporate": 12.5,
      "editorial": 35.2,
      "institutional": 18.0,
      "reference": 22.1,
      "ugc": 8.7,
      "other": 3.5
    },
    "performance_chart": {
      "dates": ["2026-02-28", "2026-03-01", "2026-03-02"],
      "series": [
        {
          "domain": "techcrunch.com",
          "values": [8.2, 7.5, 9.1]
        },
        {
          "domain": "forbes.com",
          "values": [6.0, 5.8, 6.3]
        }
      ]
    },
    "top_domains": [
      {
        "source_id": "s1t2u3v4-...",
        "domain": "techcrunch.com",
        "category": 1,
        "reference_count": 127
      },
      {
        "source_id": "w5x6y7z8-...",
        "domain": "forbes.com",
        "category": 1,
        "reference_count": 89
      }
    ],
    "opportunities": [
      {
        "domain": "reddit.com",
        "citation_count": 45,
        "category": 4,
        "category_name": "ugc"
      }
    ]
  }
}
```

### SourcesAnalyticsResponse 字段

| 字段                   | 类型                      | 描述               |
| -------------------- | ----------------------- | ---------------- |
| `stats`              | SourcesStats            | 来源和引用计数总计        |
| `category_breakdown` | CategoryBreakdown       | 按域名类别的引用分布（百分比）  |
| `performance_chart`  | SourcePerformanceChart  | 前 10 个域名的每日引用占比  |
| `top_domains`        | SourceDomainResponse\[] | 按引用次数排名的前 20 个域名 |
| `opportunities`      | SourceOpportunity\[]    | 您的品牌未被提及的高引用量域名  |

### SourcesStats 字段

| 字段                | 类型      | 描述               |
| ----------------- | ------- | ---------------- |
| `total_sources`   | integer | 日期范围内被引用的不同来源域名数 |
| `total_citations` | integer | 所有来源的总引用次数       |

### CategoryBreakdown 字段

每个字段都是属于该类别的引用占总引用的百分比（0--100）。

| 字段              | 类别 ID | 描述                 |
| --------------- | ----- | ------------------ |
| `corporate`     | 0     | 公司及品牌网站            |
| `editorial`     | 1     | 新闻媒体及出版物           |
| `institutional` | 2     | 政府、学术及非营利机构网站      |
| `reference`     | 3     | 百科全书、文档及知识库        |
| `ugc`           | 4     | 用户生成内容（论坛、社交媒体、问答） |
| `other`         | 5     | 未分类的域名             |

### SourcePerformanceChart 字段

| 字段       | 类型                   | 描述                         |
| -------- | -------------------- | -------------------------- |
| `dates`  | string\[]            | 已排序的日期字符串，格式为 `YYYY-MM-DD` |
| `series` | DomainChartSeries\[] | 每个前 10 名域名对应一项             |

### DomainChartSeries 字段

| 字段       | 类型       | 描述                               |
| -------- | -------- | -------------------------------- |
| `domain` | string   | 域名                               |
| `values` | float\[] | 与 `dates` 对齐的每日引用占比，作为当日所有引用的百分比 |

### SourceDomainResponse 字段

| 字段                | 类型            | 描述                            |
| ----------------- | ------------- | ----------------------------- |
| `source_id`       | string (UUID) | 来源 ID                         |
| `domain`          | string        | 域名                            |
| `category`        | integer       | 域名类别 ID（参见 CategoryBreakdown） |
| `reference_count` | integer       | 日期范围内的总引用次数                   |

### SourceOpportunity 字段

| 字段               | 类型      | 描述             |
| ---------------- | ------- | -------------- |
| `domain`         | string  | 域名             |
| `citation_count` | integer | 您的品牌未被提及的总引用次数 |
| `category`       | integer | 域名类别 ID        |
| `category_name`  | string  | 人类可读的类别名称      |

<Note>
  机会点是被引用 3 次或更多次但您的品牌未被提及（或 `mentioned = false`）的域名。这些代表您可以重点投放品牌内容、提升可见度的来源。
</Note>

### 应用场景

<Tabs>
  <Tab title="类别分布">
    使用 `category_breakdown` 了解 AI 服务商最常引用的来源类型。较高的 `ugc` 百分比可能意味着您可以在社区平台上提升品牌存在感。
  </Tab>

  <Tab title="表现趋势">
    将 `performance_chart` 绘制为堆叠面积图或折线图，查看热门域名的引用占比如何随时间变化。
  </Tab>

  <Tab title="识别机会点">
    `opportunities` 数组列出了您的品牌缺席但流量较高的来源。优先对接这些域名以提升您在 AI 回复中的可见度。
  </Tab>
</Tabs>