OKFrontier Event API v2

实时地缘事件情报 API — 事件流 · 社交信号 · 新闻标题 · 预测市场 · 实体档案

715+

追踪实体

5min

刷新频率

48h

数据窗口

API 端点

认证 1. 简报概览 2. 事件流 3. 推文流 4. 新闻标题流 5. 预测市场 6. 实体档案增量拉取指南错误处理 SDK 示例

认证

所有 API 请求需要在 Header 中携带 API Key：

Authorization: Bearer YOUR_API_KEY

申请 API Key 请联系：api@capduck.com

Base URL： https://api.capduck.com/v2
当前支持 Topic：iran（伊朗局势）

1. 简报概览

GET /v2/event/{topic}

AI 生成的多视角态势摘要 + 待决事项 + 近 24h 高影响事件

AI 摘要每 1 小时 更新一次，包含 4 个视角（伊朗/美国/以色列/地区）和 5 个待决问题。

curl -H "Authorization: Bearer YOUR_KEY" \
  https://api.capduck.com/v2/event/iran

2. 事件流

GET /v2/event/{topic}/events

结构化事件时间线，含影响力评分、分类、信源详情和原始链接

查询参数

参数	类型	默认	说明
`since`	ISO 8601	48h前	起始时间，基于 published_at
`limit`	integer	50	返回条数，最大 200
`impact`	integer	0	最低影响力分数 (1-10)
`category`	string	all	CONFLICT / DIPLOMACY / POLITICS / ECONOMY / PROTESTS
`lang`	string	all	`translated` = 仅返回已翻译条目

# 近24h 高影响冲突事件（仅已翻译）
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.capduck.com/v2/event/iran/events?impact=8&category=CONFLICT&lang=translated"

事件对象字段

字段	类型	说明
`id`	string	唯一标识 (UUID)，用于去重
`impact`	integer	影响力 1-10，≥7 为高影响
`category`	string	事件分类
`sentiment`	string	NEGATIVE / POSITIVE / NEUTRAL / MIXED
`title`	string	英文标题
`title_zh`	string?	中文标题（impact≥7 翻译）
`summary`	string	英文摘要
`summary_zh`	string?	中文摘要
`source_details`	array	信源列表：名称、分类、平台、原始链接
`published_at`	ISO 8601	事件发生时间
`translated`	boolean	是否已翻译

3. 推文流

GET /v2/event/{topic}/tweets

715+ 被追踪实体的社交媒体信号，含作者分类和互动数据

查询参数

参数	类型	默认	说明
`since`	ISO 8601	48h前	起始时间
`limit`	integer	50	最大 200
`category`	string	all	作者分类：OSINT Accounts / News Agencies / Journalists / Government & Military / Think Tanks
`lang`	string	all	`translated` = 仅已翻译

推文对象字段

字段	类型	说明
`id`	string	Tweet ID（用于去重）
`author_name`	string	作者名称
`author_handle`	string	@用户名
`author_category`	string	作者实体分类
`text`	string	英文原文
`text_zh`	string?	中文翻译
`retweets`	integer	转发数
`likes`	integer	点赞数
`url`	string	X/Twitter 原始链接
`published_at`	ISO 8601	发布时间

4. 新闻标题流

GET /v2/event/{topic}/newsheader

27 个 Telegram 新闻频道的实时内容，含图片/视频和原始链接

查询参数

参数	类型	默认	说明
`since`	ISO 8601	48h前	起始时间
`limit`	integer	50	最大 200
`lang`	string	all	`translated` = 仅已翻译

新闻对象字段

字段	类型	说明
`id`	string	唯一标识
`channel_name`	string	频道名称
`channel_category`	string	频道实体分类
`caption`	string	原文内容
`caption_zh`	string?	中文翻译
`content_type`	string	image / video / text
`media_url`	string?	媒体文件 URL
`original_url`	string	Telegram 原始链接
`published_at`	ISO 8601	发布时间

5. 预测市场

GET /v2/event/{topic}/polymarket

Polymarket 预测市场数据，含当前概率、趋势和历史价格序列

预测市场对象字段

字段	类型	说明
`event`	string	事件标题 (EN)
`event_zh`	string	事件标题 (ZH)
`url`	string	Polymarket 页面链接
`conditions[].label`	string	条件标签
`conditions[].yes_price`	float	当前 Yes 概率 (0-1)
`conditions[].history`	array	价格历史：{t: unix, p: price}

6. 实体档案

GET /v2/event/{topic}/entities

715+ 被追踪信息源的实体数据库，支持分类浏览和模糊搜索

查询参数

参数	类型	默认	说明
`category`	string	all	分类筛选
`q`	string	-	模糊搜索名称和描述
`limit`	integer	50	最大 500

实体分类

分类	数量
News Agencies	440
Think Tanks / Policy Organizations	97
Academics/Researchers	30
Journalists	26
Political Figures	21
International Organizations	18
Iranian State/Government	10
OSINT Accounts	10
Government & Military	7

增量拉取指南

使用 since 参数 + id 去重实现增量数据拉取：

# 1. 首次拉取
GET /v2/event/iran/events?limit=100

# 2. 记录最新 published_at
last_time = response.data[-1].published_at

# 3. 下次拉取（增量）
GET /v2/event/iran/events?since={last_time}

# 4. 用 id 去重（防边界重复）

注意： 数据窗口为 48 小时，超出自动清理。翻译是异步的，使用 lang=translated 确保只获取已翻译条目。

错误处理

HTTP 状态	错误码	说明
401	`UNAUTHORIZED`	API Key 无效或缺失
403	`FORBIDDEN`	Key 无权访问该 topic
404	`NOT_FOUND`	端点或 topic 不存在
429	`RATE_LIMITED`	超出频率限制
500	`INTERNAL_ERROR`	服务端错误

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

SDK 示例

Python

import requests

BASE = "https://api.capduck.com/v2/event/iran"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}

# 获取简报
briefing = requests.get(BASE, headers=HEADERS).json()

# 增量拉取高影响事件
events = requests.get(f"{BASE}/events", headers=HEADERS, params={
    "impact": 8,
    "since": "2026-03-30T00:00:00Z",
    "lang": "translated",
}).json()

# OSINT 推文
tweets = requests.get(f"{BASE}/tweets", headers=HEADERS, params={
    "category": "OSINT Accounts",
    "limit": 50,
}).json()

JavaScript

const BASE = 'https://api.capduck.com/v2/event/iran';
const headers = { 'Authorization': 'Bearer YOUR_KEY' };

// 获取简报
const briefing = await fetch(BASE, { headers }).then(r => r.json());

// 事件流
const events = await fetch(
  `${BASE}/events?impact=8&lang=translated`,
  { headers }
).then(r => r.json());