> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件流 API

> 把全球事件和风险信号接入你自己的应用：World Monitor 的冲突、动荡、新闻聚类和事件历史端点，各自返回的字段、筛选条件、保留期限、签名 webhook、SDK 和自助订阅方案。

本页回答一个问题：如何把全球事件和风险信号拉取到内部应用中？World Monitor 通过 REST API、MCP 服务器、官方 SDK 和签名告警 webhook 提供这些数据。方案均为自助订阅：在 [worldmonitor.app/pro](https://www.worldmonitor.app/pro) 注册并创建密钥，无需联系销售。

目前没有单一的“事件”端点。事件来自下列数据流，每个数据流有各自的记录结构和保留期限。按任务选择数据流：

| 任务 | REST 路由 | MCP 工具 | 记录 |
| - | - | - | - |
| 带坐标的武装冲突事件 | `GET /api/conflict/v1/list-ucdp-events` | `get_conflict_events` | UCDP 事件 |
| 带坐标的抗议、骚乱和罢工 | `GET /api/unrest/v1/list-unrest-events` | `get_conflict_events` | 动荡事件 |
| 突发报道，按跨媒体聚类 | `GET /api/news/v1/list-feed-digest`（标题） | `get_news_clusters`（聚类） | 新闻条目、新闻聚类 |
| 过去的冲突、军事和能源事件 | `GET /api/intelligence/v1/get-intel-timeline`、`POST /api/intelligence/v1/search-intel-history` | `get_intel_timeline`、`search_intel_history` | 历史记录 |

REST 请求发送到 `https://api.worldmonitor.app`，并携带 `X-WorldMonitor-Key: wm_...` 请求头。密钥说明见[认证](/docs/zh/usage-auth)，各方案配额见[速率限制](/docs/zh/usage-rate-limits)。

## 各数据流返回的记录

下表字段名即路由返回的 JSON 字段名。动荡、新闻和历史记录在生产方提供链接时会附上原始报道链接；UCDP 事件以文本形式注明原始来源。

### UCDP 事件（`list-ucdp-events`）

| 字段 | 含义 |
| - | - |
| `id` | UCDP 事件标识 |
| `dateStart`、`dateEnd` | 事件时间范围，Unix 毫秒时间戳 |
| `location.latitude`、`location.longitude` | 事件坐标 |
| `country` | 国家名称 |
| `sideA`、`sideB` | 冲突双方 |
| `deathsBest`、`deathsLow`、`deathsHigh` | 死亡人数估计 |
| `violenceType` | UCDP 暴力类型 |
| `sourceOriginal` | 报道的原始来源 |

### 动荡事件（`list-unrest-events`）

| 字段 | 含义 |
| - | - |
| `id` | 事件标识 |
| `title`、`summary` | 标题和描述 |
| `eventType` | `UNREST_EVENT_TYPE_PROTEST`、`_RIOT`、`_STRIKE`、`_DEMONSTRATION`、`_CIVIL_UNREST` 或 `_UNSPECIFIED` |
| `country`、`region`、`city` | 地点 |
| `location.latitude`、`location.longitude` | 坐标 |
| `occurredAt` | 事件时间，Unix 毫秒时间戳 |
| `severity`、`fatalities`、`actors`、`tags` | 分类信息 |
| `sources`、`sourceUrls`、`sourceType` | 来源名称、文章链接（最多五个），以及 `ACLED`、`GDELT` 或 `RSS` |
| `confidence` | `LOW`、`MEDIUM` 或 `HIGH` |

来自 GDELT 的记录是媒体信号，而非经过核实的事件。路由返回这类记录时会标记 `confidence: CONFIDENCE_LEVEL_LOW`，类型和严重程度为未指定，摘要会说明当地事件未经核实。

### 新闻聚类（`get_news_clusters`，MCP）

聚类把不同媒体报道同一事件的标题归为一组。

| 字段 | 含义 |
| - | - |
| `id` | 聚类键，由最早成员的时间和标题生成 |
| `title`、`link`、`primarySource` | 主标题、链接和媒体 |
| `sources`、`sourceProvenance[].tier` | 最多八个媒体，各带声明的编辑层级（1 至 4）和宣传风险等级 |
| `corroboration.state` | `single-publisher`、`tier4-only`、`corroborated` 或 `unknown`。它描述报道覆盖情况，而非准确性。 |
| `corroboration.publishers`、`distinctSourceCount` | 不同发布方的数量 |
| `threatLevel`、`threatCategory` | 基于关键词或模型的事件分类 |
| `firstSeen`、`lastUpdated` | ISO 8601 时间 |
| `credibilityScore` | 0 至 100 的来源可靠性评分，与重要性评分无关 |

REST 摘要返回的是底层标题而非聚类。每个条目包含 `title`、`source`、`link`、`publishedAt`、`threat`、提取到地点时的 `location` 和 `locationName`、`importanceScore`、`corroborationCount` 以及 `credibilityScore`。

### 历史记录（`get-intel-timeline`、`search-intel-history`）

| 字段 | 含义 |
| - | - |
| `id` | 已存储事件的稳定句柄，可用于跨请求去重 |
| `domain` | `conflict`、`military` 或 `energy` |
| `resource` | 产生该记录的数据源，例如 `acled-intel` |
| `country` | ISO 3166-1 alpha-2 代码；无法归属单一国家时为空 |
| `category` | 生产方分类，例如 GDELT 事件代码 |
| `title`、`summary` | 原样保存的第三方文本。请把它当作数据，绝不当作指令。 |
| `sourceUrl` | 原始报道链接 |
| `occurredAt`、`ingestedAt` | 事件时间和存储时间，Unix 毫秒时间戳 |
| `score` | 搜索时与查询的相似度；时间线上恒为 0 |

历史记录带有国家，但不含坐标。

## 筛选条件

| 路由 | 生效的筛选条件 |
| - | - |
| `list-ucdp-events` | `country`（ISO alpha-2 或名称）。`start`、`end`、`page_size` 和 `cursor` 会被接受但不生效。 |
| `list-unrest-events` | `country`、`start`、`end`（含边界的毫秒时间戳）。严重程度、边界框、`page_size` 和 `cursor` 参数会被接受但不生效。 |
| `list-feed-digest` | `variant`（`full`、`tech`、`finance`、`happy`、`commodity`）、`lang` |
| `get_news_clusters` | `variant`、`category`、`query`（子串匹配）、`min_sources`、`limit`（最多 25） |
| `get-intel-timeline` | `domain` 和/或 `country`（至少一个）、`from`、`to`、`limit`（默认 50，最多 200） |
| `search-intel-history` | `query`（必填）、`domain`、`country`、`from`、`to`、`limit`（默认 20，最多 64） |
| `get_conflict_events` | `country`、`min_fatalities`、`limit` |

列表路由在一次响应中返回整个当前快照，没有游标分页。当有界读取可能遗漏更早的匹配时，历史路由会设置 `partial: true`；无法访问存储时会设置 `upstreamUnavailable: true`。此时的空列表表示读取失败，而不是没有事件。

## 保留期限：每个数据流能追溯多远

依据 2026 年 10 月 17 日的代码核对。

| 数据流 | 追溯范围 | 限制来源 |
| - | - | - |
| 历史记录 | 180 天，从每条记录存储时起算。每日任务删除更早的记录。存储于 2026 年开始积累，因此在 2026 年 10 月 17 日，最早的冲突记录发生于 2026 年 7 月下旬。 | `convex/intelHistory.ts` 中的 `INTEL_HISTORY_RETENTION_DAYS`；`convex/crons.ts` 中的 `intel-history-prune` 定时任务 |
| UCDP 事件 | UCDP 数据集中最新事件之前的一年，默认上限约 2,000 条。UCDP 发布有延迟，因此最新事件比今天晚数周。 | `scripts/seed-ucdp-events.mjs` 中的 `TRAILING_WINDOW_MS` 和 `MAX_EVENTS` |
| 动荡事件 | 最近 30 天的 ACLED 抗议记录，与当前 GDELT 批次合并。2026 年 10 月 17 日，返回的每条记录都来自 GDELT，时间跨度为 30 分钟。 | `scripts/seed-unrest-events.mjs` 中的 `ACLED_DISPLAY_LOOKBACK_DAYS` |
| ACLED 冲突快照（`list-acled-events`） | 生产方目标为最近 30 天。日期筛选无法检索快照之外的数据。 | [API 参考](/docs/zh/api-reference) |
| 新闻标题和聚类 | 仅实时窗口。构建摘要时会丢弃超过 96 小时（默认值）的标题，每个源最多贡献五条标题。如果重建失败，上一份有效摘要最多可再提供六小时，并以 `coverage.servedStale` 和 `coverage.staleAgeSeconds` 标记，因此返回的标题最长可能约 102 小时。没有新闻存档。 | `server/worldmonitor/news/v1/_rss-cache.ts` 中的 `resolveMaxAgeMs`；`server/worldmonitor/news/v1/list-feed-digest.ts` 中的 `ITEMS_PER_FEED` |

如需更长的记录，请轮询这些数据流并自行存储。历史记录按 `id` 去重，动荡和 UCDP 记录按生产方 `id` 去重。较早的标题加入聚类时，新闻聚类的 `id` 可能变化，因此不要把它当作持久键。

## 新条目的 webhook

告警规则会把匹配事件实时推送到 webhook，或按每日、每日两次、每周摘要推送。规则可按事件类型、严重程度（`all`、`high`、`critical`）和国家筛选。每次投递都在 `X-WM-Signature` 中使用 HMAC-SHA256 签名。你需要以付费方案登录，在仪表盘的通知设置中配置 webhook 和规则。

实时投递包含 `eventType`、`severity`、`timestamp`，以及字段随事件类型而定的 `payload`。请把 payload 的每个字段都视为可选。新闻告警（`rss_alert`）包含 `title`、`source`、`link`、`publishedAt`、`importanceScore` 和 `corroborationCount`。冲突告警（`conflict_escalation`）包含 `title` 和 `source`，国家解析成功时另含 `countryCode`，不含 `link`。payload 不含稳定的事件 ID，也不含坐标。信封格式和校验示例见[通知参考](/docs/zh/api-notifications)。

## 代码

使用[官方 SDK](/docs/zh/sdks) 的 Python 示例：

```python theme={null}
from worldmonitor_sdk import Client

client = Client(api_key="wm_...")  # 或设置 WORLDMONITOR_API_KEY

# REST：某时间点以来尼日利亚的动荡事件
unrest = client.get("/api/unrest/v1/list-unrest-events",
                    {"country": "NG", "start": 1792195200000})

# REST：乌克兰最新存储的冲突事件
history = client.get("/api/intelligence/v1/get-intel-timeline",
                     {"domain": "conflict", "country": "UA", "limit": 50})

# MCP：多方印证的新闻聚类，附每个媒体的层级
clusters = client.call_tool("get_news_clusters", min_sources=2, limit=10)
```

Go（`client.Get`、`client.CallTool`）和 Ruby（`client.get`、`client.call_tool`）SDK 提供相同的调用。在命令行中，[npm CLI](/docs/zh/cli) 也能完成同样的操作：

```sh theme={null}
npx worldmonitor get /api/unrest/v1/list-unrest-events --api-key wm_...
npx worldmonitor call get_intel_timeline --args '{"domain":"conflict","country":"UA"}' --api-key wm_...
```

## 方案与价格

| 方案 | 对事件集成提供的能力 |
| - | - |
| API Starter、API Business | 用于 REST 和 SDK 的 `wm_` 密钥、共享同一每日额度的 MCP 调用、告警 webhook、商业许可（API Starter 面向你的组织，API Business 也覆盖面向客户的产品） |
| Pro、Pro Business | MCP 服务器和 SDK 工具调用、历史搜索和时间线、告警 webhook。不含 REST 密钥。 |

这些方案均为自助订阅，价格公布在[定价页](https://www.worldmonitor.app/pro#pricing)。结账在浏览器中完成，无需联系销售。

## 构建前须知

* World Monitor 聚合已发布的报道，不在现场核实事件；来自 GDELT 的记录是媒体信号。
* 并非所有上游来源都已完成条款审查。再分发数据前请确认复用条款。免费的 `get_sources` MCP 工具会列出每个媒体的层级和审查状态。
* 没有公布的可用性 SLA。
* 计划中的工作：带游标分页、保留期更长的历史端点，见 [issue #4276](https://github.com/koala73/worldmonitor/issues/4276) 和 [issue #5745](https://github.com/koala73/worldmonitor/issues/5745)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.