摘要：一份好用的港股实时行情 API，不仅决定数据接入效率，也直接影响后续研究的可靠性。本文以 TickDB 为例，介绍如何选择一个结构清晰的数据源，完成港股 symbol 配置和 ticker、K 线接口调用，并在接入后用一套 7 项字段核验清单确认数据就绪。适合正在选型或刚开始接入港股实时行情的量化研究者。
一、为什么要先选对数据源
接入港股实时行情，第一步不是写代码，而是选一个值得长期使用的数据源。
市面上可选的行情接口不少，但对接成本差别很大。选错了，后面的坑一个接一个：
| 常见问题 | 具体表现 | 对研究的影响 |
|---|---|---|
| 字段命名不统一 | ticker 的价格叫last_price，K 线的价格叫 close，文档里没说清楚区别 |
你以为取到了正确的字段，回测跑完才发现数据口径有问题 |
| 返回结构复杂 | ticker 和 K 线的数据嵌套在不同层级，取值路径要自己摸索 | 每个接口都要单独写取值逻辑，维护成本高 |
| symbol 格式不统一 | A 股写600519.SH，港股却要写 00700.HK，不同市场不同规则 |
跨市场策略要维护多套 symbol 格式，容易出错 |
这些问题不会阻止你拿到数据，但会让你的接入过程充满猜测。而量化研究最怕的就是猜测。
所以选数据源时，至少看三点：
字段定义是否清晰、返回结构是否一致、文档是否完整。
这三点决定了你后面的核验工作量。选对了，核验就是对照文档打勾；选错了，核验变成猜谜。
二、以 TickDB 为例：一个更适合研究者的港股行情 API
TickDB 是一个面向量化策略的统一行情 API，覆盖 A 股、港股、美股、外汇和数字货币等多个市场。对港股接入来说，它在设计上做了几件对研究者友好且省心的事：
| 设计特点 | 具体说明 | 对研究者的好处 |
|---|---|---|
| symbol 规则清晰 | 港股代码建议去掉前导零，直接写700.HK、5.HK；多市场后缀按文档统一规则管理 |
按文档统一写法管理即可，不用记忆不同市场的补零规则 |
| 字段定义明确 | ticker 快照价格就是last_price，K 线 OHLC 就是 open/high/low/close |
不会出现一个价格字段在不同接口里叫不同名字——降低字段混用风险 |
| 返回结构可按文档核对 | 同类接口的返回结构应先按文档和实际返回核对，确认后再固化到脚本里 | 每个接口取值前先确认路径，避免取到错误位置的数据 |
| 文档可查 | 核心接口字段可通过文档和当前返回交叉确认 | 接入完成后可以逐条对照，确认字段定义和实际返回一致 |
这些设计不能替代你必须要做的那份字段核验工作，但它们能让核验本身从“猜”变成“核对”——你需要的不是自己推理，而是对照文档打勾。
三、如何接入：ticker 和 K 线的基础配置
选好数据源后，接入港股实时行情主要涉及两个核心接口：
| 接口 | 用途 | 返回的核心价格字段 | 接入时最容易忽视的点 |
|---|---|---|---|
| ticker（实时快照） | 拉取当前时刻最新行情 | last_price（最近一笔成交价） |
last_price 不等于当日收盘价 |
| K 线（历史聚合） | 拉取指定时间间隔的聚合数据 | open/high/low/close |
返回路径需以文档和实际返回为准，不要假设 |
3.1 ticker 快照：获取实时价格
接入步骤：
- 确认 symbol 格式：港股代码去掉前导零，如
700.HK - 调用 ticker 接口，传入目标 symbol / symbols 参数，具体参数名以当前文档为准
- 返回 JSON 中定位
last_price字段
⚠️ 重要提醒：
last_price是最近一笔成交价，不等于当日收盘价。如果你需要“今天的收盘价”，应该去日线 K 线里取close。两者在盘中可能相差很大——这是初次接入最高频的错误。
3.2 K 线：获取 OHLC 历史数据
接入步骤：
- 指定参数：symbol（如
700.HK）和 interval（如1d日线、1m1 分钟线） - 调用 K 线接口
- 先打印返回 JSON 顶层结构，确认 OHLC 数组所在路径，再写取值逻辑
⚠️ 重要提醒：K 线的返回路径以当前文档和实际返回为准，不要假设在所有接口里都一样。取值前先确认数组位置，再写后续处理逻辑。
四、接入完成后：七项字段核验清单
接口返回成功状态，比如 code=0，只是第一步。接入完成后，下面这 7 项核验必须逐条跑一遍，否则你拿到的数据只是“看起来对”。
| 序号 | 核验项 | 要确认什么 | 最容易出的错 |
|---|---|---|---|
| 1 | symbol 格式 | 港股代码是否去掉前导零，如700.HK |
依赖带前导零的兼容写法，换数据源后失效 |
| 2 | ticker 价格字段 | 快照价格是last_price，不等于收盘价 |
把last_price 和 K 线 close 混用——最高频错误 |
| 3 | K 线价格字段 | OHLC 是open/high/low/close，返回路径先确认 |
把 K 线close 等同于 ticker last_price |
| 4 | timestamp 单位 | 确认是 13 位毫秒还是 10 位秒 | 按秒级处理毫秒时间戳，时间全错 |
| 5 | 空数据处理 | 非交易时段或停牌时返回什么 | 脚本直接取data[0]，空数组导致异常 |
| 6 | 返回结构路径 | ticker 和 K 线路径不同，需分别确认 | 路径写错，或取到错误位置的数据 |
| 7 | 未验证字段边界 | 港股通、暗盘、南下资金等是否真有返回 | 把文档没写的能力当成已支持，写进策略 |
4.1 symbol 格式：前导零去掉
港股代码建议去掉前导零，写 700.HK 而不是 00700.HK，写 5.HK 而不是 00005.HK。
核验动作：用 700.HK 和 5.HK 分别请求，确认均正常返回。统一格式写入脚本，不依赖系统做补零转换。
4.2 ticker 价格字段：它不等于收盘价
ticker 返回的 last_price 是最近一笔成交价，跟当日收盘价是两回事。
核验动作：同一时刻分别请求 ticker 和日线 K 线，对比两者的价格字段，直观理解差异。
4.3 K 线价格字段：先确认返回路径
K 线返回 open/high/low/close，但取值之前必须先确认这些字段在返回 JSON 中的位置。
核验动作：打印返回 JSON 顶层结构，确认 OHLC 数组所在路径，以当前文档和实际返回为准，再写取值逻辑。
4.4 timestamp 单位：别搞混位数
ticker 和 K 线常见返回 13 位毫秒时间戳。如果当成 10 位秒处理，时间解析会严重偏移。
timestamp 位数只用于字段解析，不代表延迟、SLA 或数据新鲜度保证。
核验动作：取一条返回的时间字段，检查位数，确认后统一写转换逻辑。
4.5 空数据处理：停牌和非交易时段
非交易时段或股票停牌时，ticker 可能返回空数组，K 线可能返回空列表。
核验动作：在非交易时段或找一只停牌股票请求，观察返回结构，确认脚本对空数据有显式处理。
4.6 返回结构路径：ticker 和 K 线分别确认
ticker 和 K 线的返回路径不同，混写会取不到数据。
核验动作：两种请求都打印返回 JSON，以文档和实际返回为准，确认各自路径后再写取值逻辑。
4.7 未验证字段边界：别把猜测写成结论
港股通标的、暗盘数据、南下资金流向、指数成分权重——这些不是行情接口标配。文档会列出每个接口的返回字段：
原则：以文档和当前返回为准，不以推测为准。 返回里有的，可以用；返回里没有的，先标注为“需独立数据源确认”。
核验动作：检查研究脚本里是否引用了上述特殊字段。如果有但当前返回里没有，先注释掉，待确认后再放开。
五、核验做完后，数据才算真正就绪
从选数据源到接入完成，再到 7 项核验全部打勾，这套流程走下来，你的港股实时行情才算真正进入了可用状态。
TickDB 这类字段定义清楚、返回结构可按文档核对的 API，能让这套核验过程从“猜”变成“核对”——大部分工作是对照文档逐项确认：
| 确认项 | 通过标准 |
|---|---|
| 格式 | symbol 去掉前导零，正常返回 |
| 路径 | ticker 和 K 线返回路径以文档和实际返回为准 |
| 字段 | last_price ≠ close，各取所需 |
| 时间 | timestamp 位数确认，解析逻辑正确 |
| 空数据 | 空数组有显式处理 |
| 边界 | 未验证字段已标注，不写进策略 |
提前跑完这套核验的时间成本，远比事后发现数据口径问题再返工要低。这不是额外的工作，这是保证你的研究建立在可靠数据上的必要一步。
免责声明：本文仅以 TickDB 为例说明港股实时行情的接入流程与字段核验方法，所有接口描述均来自公开文档，不代表特定产品的功能承诺。文章不构成任何投资建议，不推荐任何具体证券或交易方向，不对未来收益做任何暗示。文中提及的 symbol（如 700.HK、5.HK）仅用于格式说明，不构成投资标的推荐。
标签：#港股实时行情 #行情API接入 #TickDB #量化数据接入 #字段核验