股票行情API怎么选？做报价看板，哪些数据必须有，哪些可以后加？

TickDB Research ·

摘要：面向负责股票报价看板的金融应用产品负责人，本文从一份首版需求出发，把价格展示、历史走势、盘口观察和成交明细分别对应到需要的数据，解释哪些能力应进入首版、哪些可以按需求增加。结合TickDB的一次美股样本检查，提供填写完成的数据需求单、验收方法与可复用检查代码，帮助产品和技术围绕同一份交付标准选择股票行情API。

假设你正在推进一个股票报价看板。首版需求很清楚：用户能找到自选股票，查看价格和涨跌，知道数据截至什么时候。

讨论API时，选项却越来越多：历史K线要不要？盘口接几档？逐笔成交是不是也该接上？盘前、盘后和夜盘要不要一起展示？

每加一类数据，页面就多了一组要解释的信息：它对应什么时段，多久更新，空值时显示什么，与其他模块的数字为什么不同。功能清单如果没有边界，技术同事很难判断什么才算做完。

选择股票行情API，可以先做一个决定：把数据按页面功能配置。支撑首版承诺的数据优先接入；支撑后续分析功能的数据按需求增加；标的身份、时间口径和异常状态则从首版开始设计。

一、先写清首版承诺，再看接口清单

本文用一份假设需求贯穿：做一个美股自选报价看板，首版展示股票身份、所选交易时段的价格及涨跌，支持持续更新和数据过期提示。示例首版选择常规交易时段，暂不承诺扩展时段切换、盘口分析、成交明细或历史研究。

这并不是说后面几项不重要。产品如果主打历史走势，K线就是首版依赖；如果核心功能是观察买卖价差，买卖报价就要进入首版。优先级来自已经承诺的功能。

把需求中的“实时行情”拆开，至少写出四句话：

  • 展示对象：哪一个市场、哪一份标的清单，代码如何与名称对应。
  • 展示口径：展示哪个时段的什么价格，涨跌相对哪个基准。
  • 更新要求：目标交易时段内，多久没有取得符合要求的数据就提示过期。
  • 失败行为：代码不存在、账户无权限、字段缺失或连接中断时，页面怎样回应。

“支持WebSocket”描述接入方式；“目标时段内持续更新，过期后明确提示”才是产品需要验收的行为。前者还需要技术实现、时段规则和页面状态配合，才能交付后者。

image.png

图1：方法示意。先明确功能，再选择支撑该功能的数据。历史走势、盘口和成交是否进入首版，取决于本次产品承诺。

二、首版报价展示，先把这些信息配齐

1. 价格需要附着在明确的股票身份上

页面显示一个数字之前，先确认它属于哪只证券、哪个市场、什么币种。简称可以用于阅读，稳定的证券代码和市场信息用于关联数据。

跨市场扩展时，这一步尤其重要。相似的代码、不同币种和交易时段，会使“统一放进一张表”比预想复杂。名称、市场和币种可以来自产品目录或参考资料，不要求每次报价都重复返回，但应用应保留明确的对应关系。

2. 涨跌幅需要有可解释的基准

产品不能只写“显示涨跌幅”，还应写清它相对哪个参考价格、采用哪个交易时段的统计口径。

TickDB的报价文档列有最新成交价、参考昨收和涨跌幅等字段，并说明除核心报价字段外，其他信息按产品、时段及数据可用性返回。拿到某个字段后，要核对它是否符合页面承诺；缺失时显示未提供或暂不可用，不自动填成零涨跌。

如果应用自行计算涨跌幅，还要保留计算基准。不要拿一个时段的价格，配另一个口径的参考值，只因为两者都是非空数字。

3. 报价时间与页面状态应一起交付

行情时间描述数据对应的时点，接收时间描述程序取得响应的时点。页面可以选择适合用户阅读的时间格式，后台则保留原始时间戳和时区规则。

过期判断也应对应产品要求。常规时段已经结束，页面保留最后一条常规时段报价，可以是正常设计；交易时段内更新停止，仍保持“实时”标识，就会误导用户。

因此，首版至少要区分：正常展示、数据过期、缺少数据。页面状态是应用实现的能力，不会因为接口返回了时间戳就自动具备。

三、什么时候才需要增加K线、盘口和逐笔成交？

可以用一个问题判断：没有这类数据，哪一个已承诺的功能会无法完成？

准备增加的功能需要补什么数据随之增加的验收责任
展示一段历史走势相应周期和范围的K线时间范围、周期、复权口径、缺失记录及未完成周期
观察买卖报价与价差最优买卖报价；需要观察层级时再取相应深度实际档数、数量单位、各自时间及空盘口状态
展示最近发生的成交最近成交记录或匹配需求的成交推送记录范围、成交时间、数量单位、重复处理与缺失提示
切换盘前、盘后或夜盘对应时段的数据及明确标签各对象的价格、基准和时间是否一起切换

历史走势：先决定要展示什么时间尺度

首版只要当前报价，就不必因为API提供多年数据而先建设历史研究模块。需要走势图时，再确认日线还是分钟线、显示多长区间，以及采用什么复权口径。

同样，页面能画出一条曲线，只完成了展示。历史样本是否适合回测，还涉及证券样本、数据版本和研究设计，不能由“有K线接口”直接推定。

盘口：服务于买卖报价观察，不承诺实际成交

最新成交价描述已经发生的交易；买卖盘口描述返回时可见的买卖报价。观察当前买卖价差，需要对应买卖报价；观察更多价格层级，才进一步需要深度。

接口支持几档是上限与范围问题。页面应处理实际返回较少、单侧为空等情况。盘口随时可能变化，可见报价和数量不能被页面包装成一定可以成交的价格与数量。

逐笔成交：先明确是最近窗口还是连续记录

最近成交列表可以帮助用户了解刚才发生的交易。但查到最近三条或一百条，并没有获得完整交易日的成交历史。

如果产品承诺连续记录，就要进一步考虑持续接收、断线、去重和缺口。把最近记录接口反复刷新，并不能直接作为“完整成交归档”的验收依据。

四、一份可直接交给技术伙伴的数据需求单

下面是本文假设看板的填写示例。它记录产品决策，尚不是上线验收结果。

页面功能与优先级最小数据可后加能力验收方法
自选股票识别：首版必需代码、名称、市场、币种及对应关系跨市场搜索核对完整自选清单，避免代码歧义和错误单位
价格展示：首版必需目标时段价格、行情时间扩展时段切换逐项对照时段与字段；价格和时间属于同一对象
涨跌展示：首版必需匹配口径的涨跌值或计算基准更多统计指标核对参考价格与统计口径，缺失不补零
更新与状态：首版必需更新记录、行情时间、接收时间和错误状态自动恢复等增强能力在目标时段测试更新；模拟中断，检查过期与缺失提示
历史走势图：本示例后加对应周期的历史K线更多周期与历史研究核对范围、口径、缺失和周期完成状态
盘口与成交模块：本示例后加按具体功能选择买卖盘或成交记录深度观察与连续成交记录分别核对返回范围、时间、数量单位及空态

这张表还要配一小段适用条件：目标账户、完整标的清单、所选时段、预期负载，以及内部使用还是客户展示。额度和使用条件应按这份具体需求确认，不把官网列出的能力自动视作当前账户权益。

如果某个后加功能成为首版卖点，就把该行移到首版，并同时接受它的验收责任。不要只调整功能优先级，却把数据检查留到以后。

五、用TickDB样本，把“有接口”变成可检查的记录

在这类任务中，TickDB提供A股、美股、港股的报价、历史K线、买卖盘和成交数据接入路径，可按需要使用REST查询或WebSocket推送。具体市场、字段与账户权限仍分别核对。本文选择已连接的MCP，对美股AAPL.US做一次样本检查，不展开完整看板开发。

2026年11月10日，先从美股目录确认Apple的身份，再分别查询报价、盘口与最近三条成交。下面只展示结构和时间，不展示行情价格。

数据本次实际返回对应数据时间，UTC
主报价包含证券代码、价格、参考昨收、涨跌幅与时间字段2026-11-09 21:00:01
买卖盘口买侧1档、卖侧1档2026-11-10 04:01:56.484
最近成交请求3条，返回3条，记录标有overnight2026-11-10 04:00:42至04:01:51

取数记录位于2026年11月10日UTC 04:01这一分钟。三类数据来自独立查询，不是同一时刻的原子快照，也不用于计算端到端延迟。

这个样本首先影响的是页面口径：主报价还附有盘前、盘后与夜盘对象。首版若选择常规时段，就应核对所取字段与目标时段是否匹配，并保留对应标签；以后增加夜盘时，要同时处理夜盘价格和它自己的时间。不能因为另一个对象时间更晚，就静默替换一列价格而沿用原标签。

其次，盘口一档与成交三条分别说明本次返回了什么结构，不能替代“深度足够”“成交完整”的产品判断。本次没有验证全自选清单、持续更新、WebSocket或对外展示条件，账户等级也未核验。

怎样取得自己的样本

在已连接TickDB MCP的客户端中，可以使用以下任务。保留真实成功或错误，不让助手补造数据：

先在US股票目录确认Apple的身份，再查询AAPL.US：
1. get_ticker，symbols="AAPL.US"，type="stock"；
2. get_order_book，symbol="AAPL.US"，type="stock"；
3. get_recent_trades，symbol="AAPL.US"，type="stock"，limit=3。
将各工具返回的完整业务JSON分别保存为ticker_raw.json、
depth_raw.json、trades_raw.json，记录取数时间。
按模块列出字段、返回数量和各自时间，不把它们合并成同一时刻。
如果查询失败，保留原始错误，不生成模拟成功文件。

后面的检查程序可以读取这三个保存文件，生成sample_check.csv。它检查结构和时间，不能确认市场数据正确性、持续运行或产品上线条件。

如需按自己的需求单核对市场能力、接入方式与使用条件，可查看TickDB股票API页面。

image.png

图2：方法示意。样本检查帮助确认返回结构；持续更新、异常状态和使用条件仍需按产品需求验收。

六、交付之前，让三件事对应起来

产品负责人可以先准备三份材料：填好的数据需求单、保留时间和条件的真实样本、能逐项执行的验收清单。

需求单回答为什么要这类数据；样本让技术同事看到实际返回；验收清单说明正常、过期和缺失时应发生什么。三者对应起来，才容易发现“功能写进首版了，但数据或异常行为还没定义”的缺口。

现在就从一项已经承诺的页面功能开始，填下它需要的数据、采用的时段、允许的缺失行为和验收方法。完成这一步，再选接口、权限和后续能力，股票行情API的选择就有了具体依据。

资料与样本日期：2026年11月10日。样本来自TickDB MCP；字段与能力说明参考TickDB当前官方文档。产品配置为本文假设案例，实际使用条件按目标市场、账户与用途确认。

附录：保存样本的结构检查程序

将下面程序保存为check_sample.py，与三个JSON文件放在同一目录，运行python3 check_sample.py。需要Python 3.10或以上版本，仅用标准库，不发网络请求，不需要Key。遇到业务失败、证券不符或必需字段缺失时会停止。

"""Python 3.10+; inspect saved TickDB MCP payloads, without network calls."""
import csv
import json
from datetime import datetime, timezone
from pathlib import Path


def read_payload(filename):
    payload = json.loads(Path(filename).read_text(encoding="utf-8-sig"))
    if payload.get("code") != 0:
        raise ValueError(f"Unsuccessful API response: {filename}")
    return payload["data"]


def utc(value):
    if type(value) is not int or value < 0:
        raise ValueError("Expected a nonnegative millisecond timestamp")
    return datetime.fromtimestamp(value / 1000, timezone.utc).isoformat()


def main():
    symbol = "AAPL.US"
    quotes = read_payload("ticker_raw.json")
    matching = [row for row in quotes if row.get("symbol") == symbol]
    if len(matching) != 1:
        raise ValueError("Expected exactly one matching quote")
    quote = matching[0]
    book = read_payload("depth_raw.json")
    tape = read_payload("trades_raw.json")
    if book.get("symbol") != symbol or tape.get("symbol") != symbol:
        raise ValueError("The payloads refer to different symbols")
    required = ("last_price", "timestamp")
    if any(quote.get(key) is None for key in required):
        raise ValueError("Missing a required quote field")
    bids, asks, trades = book["bids"], book["asks"], tape["trades"]
    times = [row["timestamp"] for row in trades]
    rows = [
        ["quote", symbol, "required_fields_present", utc(quote["timestamp"])],
        ["depth", symbol, f"bids={len(bids)};asks={len(asks)}", utc(book["timestamp"])],
        ["trades", symbol, f"rows={len(trades)}",
         f"{utc(min(times))} to {utc(max(times))}" if times else "empty"],
    ]
    with Path("sample_check.csv").open("w", newline="", encoding="utf-8-sig") as file:
        writer = csv.writer(file)
        writer.writerow(["module", "symbol", "observed_structure", "data_time_utc"])
        writer.writerows(rows)
    for row in rows:
        print(" | ".join(row))
    print("Saved sample_check.csv; structure check only, not release approval")


if __name__ == "__main__":
    try:
        main()
    except (OSError, ValueError, TypeError, KeyError) as error:
        raise SystemExit(f"STOP: {error}")

相关文章

黄金行情API怎么用？用Python复盘CPI前后的金价变化

面向需要黄金行情API的量化研究人员，本文以CPI事件复盘为例，获取XAUUSD历史K线，对齐公布时刻，计算不同观察窗口的价格变化。文章提供实际运行的Python示例、结果表及数据检查方法，帮助团队统一比较基准，整理可复核的事件样本，为后续研究与策略回测准备输入。

TickDB Research ·

免费股票API怎么选？从个人研究到产品上线，先分清这几种限制

面向准备将研究原型交付为行情看板的金融产品负责人，本文以“20只美股、每10秒刷新”为例，拆解免费股票API的数据范围、更新频率、额度、订阅和使用条件。结合AKShare、Alpha Vantage、Twelve Data与TickDB的官方说明，以及一次TickDB MCP调用记录，提供可填写的选型判断表和可运行的用量计算代码，帮助团队判断免费方案能用到哪一步、交付前还需补什么。

TickDB Research ·

外汇行情还在更新吗？用 Python 订阅 EURUSD 并记录双时间

适合正在开发外汇报价监控、需要确认脚本持续收到行情的 Python 开发者。使用 TickDB 的 WebSocket 行情订阅，记录 EURUSD 报价、数据时间和本机接收时间，生成原始消息与 CSV。通过目标报价数量、接收间隔和数据时间推进情况，区分连接仍在、消息到达与数据更新。本次30秒订阅观察收到38条目标报价；代码支持有限运行和自动保存结果，方便在自己的环境复查。

TickDB Research ·

一个 API 同时接 A 股、港股、美股、加密和外汇，怎样验证才算数？

直接答案 多数人把行情 API 的覆盖列表当成菜单，以为列出来的就能点。实际上，那是一份意向书，不是交付承诺。判断一个 API 是否真正实现了多资产统一接入，你需要挑 A 股、港股、美股、加密货币和外汇各一个真实品种，用同一次查询验证五件事：同一次调用能否通过鉴权并返回结果，五个品种代码能否被正确解析，返回结构是否共享一套核心字段，时间戳格式是否明确且一致，以及无效 symbol 是报错、忽略

TickDB Research ·

股票API选型必备：国内外主流服务商与工具大全（44种方案完整指南）

Wind、同花顺iFinD、东方财富Choice、Tushare、AKShare、Bloomberg、LSEG、FactSet、TickDB、Massive、Alpha Vantage、Databento、Morningstar，该从哪一种开始？这份指南将44种国内外数据服务、平台与工具分成10类，按个人研究、量化回测、行情监控、应用开发、AI投研和交易连接等需求提供查找路径，逐项说明核心能力、适用人群、接入流程与使用条件，并附可运行代码、需求模板和验收清单，选型时查，接入时用。

TickDB Research ·