美股API接入指南：实时行情、历史K线，怎样避免显示错价格？

TickDB Research · Sun Oct 25

摘要：美股行情功能接通以后，产品经理还要回答：页面显示的是哪个时段的价格，历史曲线包含哪些交易，财报之后怎样继续观察？本文以特斯拉三季报为案例，实际调用 TickDB REST API，取得报价、历史日线、分钟线与交易时间信息，解释实时行情、历史K线和盘前盘后数据怎样分工，并提供可运行脚本、原始结果与财报行情观察表，方便产品和技术同事一起验收。

10 月 22 日北京时间 12:42，TickDB 的同一次特斯拉快照里，主价格是 386.47 美元，盘后价格是 373.649 美元，夜盘（隔夜时段，overnight）价格是 368.82 美元。假如行情页只取主价格，把“页面刚刷新”当成“价格就是现在”，用户看到的仍可能是前一天下午的收盘记录。财报已经发布，这样的显示很容易让人误读市场变化。

我后来发现，问题不在接口有没有返回价格，而在页面把哪个时段的价格当成了“现在”。

接入时应把报价、历史走势和更新方式分别处理，让每个价格都带上自己的时段与数据时间。TickDB 提供行情快照、历史 K 线和交易时间查询，可以据此生成一张能追溯来源的观察表。下面沿着“先取报价，再取历史，最后对齐财报事件”的顺序，把这条路径实际跑一遍。

特斯拉官网确认，2026 年第三季度业绩于 10 月 21 日公布；此前公告安排在美股盘后发布。这也是一个适合检查行情页的时刻：常规交易结束以后，报价仍可能继续变化。特斯拉业绩公告、此前发布安排

一分钟看懂：现在的价格、过去的走势，各用什么数据

图1：AI生成概念示意。快照与历史序列分别回答不同问题，图中K线不代表真实行情。

页面要回答的问题	应取得什么	展示时保留什么
这只股票目前能查到什么报价	行情快照及对应时段的字段组	价格、返回项、数据时间
过去一段时间怎样变化	指定范围与周期的历史K线	日期范围、周期、复权方式
页面怎样继续更新	按需求安排轮询或持续订阅	更新状态、异常提示与恢复方式

快照像一次带时间的定格，K线把一个窗口内的开、高、低、收等数据汇总起来。查询方式决定你何时拿到它们；盘前、常规、盘后与夜盘，描述的是数据所属时段。

这几个问题分清后，接口参数和页面字段就能一一对应：股票详情页展示哪一种报价，曲线画哪个范围，数据缺失时怎样提醒。技术同事也不必从“接一个实时行情接口”里猜整套页面逻辑。

第一步：取回报价，把价格和它的时间一起留下

我这次直接请求 TickDB 的 REST 快照端点：

GET https://api.tickdb.ai/v1/market/ticker

请求参数：

{"symbols":"TSLA.US,AAPL.US","type":"stock"}

鉴权通过请求头 X-API-Key 传递，密钥放在服务端或本地安全环境中。我把返回结果存下来后，特斯拉的三个返回项如下，时间统一换算为纽约时间（America/New_York；北京时间约为纽约时间加 12 小时，夏令时）：

返回项	价格（美元）	纽约数据时间
主价格 `last_price`	386.47	10月21日 16:00:00
盘后 `post_market_quote.last_done`	373.649	10月21日 19:59:59
夜盘 `overnight_quote.last_done`	368.82	10月22日 00:42:06

接口请求发生在北京时间 10 月 22 日中午，主价格的数据时间却在纽约前一天下午。请求时间与数据时间要分别保存：页面刚刚刷新，只能说明刚发起过查询。

对这组结果，页面可以分开展示“常规收盘”“盘后”“夜盘”，旁边标明各自时间。如果页面只观察常规交易，就保留常规收盘作为主价；如果页面要展示夜盘观察结果，就使用对应返回项，并保留夜盘标签。

这里容易省掉一步：时间戳最大的字段，不一定是页面要的主价。一个“常规收盘表现”页面，与一个“夜盘观察”页面，选择规则本来就不同。

TickDB 当前文档说明，扩展时段的返回项在对应产品和数据可用时返回。对应字段缺失时，界面应显示缺失状态；沿用旧值则注明旧值时间，不把别的时段悄悄替上去。TickDB快照字段说明

第二步：取得历史走势，先明确曲线画的是哪一段

历史行情使用：

GET https://api.tickdb.ai/v1/market/kline

我这篇的日线请求固定为：

{
  "symbol":"TSLA.US",
  "interval":"1d",
  "adjust":"none",
  "start_time":1792022400000,
  "end_time":1792627199999,
  "limit":1000
}

对应 UTC 时间为 10 月 15 日 00:00:00 至 10 月 21 日 23:59:59.999；时间戳单位是毫秒。

曲线停在前一天，先检查返回日期

这次区间日线查询返回了四条记录，最后一条停在 10 月 20 日。交易日历列出的日期则包含 10 月 21 日。

我一开始也只看了请求成功，后来把返回日期和交易日历对了一遍，才发现曲线停在前一天。我针对 10 月 21 日又查了一次，取得了该日记录，收盘价为 386.47 美元。最终五个交易日与本次日历对齐，两次原始响应分别保留。

这里最容易被忽略：请求成功，不代表曲线完整。页面很可能已经把一条截止到前一天的线画好了。把返回日期与预期交易日核对，才知道是否还需要补取。

缺日的原因需要进一步定位；在原因明确之前，先记录缺口与补取结果，不用上一条价格复制出一条“新日线”。

分钟线包含哪些时段，要看实际返回

我还查询了特斯拉 10 月 21 日的 1m、不复权历史数据，返回 720 条记录，纽约时间从 08:00 到 19:59，包含盘后片段。

所以，不能把“美股分钟K线只含常规时段”作为通用前提。也不能看到这份样本里有盘后，就认定其他证券、日期和粒度都相同。产品画图前应检查实际时间范围，再决定怎样标注和筛选。

日线与分钟线也可能表现不同。我补取的日线收盘价是 386.47；当日最后一条分钟线在 19:59，收盘价为 373.649。若页面要展示常规收盘，应使用已确认的对应记录，不能直接拿整段分钟序列的最后一行代替。

TickDB 文档还说明，最新一根 K 线可能仍在形成；免费版 K 线查询不支持通过 start_time、end_time 指定范围。接入前核对账号权限，做研究归档时留下查询时间和复权方式。TickDB K线查询说明

财报之后，把事件与行情放到同一条时间线上

图2：由本篇真实返回绘制。实线为720条分钟收盘价；夜盘只画一个快照点，未采样的空档不连线。17:30标记为公司公告的业绩问答会时间。

在这张图里，16:00 的常规收盘只是一个节点。分钟样本继续到 19:59；之后，下一天的夜盘快照又给出了一个新的观察点。

如果界面只画常规时段，收盘以后曲线停下可以是产品设计；旁边的扩展时段报价却还在变化。此时应告诉用户曲线显示到哪里，避免让人以为整个页面卡住了。

反过来，若曲线已经包含盘后，标题和时间轴也要相应标注，不能仍让读者按“常规交易走势”理解整段数据。

财报日期、问答会时间、行情时间，分别记录

特斯拉公告中的问答会时间是 10 月 21 日美东 17:30，对应北京时间 10 月 22 日 05:30。它是问答会安排，不能直接填进“财报精确发布时间”。

这次可以形成下面的事件观察表：

记录	时间或时段	价格（美元）	来源
三季报发布安排	10月21日盘后	—	特斯拉官方公告
常规收盘记录	10月21日 16:00:00	386.47	TickDB快照；补取日线收盘一致
业绩问答会安排	10月21日 17:30	—	特斯拉官方公告
盘后快照	10月21日 19:59:59	373.649	TickDB盘后对象
夜盘快照	10月22日 00:42:06	368.82	TickDB夜盘对象

行情记录只能帮你定位观察窗口，不能拿先后顺序当因果。要解释价格变化，还得看财报和同期信息。

FINRA 的投资者资料也提醒，扩展时段可能面临较低流动性、更大波动和不同交易场所的价格差异。把时段与时间写清，是给读者判断这些数据的必要信息。FINRA：扩展时段交易

交付前必须定下四件事：主价、异常、更新、追溯

主价怎么选。先写清页面目的，再决定采用哪个返回项。交易时段切换时，也要说明旧返回项怎样保留和展示。

什么情况下显示异常。对应字段缺失、时间无法解析、历史范围不完整，应成为可见状态。数据多久算旧，要由具体用途确定，不能用一条固定阈值覆盖所有场景。

页面怎样继续更新。按需查询适合打开页面或发起一个问题时取得快照；轮询需要安排频率和请求次数限制。需要持续订阅的项目，另行检查更新、连接恢复与数据缺口处理。本文的实际接入是 REST。

同事能否追溯结果。至少保留证券代码、返回项、数据时间、采集时间和原始返回的保存位置。报价表与历史表分别保存，避免把“某一刻的价格”和“某个窗口的收盘”混成一列。

这些要求写进验收清单，产品验收就有了具体检查项：检查页面上的价格来自哪里、属于哪一段，以及缺失时用户会看到什么。

给技术同事：直接运行随文材料

下载完整脚本、原始响应与观察表

材料使用 Python 3.10+、系统 curl 和 IANA 时区数据，不需要安装第三方 Python 库。请先在安全环境中配置 TICKDB_API_KEY，然后在解压根目录运行：

python3 attachments/collect_us_observation.py --out my_run

脚本实际发起 REST 请求，密钥通过标准输入传给 curl，不进入命令参数或结果文件。默认参数就是本篇固定的证券与日期窗口；取自己的样本前，修改脚本中集中列出的任务参数，再另存运行结果。

最终运行取得八行报价记录、五条日线和720条分钟线。五条日线包含一次定向补取，原始区间响应与补取响应都保留在材料中。

如果先想核对本文结果，可以离线运行：

python3 attachments/collect_us_observation.py --offline evidence --out my_check

它会生成报价 CSV、日线 CSV、分钟线 CSV 和检查报告。本篇保存样本输出 PASS；若仍有缺日，报告保留 CHECK_REQUIRED。输出目录必须是新目录，避免覆盖已有记录。

随文另有事件观察表生成脚本，把官方事件信息与报价 CSV 放到同一份表中，运行方法见 README。

常见问题：先把一只股票的快照和一小段历史跑通

刚开始接美股API，先做哪一步

先挑一只目标股票，取得一份快照和一小段历史数据。把页面要展示的返回项、时段和数据时间确认下来，再扩展股票池与更新方式。免费账号是否支持所需范围，先按当前文档核对。

价格或曲线看起来不对，从哪里排查

先看原始返回，再核证券、返回项、数据时间、周期、复权和日期覆盖。本篇区间日线缺日，定向补取后取得记录，就是需要把结果保存下来再核对的一类情况。

这套结果还能用在哪里

相同的报价与时间记录，可以交给研究表、监控任务或 AI 助手。AI 回答行情问题时，也应保留返回项、数据时间和来源；提醒或持续监控则要增加相应的更新与异常处理。

最后，先把一张行情页交付清楚

美股 API 接入的第一份有用成果，可以很小：一张显示返回项与时间的报价表，一段范围清楚的历史走势，再加一份能找到来源的事件记录。

这次特斯拉样本中，常规收盘、盘后和夜盘分别有自己的价格，日线还经历了一次缺日补取。把这些差异保留下来，产品经理才能检查页面含义，技术同事才能定位取数与展示问题。

我自己跑完这一遍，最先改的不是脚本，是页面上的时间标注。

用自己的目标证券跑一次，先核对页面上的主价格和曲线截止时间。这两处说清楚以后，再增加更多标的和功能。

本文样本采集于2026年10月22日。价格用于展示数据接入方法，不构成投资建议。

参考资料与随文材料

[特斯拉三季报发布公告]及[此前发布安排]：事件日期、盘后发布安排与问答会时间。
TickDB：行情快照、K线查询、交易日历、交易时段：当前字段、参数与查询条件。
[FINRA：Extended-Hours Trading—Know the Risks]：扩展时段交易的市场背景。
[本文实测材料]：真实REST响应、参数与时间、运行脚本、CSV、检查报告及事件观察表。