# Orange Hitick Trump Statements API 文档

这份文档用于开发者通过 HTTP API 查询 Orange Hitick 收集的特朗普公开言论和白宫正式内容。

## 1. 服务信息

- HTTP 接口：`GET /api/v1/trump/statements`
- HTTP 鉴权方式：请求头 `X-API-Token`
- 返回包装：Orange Hitick 统一 `ApiResponse`
- 模型标识：`TrumpStatements`
- 计费说明：每次成功查询后计费一次
- 默认范围：最近 7 天
- 默认条数：`10`，最大 `100`

HTTP API 的统一返回结构：

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

## 2. 数据来源

当前公开内容来自以下三类来源：

| `source_type` | 来源 | 内容语义 |
| --- | --- | --- |
| `TRUTH_SOCIAL` | Trump Truth Social 公开内容 | 特朗普在 Truth Social 发布的内容 |
| `WHITE_HOUSE_PRESIDENTIAL_ACTION` | 白宫 Presidential Actions | 白宫发布的总统行动、行政令等正式内容 |
| `WHITE_HOUSE_NEWS` | 白宫 News | 白宫发布的新闻稿、讲话稿和相关正式内容 |

白宫正式行动和新闻稿应根据 `source_type`、标题、正文和来源链接准确描述。

## 3. HTTP 查询 API

```http
GET /api/v1/trump/statements
```

请求头：

```http
X-API-Token: your_token_value
```

查询参数：

- `startTime`：可选，开始时间，必须是带时区的 ISO-8601 时间；不传时默认为 `endTime - 7 天`
- `endTime`：可选，结束时间，必须是带时区的 ISO-8601 时间；不传时默认为当前时间
- `limit`：可选，默认 `10`；必须大于 `0`，超过 `100` 时按 `100` 处理

时间范围采用左闭右开区间 `[startTime, endTime)`。返回结果按 `published_at` 倒序排列；发布时间相同时按记录 ID 倒序排列。

查询默认最近 7 天、返回 3 条：

```bash
curl -sS 'https://api.hitick.top/api/v1/trump/statements?limit=3' \
  -H 'X-API-Token: your_token_value'
```

查询指定时间范围：

```bash
curl -sS \
  'https://api.hitick.top/api/v1/trump/statements?startTime=2026-08-01T00%3A00%3A00%2B08%3A00&endTime=2026-08-08T00%3A00%3A00%2B08%3A00&limit=20' \
  -H 'X-API-Token: your_token_value'
```

## 4. 返回结构

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "start_time": "2026-08-01T00:00:00+08:00",
    "end_time": "2026-08-08T00:00:00+08:00",
    "count": 1,
    "items": [
      {
        "id": 1001,
        "subject_tag": "trump",
        "source_type": "WHITE_HOUSE_NEWS",
        "publisher": "The White House",
        "title": "Remarks by President Trump ...",
        "content_markdown": "<p>Article body...</p>",
        "source_url": "https://www.whitehouse.gov/remarks/...",
        "aggregation_url": null,
        "media_urls": [],
        "categories": [],
        "metadata": {
          "rss_guid": "example-guid"
        },
        "published_at": "2026-08-05T12:00:00+08:00"
      }
    ]
  }
}
```

字段说明：

- `start_time`：本次实际查询的开始时间，统一转换为 `Asia/Shanghai`
- `end_time`：本次实际查询的结束时间，统一转换为 `Asia/Shanghai`
- `count`：本次实际返回的记录数
- `items`：言论或报道数组
- `id`：记录 ID
- `subject_tag`：主题标签，当前固定为 `trump`
- `source_type`：数据来源类型，取值见“数据来源”章节
- `publisher`：发布机构或媒体名称
- `title`：标题；部分 Truth Social 内容可能没有独立标题
- `content_markdown`：正文内容，可能保留来源中的原始格式
- `source_url`：原始内容地址
- `aggregation_url`：聚合来源地址；没有聚合来源时为空
- `media_urls`：正文关联的媒体资源 URL 数组
- `categories`：RSS 分类数组
- `metadata`：来源相关的附加元数据，不建议依赖其中未明确约定的字段
- `published_at`：原始内容发布时间

## 5. API 调用建议

- 用户没有指定时间范围时，使用默认最近 7 天；不要自行扩展到无限历史范围
- 用户指定自然语言时间时，转换为带时区的 ISO-8601 时间后再调用
- 优先依据 `source_type`、`publisher` 和 `source_url` 说明信息来自哪里
- `TRUTH_SOCIAL` 可以描述为特朗普在 Truth Social 发布的内容
- 白宫 Presidential Actions、白宫 News 与特朗普个人社交媒体发言应分别描述
- 引用或总结前检查 `published_at`，避免把旧内容表述为最新消息
- 如果 `count=0`，说明指定范围内当前没有可返回的记录，不要虚构结果
- 返回内容可能很长，先根据标题、来源和时间筛选，再按用户问题提取相关正文

## 6. 参数错误与使用限制

- `startTime` 或 `endTime` 不符合带时区 ISO-8601 格式时，返回参数错误
- `startTime` 必须早于 `endTime`
- `limit` 必须大于 `0`
- 数据不保证覆盖所有特朗普公开言论和白宫正式内容
- 来源页面可能受站点故障或访问限制影响
- 该接口用于信息检索与 Agent 分析，引用时仍应保留原始来源和发布时间