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。避免并发重试。

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

所有业务接口的根路径为 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；外层 data 同时保留状态与时间字段。

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": "市场情绪中性震荡……"
    },
    "ts": 1784108544176
  },
  "ts": 1784108544176,
  "_cost": 1
}

完整评分对象位于 response.data.data；非交易时段可能返回较少的信号项。

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": []
  },
  "ts": 1784108544176,
  "_cost": 1
}

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

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。