GlobalPulse API

什么是 GlobalPulse API

GlobalPulse API 是我们将客户端展示的所有数据通过标准 HTTP 接口对外提供的服务。这意味着你可以：

• 把我们的【涨跌家数】数据接入你自己的量化策略
• 把我们的【AI 盘后扫描】嵌入到企业内部 Slack / 钉钉机器人
• 用 Python 抓取每日新闻流，做自己的舆情分析
• 构建基于 GlobalPulse 数据的衍生产品

L1核心特征

3 分钟快速开始

L1第一步：获取 API Key

在 GlobalPulse 客户端 → 【设置】→ 【API 密钥】，点击【创建 Key】即可生成。Key 形如 gpapi_xxxxxxxx_xxxxxxxxxxxx，请妥善保存。

L1第二步：发起第一个请求

测试你的 Key 是否工作。以下命令获取当前 A 股大盘涨跌家数：

curl https://api.global-pulse.net/api/v1/market/limit-stats \
  -H "X-API-Key: gpapi_xxxxxxxx_xxxxxxxxxxxx" \
  -H "User-Agent: my-app/1.0"复制

import requests

API_KEY = "gpapi_xxxxxxxx_xxxxxxxxxxxx"

r = requests.get(
    "https://api.global-pulse.net/api/v1/market/limit-stats",
    headers={
        "X-API-Key": API_KEY,
        "User-Agent": "my-app/1.0",
    },
    timeout=10,
)
print(r.json())复制

const API_KEY = "gpapi_xxxxxxxx_xxxxxxxxxxxx";

const res = await fetch(
  "https://api.global-pulse.net/api/v1/market/limit-stats",
  {
    headers: {
      "X-API-Key": API_KEY,
      "User-Agent": "my-app/1.0",
    },
  }
);
const data = await res.json();
console.log(data);复制

L1第三步：解析响应

除健康检查外，受保护业务接口返回统一结构：

{
  "ok": true,
  "data": {
    "ztNum": 76,
    "dtNum": 40,
    "upNum": 3201,
    "downNum": 1924,
    "flatNum": 0,
    "zbCount": 41,
    "lbMax": 4,
    "date": "2026-07-15"
  },
  "ts": 1784108544176,
  "_cost": 1
}

✓ ok: true 表示成功。失败时 ok: false 并带 code + error。详见 错误码。

说明：为便于阅读，部分响应示例保留了 // 注释，属于 JSONC 展示格式；线上响应本身是严格 JSON。

鉴权机制

L1必需 Header

每次请求必须包含以下两个 Header：

L2Key 安全规范

• 不要将 Key 写在前端代码或公开仓库中
• 不要通过 URL 参数传递 Key（防止 server 日志记录）
• 务必使用环境变量或秘钥管理服务存储
• 如果 Key 不慎泄露，立即在客户端【API 密钥】中【禁用】然后【新建】

L3Key 生命周期

API Key 与你的 PRO 订阅深度绑定：

• 每个 PRO 用户在任一时刻最多有 1 个 active key
• PRO 订阅过期时，Key 自动禁用（disabled_reason: pro_expired）
• 禁用后所有请求返回 403 KEY_DISABLED
• 续费 PRO 后需手动重新创建新 Key

配额与限流

L1叠加包

本月配额用完后，可购买 +10,000 次叠加包（¥99），立即生效，当月有效，不结转下月。请在客户端或账户服务页按提示购买。

L2响应头

成功的、已鉴权响应通常包含以下 Header，便于你监控用量；健康检查和鉴权失败响应不承诺带有配额头。

L3限流策略与重试

触发限流时返回 429 RATE_LIMITED，响应体：

{
  "ok": false,
  "code": "RATE_LIMITED",
  "error": "Rate limit exceeded: 60/min",
  "retry_after_seconds": 18
}

建议使用指数退避（exponential backoff）策略，并优先遵循 Retry-After 响应头；若客户端不读取响应头，再使用 retry_after_seconds。避免并发重试。

17 条路径 · 21 项可调用能力

所有业务接口的根路径为 https://api.global-pulse.net/api/v1。另有无需 Key 的健康检查 GET /api/v1/ping；/ai/postscan 是 /ai/post-scan 的兼容别名。

L1健康检查

无需 API Key，用于负载均衡、部署检查和客户端启动探测。该接口不消耗配额。

{
  "ok": true,
  "service": "gp-api-v1",
  "version": "1.0.0",
  "ts": 1784108544176
}

L1最新新闻流

获取 GlobalPulse 汇聚的最新财经新闻（中文为主，覆盖国内外财经与产业资讯）。

Query 参数

响应

{
  "ok": true,
  "data": {
    "count": 1,
    "items": [{
      "id": "n_8c9d2f...",
      "title": "央行：将继续实施稳健的货币政策...",
      "summary": "今日央行召开三季度金融统计数据发布会...",
      "url": "https://...",
      "source": "新华社",
      "region": "cn",
      "time": 1784108544176,
      "sentiment": 0.62,        // 情绪分 -1 ~ 1
      "tags": ["央行", "货币政策"],
      "pubTime": 1784108544176
    }]
  },
  "ts": 1778653662616
}

示例（cURL）

curl 'https://api.global-pulse.net/api/v1/news/latest?limit=20' \
  -H "X-API-Key: $API_KEY" \
  -H "User-Agent: my-app/1.0"

L1搜索新闻

按关键词全文检索历史新闻库。

Query 参数

示例

curl 'https://api.global-pulse.net/api/v1/news/search?q=人工智能&limit=10' \
  -H "X-API-Key: $API_KEY" \
  -H "User-Agent: my-app/1.0"

L2主题流

按预定义主题筛选新闻。GlobalPulse 提供 8 个细分主题(覆盖 A 股全行业)+ 4 个兼容别名。

8 个标准主题

4 个兼容别名(向后兼容老客户)

匹配机制

• 每个主题预置 30-150 个关键词(中英文 / 公司名 / 技术术语)
• 标题命中权重 ×3,正文命中权重 ×1
• 按相关度排序,同分按时间倒序
• 响应内含 matched_keywords 字段,客户可查看为何命中
• 服务端会对相同主题的短时间重复请求进行复用；客户端不应依赖固定缓存时长或延迟承诺

查询参数

示例

curl 'https://api.global-pulse.net/api/v1/news/topic/ai?limit=20' \
  -H "X-API-Key: $API_KEY" \
  -H "User-Agent: my-app/1.0"

响应示例

{
  "ok": true,
  "data": {
    "topic": "ai",
    "topic_resolved": "ai",
    "topic_info": {
      "name": "AI / 人工智能",
      "description": "人工智能、大模型、算力相关新闻",
      "keywords_count": 65
    },
    "count": 18,
    "items": [
      {
        "title": "人工智能产业链出现新进展",
        "url": "https://...",
        "source": "财经资讯",
        "time": "2026-05-17T09:30:00Z",
        "summary": "...",
        "matched_keywords": ["人工智能", "大模型", "推理"]
      },
      ...
    ],
    "cached": false
  }
}

列出所有可用主题

无参数。返回完整的 8 主题元数据 + 4 别名映射,方便客户端动态生成 UI 选择器。

curl 'https://api.global-pulse.net/api/v1/news/topics' \
  -H "X-API-Key: $API_KEY" \
  -H "User-Agent: my-app/1.0"

L3全量新闻档案 NEW

访问 GlobalPulse 新闻档案（按可用数据窗口提供）。适合投研分析、事件研究、行业梳理与增量同步。

查询参数

示例

curl 'https://api.global-pulse.net/api/v1/news/archive?limit=500' \
  -H "X-API-Key: $API_KEY" \
  -H "User-Agent: my-app/1.0"

响应示例

{
  "ok": true,
  "data": {
    "count": 500,
    "total_in_archive": 5024,
    "oldest": "2026-05-14T03:00:00.000Z",
    "newest": "2026-05-17T03:30:00.000Z",
    "items": [
      {
        "id": "xxx_123",
        "title": "...",
        "source": "财联社",
        "region": "cn",
        "pubTime": 1778988870752,
        "url": "https://...",
        "tags": ["AI","大模型"],
        "sentiment": "positive",
        "heatBase": 80
      },
      ...
    ]
  }
}

使用场景

• 投研报告:拉取当前可用窗口内的金融新闻,做行业事件梳理
• 策略回测:用历史新闻做事件驱动策略的研究
• 语料训练:做行业语料库建设、关键词图谱
• 批量分析:配合 since 增量拉取,只取最新增量

L1大盘指数

实时获取 A 股、港股、美股、日经、富时等全球主要指数。

响应

{
  "ok": true,
  "data": {
    "ok": true,
    "ts": 1784108544176,
    "data": [
      {
        "name": "上证指数",
        "price": "3955.58",
        "change": "-0.29%",
        "isUp": false,
        "region": "cn"
      }
    ]
  },
  "ts": 1784108544176,
  "_cost": 1
}

为兼容旧客户端，指数数组仍位于 response.data.data；新客户端可直接使用同一层的 items 与 count。

L2市场情绪

基于新闻情绪、连板梯队、北向流入等多维度计算的综合情绪分（-100 ~ 100）。

响应

{
  "ok": true,
  "data": {
    "ok": true,
    "data": {
      "score": 55,
      "level": "neutral",
      "label": "中性震荡",
      "dims": { "volume": 20, "limitUp": 60, "sector": 90, "global": 95, "policy": 50, "technical": 42, "news": 20 },
      "dimensions": [],
      "signals": [],
      "narrative": "市场情绪中性震荡……"
    },
    "dataQuality": { "status": "ready", "reasons": [], "usableCount": 16, "suppliedCount": 16 },
    "ts": 1784108544176
  },
  "ts": 1784108544176,
  "_cost": 1
}

为兼容旧客户端，完整评分对象仍位于 response.data.data；新客户端可直接读取 response.data.score、level、dimensions、signals 等核心字段。若输入不足，response.data.dataQuality.status 会为 degraded，并给出 reasons，不把降级分数伪装成满质量实时数据。

L1涨跌停统计

实时 A 股市场广度数据：涨跌家数、涨停数、跌停数、连板梯队。

响应

{
  "ok": true,
  "data": {
    "ztNum": 76,
    "dtNum": 40,
    "upNum": 3201,
    "downNum": 1924,
    "flatNum": 0,
    "zbCount": 41,
    "lbMax": 4,
    "date": "2026-07-15"
  },
  "ts": 1784108544176,
  "_cost": 1
}

L2北向资金

沪股通 + 深股通实时净流入。

响应

{
  "ok": true,
  "data": {
    "today": null,
    "history": [],
    "available": false,
    "status": "unavailable",
    "reason": "off_hours_or_source_unavailable"
  },
  "ts": 1784108544176,
  "_cost": 1
}

非交易日或数据源暂无北向数据时，today 可能为 null，history 可能为空数组；这属于正常数据状态，不等同于接口故障。

L2活跃股池 NEW

返回中央数据引擎计算的活跃股池。盘中默认返回当前帧；非交易时段由中央模块按其可证明的最近收盘回放返回。接口只读，不接受客户端写入。

Query 参数

响应示例

{
  "ok": true,
  "data": {
    "marketOpen": true,
    "count": 20,
    "sourceTs": 1784108544176,
    "asOf": 1784108544176,
    "tradeDate": "2026-08-20",
    "modelVersion": "active-pool-v1",
    "data": [{ "code": "600519", "name": "贵州茅台", "score": 92.4 }],
    "rankingPolicy": {},
    "membershipPolicy": {},
    "stability": {},
    "coverage": {},
    "sources": {}
  },
  "ts": 1784108544176,
  "_cost": 1
}

字段以线上返回为准；当中央帧无法证明新鲜或完整时，服务端会返回不可用错误，不用空数组伪装正常数据。

L2分时资金流 NEW

返回服务端按 5 分钟累计的板块分时资金流帧，适合绘制当日连续曲线。

Query 参数

响应示例

{
  "ok": true,
  "data": {
    "dim": "industry",
    "date": "2026-08-20",
    "isToday": true,
    "count": 2,
    "available": true,
    "status": "ready",
    "reason": null,
    "latestFrameAt": "2026-08-20T10:05:00+08:00",
    "latestSourceTs": 1784108544176,
    "latestSourceAgeSec": 12,
    "latestSourceCached": false,
    "stale": false,
    "frames": [{ "t": "09:35", "v": { "银行": 123456789 }, "sourceTs": 1784108500000 }]
  },
  "ts": 1784108544176,
  "_cost": 1
}

响应不计算或发布 flowScore；客户端应根据帧时间、来源时间戳和 stale 自行处理展示。

L2真实赚钱涨跌 NEW

返回已通过数据新鲜度与完整性校验的“真实赚钱涨跌”公开投影，包含最新值、盘中点、交易日历史和可证明的强势篮子/延续性信息。

上游无可发布最新帧或数据过期时返回 503 UPSTREAM_UNAVAILABLE；不会把陈旧或内部审计字段伪装成完整数据。

响应示例

{
  "ok": true,
  "data": {
    "meta": {
      "shortName": "RPI",
      "algorithmVersion": "RPI-1.1.0",
      "updatedAt": 1784108544176,
      "ageMs": 12000,
      "sourceAgeSec": 12,
      "stale": false,
      "daysContract": "RPI-PUB-DAYS-2"
    },
    "latest": {
      "tradeDate": "2026-08-20",
      "sourceTs": 1784108544176,
      "value": 103.42,
      "changePct": 0.87,
      "profitShare": 61.2,
      "coveragePct": 96.4
    },
    "intraday": [],
    "days": [],
    "strongBasket": {},
    "continuation": { "available": false, "reason": "continuation_unavailable" }
  },
  "ts": 1784108544176,
  "_cost": 1
}

L2连板 / 涨停梯队 NEW

返回中央数据引擎的真实连板/涨停梯队分层。线路使用中央五档梯队，不用涨停总数反推梯队；无可证明的中央数据时 fail-closed。

Query 参数

无。传入任意查询参数会返回 400 BAD_REQUEST。

响应示例

{
  "ok": true,
  "data": {
    "date": "20260820",
    "tradeDate": "2026-08-20",
    "cacheTs": 1784108544176,
    "cacheAgeSec": 12,
    "maxBoards": 5,
    "total": 76,
    "estimated": false,
    "source": "central-board-ladder",
    "fromCache": false,
    "stale": false,
    "data": [
      { "boards": 5, "label": "5连板", "count": 1, "stocks": [{ "code": "000001", "name": "示例" }] },
      { "boards": 4, "label": "4连板", "count": 2, "stocks": [] }
    ]
  },
  "ts": 1784108544176,
  "_cost": 1
}

L3概念图谱 3D NEW

全市场概念簇 + 个股梯队的结构化图谱,驱动「概念星图 3D」可视化。两种视图:

• 全景视图(默认,不带 code):返回概念簇 + 每簇龙头梯队 + 市场温度判定。消耗 10 次配额。
• 单股视图(带 ?code=6位代码):返回该股所属概念 + 在各概念内的梯队位次。消耗 1 次配额。

查询参数

响应(全景)

{
  "ok": true,
  "data": {
    "regime": "题材活跃·多点开花",
    "base_date": "2026-06-12",
    "clusters": [
      {
        "concept": "AI算力",
        "limit_up": 6,
        "members": [
          { "rank": 1, "code": "300750", "name": "宁德时代",
            "chg_pct": 10.0, "zt": true, "dt": false,
            "amount": 12800000000, "role": "龙1" }
        ]
      }
    ]
  },
  "quota_cost": 10,
  "ts": 1784108544176
}

示例

curl 'https://api.global-pulse.net/api/v1/market/concept-graph?top=20&members=10' \
  -H 'X-API-Key: gpapi_xxxxxxxx_xxxxxxxxxxxx' \
  -H 'User-Agent: my-app/1.0'

# 单股视图
curl 'https://api.global-pulse.net/api/v1/market/concept-graph?code=600519' \
  -H 'X-API-Key: gpapi_xxxxxxxx_xxxxxxxxxxxx' \
  -H 'User-Agent: my-app/1.0'

L1AI 叙事

返回最近 5 天内可用的 AI 市场叙事；交易日通常每 30 分钟更新一次，非交易日沿用最近一条。

响应

{
  "ok": true,
  "data": {
    "available": true,
    "title": "市场情绪边际改善，结构性机会延续",
    "narrative": { "summary": "今日市场……", "bullish": [], "bearish": [] },
    "updated_at": "2026-07-15T14:30:00.000Z",
    "expires_at": "2026-07-15T15:00:00.000Z"
  },
  "ts": 1784108544176,
  "_cost": 1
}

L2信号复盘

返回最近仍有效的一条利好信号和一条利空信号；没有对应信号时，bull 或 bear 为 null。

响应

{
  "ok": true,
  "data": {
    "bull": { "title": "资金回流科技板块", "content": { "summary": "……" }, "updated_at": "2026-07-15T09:30:00.000Z" },
    "bear": null
  },
  "ts": 1784108544176,
  "_cost": 1
}

L3盘后扫描

每个交易日约 16:30 生成盘后扫描。当前正式字段为 5 类股票池；/v1/ai/postscan 是兼容别名。

响应

{
  "ok": true,
  "data": {
    "available": true,
    "title": "2026-07-15 盘后扫描",
    "date": "2026-07-15",
    "pools": {
      "golden_relay": [{ "code": "300999", "name": "示例股票", "reason": "..." }],
      "divergence_warning": [],
      "risk_defense": [],
      "strong_no_limit": [],
      "second_wave": []
    },
    "deep_report": null,
    "concept_trend": null,
    "meta": {},
    "created_at": "2026-07-15T16:35:12.000Z"
  },
  "ts": 1784108544176,
  "_cost": 1
}

错误码表

所有错误返回 { ok: false, code, error }，部分错误还带 details 或 retry_after_seconds。以下为线上当前真实契约；不要根据错误文案猜测状态码。

L2错误响应示例

{
  "ok": false,
  "code": "QUOTA_EXCEEDED",
  "error": "Monthly quota reached. Please review your plan or purchase an add-on.",
  "details": { "limit": 10000, "used": 10000, "period": "2026-07" }
}

版本管理

L2兼容性承诺

线上 v1 接口持续提供兼容支持。本页 V3.0 是文档版本，不会把线上路径升级成 /api/v2。现有路径与字段保持兼容；新增字段不会要求已有客户端立即升级。

• ✅ 只增不减：新增字段不影响现有代码
• ✅ 数据质量持续优化：算法升级用户无感
• ✅ 非破坏性变更：除非提前 60 天公告，不会下线接口

L3升级路径

未来如果有破坏性变更，将发布 v2：

• v1 与 v2 并存至少 6 个月
• 提前 90 天邮件 + 客户端通知
• 提供完整的 v1 → v2 迁移指南

SDK 与工具

pip install requests

L3OpenAPI 3.0 规范

使用我们的 OpenAPI 3.0 规范 在 openapi-generator 生成你需要的任意语言 SDK（Go / Rust / Java / Swift / Kotlin）。规范与当前线上 v1 路由同步，概念图谱也包含在内。

常见问题

API 数据多久更新一次？

新闻：分钟级；行情：实时（盘中延迟取决于数据源）；AI 叙事：交易日通常每 30 分钟更新；盘后扫描：每交易日约 16:30。

能用 API 数据做收费产品吗？

可以，但需要遵守：(1) 不能转售原始数据 (2) 必须标注 "Powered by GlobalPulse" (3) 不能逆向我们的算法。商业大客户请联系 business@global-pulse.net。

API Key 丢了怎么办？

在客户端【API 密钥】中【禁用】当前 Key，再【新建】一个。旧 Key 立即失效。

能锁定 IP 吗？

v1 不强制锁定 IP（仅记录最近调用 IP）。如果你的安全场景需要 IP 白名单，请联系商务定制企业版。

支持 Webhook 推送吗？

v1 暂不支持，需要轮询。未来版本可能支持 Webhook（新闻推送 / 盘后扫描完成等）。

有 SLA 保证吗？

个人 PRO：尽力而为，无 SLA。企业版可签 99.5% SLA。