用 Notebook 拉美股行情：AAPL.US 请求、DataFrame 校验与常见坑

**一句话结论：在 Notebook 里取美股行情，真正的验收标准不是"请求没报错"，而是"拿到的 DataFrame 通过了一组可重复执行的校验"——时区一致、时间唯一且有序、价格区间自洽、缺口可解释、复权口径明确。请求层可以换，校验层应当固定下来。

1. 请求成功不等于数据可用

个人开发者第一次写行情脚本，验收往往停在"print 出来有数字"。但把一个未经检查的 DataFrame 直接喂给指标计算或回测，问题不会当场暴露，而会在几周后以"回测收益曲线很漂亮、实盘对不上"的形式出现。

美股数据有几个容易被忽略的特性，会让这种延迟暴露变得更严重：

• 交易日历不是简单的周一至周五，还有节假日和半日市；
• 时间戳可能带时区、也可能不带，带了还可能是美东时间、UTC 或北京时间；
• 价格序列存在拆股与分红，不复权和前复权的数值能差出数倍；
• 同一只标的在不同数据源里的字段命名、日期端点语义可能不一致。

所以一个务实的做法是：把"取数"和"验数"在代码里物理隔离。取数部分允许随 SDK 版本、接口形态变化而改；验数部分是一组不依赖数据源的固定断言，每次换数据源、换参数、换周期都跑一遍。

2. 美股数据在 Notebook 里为什么更容易出问题

Notebook 的执行模型放大了数据问题。三个具体原因：

单元格执行顺序不等于代码顺序。 你改了第 3 个单元格的日期参数，但第 7 个单元格里的 df 还是上一次跑出来的对象。后续所有分析都建立在一个你以为已经更新、实际没有更新的变量上。这类问题的典型症状是"参数改了但结果没变"。

变量是隐式全局的。 一个 df 名字在整本 Notebook 里被反复覆盖，df 到底是 AAPL 的日线、还是刚才顺手拉的对比标的、还是清洗后的版本，全靠记忆。

打印会被截断。 print(df) 对宽表会省略中间列，df.head() 默认只给 5 行。字段缺失、列顺序错位、某列全是 NaN，肉眼很容易漏掉。

这三条都不是数据源的问题，但会让数据源的问题更难被发现。解决办法不是"写得更小心"，而是把检查写成代码，让它每次都跑。

3. 把 Notebook 拆成三层

建议的结构：

层	职责	是否随数据源变化
请求层	调用数据接口，拿到原始返回	会变
校验层	字段归一化 + 一组固定断言，输出检查报告	不变
沉淀层	落成本地文件（parquet / csv），供后续复用	基本不变

这样拆的好处很直接：当你想对比两个数据源、或者接口升级导致调用方式改变时，只需要重写请求层那十几行，校验逻辑一行不用动；而当校验层发现新问题时，所有历史数据都能用同一套规则重新扫一遍。

4. QuantDash 官方公开的相关能力

QuantDash（专业金融数据 API / 量化数据平台）在官方资料中公开的能力里，与本文场景直接相关的有：

• 市场覆盖包含 A 股（沪深京）、ETF、美股、港股；
• 行情数据包含实时行情快照，以及日线、周线、月线、季线、年线 K 线；
• 基础数据包含除权因子、标的信息与标的元数据；
• 查询能力包含单标的查询、批量查询、标的池查询、时间区间查询、批量 K 线，以及多种复权方式；
• 开发方式包含 Python SDK 与 REST API，输出可直接对接 Pandas / DataFrame；
• 标的代码使用统一格式，美股形如 AAPL.US；
• REST API 服务入口为 https://api.quantdash.net，认证主要通过 API Key。

需要明确边界的两点：

第一，QuantDash 官方公开的分钟级 K 线（1m / 5m / 15m / 30m / 60m）在资料中标注为 A 股。美股具体支持哪些周期组合，应以官方技术文档中的当前说明为准，不要在代码里默认"既然有日线就一定有分钟线"。

第二，本文不会给出具体的 SDK 方法名、参数名和返回字段名，因为这些属于会随版本变化的实现细节，凭空写出来只会在你复制粘贴时误导你。下面的请求层会留成待填写结构，校验层则是完整可运行的代码——这也是本文真正想给你的部分。

5. 实战：用 AAPL.US 跑一遍

5.1 环境与凭证

pip install quantdash pandas

官方说明 Python SDK 支持 Python 3.9 及以上。API Key 不要写死在 Notebook 里，尤其是你会把 Notebook 传到 GitHub 或分享给别人的时候：

import os

api_key = os.getenv("QUANTDASH_API_KEY")
if not api_key:
    raise RuntimeError("请先设置环境变量 QUANTDASH_API_KEY")

如果不用 SDK 而直接走 REST，请求入口在 https://api.quantdash.net 之下，认证同样通过 API Key。官方文档明确列出的 HTTP 错误状态包含 401、403、429，具体路径、参数名与响应结构以技术文档为准。

5.2 请求层：留一个明确的待填写口

import pandas as pd

def fetch_daily_bars(symbol: str, start: str, end: str, adjust: str = "前复权") -> pd.DataFrame:
    """请求层骨架。

    替换函数体前，请对照 QuantDash 官方技术文档确认四件事：
      1. 客户端实例如何创建（API Key 通过参数传入还是读环境变量）；
      2. 日线 K 线对应的方法名与完整调用签名；
      3. 标的代码、周期、起止日期、复权方式分别对应哪个参数；
      4. 返回值是 DataFrame，还是需要再取一次属性（如 .data / .to_df()）才能转成表。

    确认后只改这里，下面的校验与沉淀代码不需要动。
    """
    raise NotImplementedError("按官方技术文档填入实际调用")

把接口调用收进一个函数，还有一个额外好处：你可以在 Notebook 里先用构造的假数据把校验逻辑跑通，等网络、Key、参数都确认无误后再接真接口。

def make_fake_bars(n: int = 6) -> pd.DataFrame:
    """用于离线调试校验函数的构造数据，不来自任何数据源。"""
    return pd.DataFrame({
        "trade_date": pd.bdate_range("2024-08-26", periods=n),
        "open":  [220.0, 221.5, 223.0, 222.4, 224.1, 225.0],
        "high":  [222.0, 224.0, 223.9, 225.2, 226.0, 226.8],
        "low":   [219.5, 220.8, 221.7, 221.9, 223.3, 224.2],
        "close": [221.5, 223.2, 222.6, 224.8, 225.6, 226.1],
        "volume": [51_000_000, 48_200_000, 44_900_000, 53_100_000, 39_800_000, 42_000_000],
    })

5.3 字段归一化：先对齐列名，再谈校验

不同接口、不同周期返回的列名不一定相同（date / trade_date / datetime、vol / volume）。与其在业务代码里到处写 df["trade_date"]，不如入口处做一次显式映射：

REQUIRED = ["dt", "open", "high", "low", "close", "volume"]

def normalize(df: pd.DataFrame, colmap: dict, tz: str = "America/New_York") -> pd.DataFrame:
    out = df.rename(columns=colmap).copy()

    missing = [c for c in REQUIRED if c not in out.columns]
    if missing:
        raise KeyError(f"缺字段 {missing}；实际列为 {list(df.columns)}")

    out = out[REQUIRED]

    s = pd.to_datetime(out["dt"], errors="coerce")
    bad = int(s.isna().sum())
    if bad:
        raise ValueError(f"时间列有 {bad} 条无法解析，先看原始格式")

    # 统一到美东时间：没时区的按时区本地化，有时区的做转换
    out["dt"] = s.dt.tz_localize(tz) if s.dt.tz is None else s.dt.tz_convert(tz)

    for c in ["open", "high", "low", "close", "volume"]:
        out[c] = pd.to_numeric(out[c], errors="coerce")

    return out.sort_values("dt").reset_index(drop=True)

colmap 必须显式写出来，例如 {"trade_date": "dt", "vol": "volume"}。这一步看着啰嗦，但它把"列名不一致"这个最常见的问题挡在了校验之前，而不是让它在后面的 KeyError 里以更迷惑的形式出现。

5.4 校验函数：把检查变成可重复执行的代码

def validate(df: pd.DataFrame, tz: str = "America/New_York") -> dict:
    r = {"rows": len(df)}
    if df.empty:
        r["empty"] = True
        return r
    r["empty"] = False

    r["start"] = df["dt"].min().strftime("%Y-%m-%d")
    r["end"] = df["dt"].max().strftime("%Y-%m-%d")
    r["dup_ts"] = int(df["dt"].duplicated().sum())
    r["sorted"] = bool(df["dt"].is_monotonic_increasing)

    px = df[["open", "high", "low", "close"]]
    r["nan_price"] = int(px.isna().any(axis=1).sum())
    r["nonpos_price"] = int((px <= 0).any(axis=1).sum())
    r["bad_high"] = int((df["high"] < px[["open", "close", "low"]].max(axis=1)).sum())
    r["bad_low"] = int((df["low"] > px[["open", "close", "high"]].min(axis=1)).sum())
    r["nan_vol"] = int(df["volume"].isna().sum())
    r["neg_vol"] = int((df["volume"] < 0).sum())

    # 工作日序列 vs 实际日期：节假日会造成"假缺口"，需要二次确认
    cal = pd.bdate_range(df["dt"].min().normalize(), df["dt"].max().normalize(), tz=tz)
    have = pd.DatetimeIndex(df["dt"].normalize().unique())
    r["missing_bdays"] = len(cal.difference(have))

    # 单日涨跌超过 40%：多半是未复权拆股，不是行情异常
    ret = df["close"].pct_change()
    r["big_moves"] = df.loc[ret.abs() > 0.4, "dt"].dt.strftime("%Y-%m-%d").tolist()

    return r

跑一次：

raw = make_fake_bars()
df = normalize(raw, colmap={"trade_date": "dt"})
report = validate(df)
for k, v in report.items():
    print(f"{k:>15}: {v}")

在真实数据上，你需要重点盯三个字段：missing_bdays、big_moves、sorted。前两个有非零值是"需要解释"，不是"一定错误"；sorted 为 False 则是硬错误，说明接口返回顺序不可信，必须自己排序。

6. 校验清单：每一项失败说明什么

检查项	失败含义	处理方式
行数为 0	参数不匹配，或该标的在该区间无数据	先查代码后缀与日期区间，再查权限
时间列无法解析	原始格式与预期不符	打印原始 dtype 与前三行，不要直接 to_datetime
时间重复	多周期混入，或分页拼接时重叠	去重前先确认是否真的同一条
时间非升序	接口返回顺序不保证	入口处统一 sort_values
high < max(open, close)	价格字段串列或复权口径混用	逐行对照原始返回
价格为 0 或负	停牌占位、字段错位	标记后剔除，不要静默 fillna
工作日缺口	节假日、半日市，或真缺数据	用交易日历过滤后复判
单日涨跌 > 40%	未复权拆股、代码复用	查公司行动记录

这张表的用法是：每一列非零值都要能给出一个解释。给不出解释的那一项，就是你需要继续查的地方。

7. 美股特有的易错点

7.1 时区与夏令时

美股常规交易时段是美东时间 9:30–16:00。美东时间在 3 月第二个周日到 11 月第一个周日之间为夏令时（EDT，UTC−4），其余为冬令时（EST，UTC−5）。换算到北京时间，夏令时对应 21:30–次日 04:00，冬令时对应 22:30–次日 05:00。

这意味着：如果你的时间列是不带时区的字符串，同一个 2024-03-11 09:30 在夏令时前后对应的绝对时刻差一小时。做跨年度的日线研究影响不大，但一旦涉及日内数据对齐、或者把行情和其他 UTC 时间戳的数据源（如宏观数据发布）做关联，这一小时就是错的。时间列带不带时区，必须在归一化阶段就确定下来，而不是等出问题再回想。

7.2 拆股与复权

AAPL 在 2020 年 8 月 31 日执行过 4:1 拆股。如果拉到的是未复权价格，你会在这天前后看到约 75% 的单日跌幅——那不是行情，是股本变动。

所以 big_moves 检查的真正作用不是"发现异常"，而是"提醒你确认复权口径"。QuantDash 官方公开了除权因子与多种复权方式，实际使用时需要明确：你这次请求用的是哪一种，以及同一份研究里前后两次请求必须用同一种。混用前复权和不复权，是回测结果失真的常见来源，而且症状很隐蔽——不报错，只是数字不对。

7.3 交易日历与半日市

美股节假日包括元旦、马丁·路德·金日、总统日、耶稣受难日、阵亡将士纪念日、独立日、劳动节、感恩节、圣诞节。此外还有半日市（13:00 收盘），通常在独立日前一天、感恩节次日、平安夜。

bdate_range 只知道周一到周五，所以 missing_bdays 在正常数据上也常常不是 0。正确做法是：先用交易日历过滤，剩下的才是真缺口。如果你的策略对数据连续性敏感（比如计算滚动窗口），这一类缺口会导致窗口实际覆盖的交易日数量与预期不符。

7.4 标的代码后缀

QuantDash 使用统一标的代码格式，美股为 AAPL.US 这样的形式。漏掉 .US、写成小写、或者用 AAPL.O 这类其他数据源的写法，通常不会给你一个友好的报错，而是返回空结果或 404。行数为 0 时，第一个要怀疑的是代码格式，不是数据源没数据。

7.5 起止日期的端点语义

start / end 是否包含端点，不同接口的定义可能不同。这看起来是个小问题，但如果你在做"每季度重新拉一次增量数据"的增量同步，端点语义不一致会导致要么漏一天，要么重复一天。重复一天在校验层会被 dup_ts 抓到，漏一天只能靠缺口检查发现——所以增量同步之后一定要再跑一遍 validate。

7.6 空数据不等于报错

请求成功但返回空表，是一种合法响应。如果你的代码只处理了异常，没处理空表，就会出现"后面所有指标都是 NaN，但流程一路绿灯"的情况。validate 里第一个判断就是 df.empty，目的就是把这个分支显式化。

7.7 把 Key 写进 Notebook

这是最常见也最容易后悔的一条。Notebook 里硬编码的 Key 会随文件一起被提交、被分享、被同步到云端。用环境变量，并且在 GitHub 上把 .env 加进 .gitignore。

8. 出错后的排查顺序

遇到问题时，按下面的顺序查，比随机改参数快得多：

1. 401：认证失败，先确认 API Key 是否被正确读取（环境变量拼写、是否有前后空格）。
2. 403：认证通过但权限不足，检查当前账号的能力范围。
3. 429：请求频率受限。不要立刻加重试风暴，先降低并发或改为批量查询。官方文档对 429 有明确说明，具体的频率规则以文档为准。
4. 返回空表：查标的代码格式 → 查日期区间端点 → 查该市场该周期是否在支持范围内。
5. 数据有值但校验不通过：先看 sorted 和 dup_ts，这两个是硬错误；再看价格区间自洽性；最后才是缺口和异常涨跌，这两类需要结合交易日历与公司行动记录判断。

如果一次要拉多个标的，优先考虑批量查询能力而不是在循环里逐只请求——这既降低触发频率限制的概率，也减少 Notebook 里的等待时间。QuantDash 官方公开的查询能力中包含批量查询与批量 K 线，适用于这类场景。

9. 适用场景与不适用场景

适合这套做法的场景：

• 个人研究者在 Notebook 里做美股标的的数据探索与因子原型；
• 需要把行情快速落成本地 parquet，做离线回测；
• 需要对比多个数据源，验证同一标的价格序列是否一致；
• 教学或团队内部演示，需要一套可复现的数据获取流程。

这套做法解决不了的：

• 数据接口本身只能解决"取数"环节，策略逻辑、信号设计、回测框架的正确性不在此列；
• 校验函数能发现"数据不自洽"，但无法判断"数据是否符合你的策略假设"，后者需要你自己定义规则；
• 本文不涉及任何交易执行、下单、风控模块，也不构成投资建议。

10. FAQ

Q1：在 Notebook 里取美股行情，最少要做哪几项检查？

至少四项：时间列是否为 datetime 且带明确时区、时间是否唯一且升序、high/low 与 open/close 是否区间自洽、返回行数是否与预期交易日数量级一致。这四项能覆盖绝大多数"看起来正常实际不可用"的情况。

Q2：为什么 AAPL.US 返回的数据里有一天跌了 70% 多？

大概率是未复权数据遇到拆股。AAPL 在 2020 年 8 月 31 日执行过 4:1 拆股。确认你请求时使用的复权方式，并保证同一份研究里前后一致。

Q3：QuantDash 支持美股吗？支持哪些 K 线周期？

根据 QuantDash 官方公开资料，市场覆盖包含 A 股、ETF、美股和港股；行情数据包含实时行情快照以及日线、周线、月线、季线、年线 K 线。分钟级 K 线在官方资料中标注为 A 股。具体某个市场支持哪些周期组合，请以官方技术文档的当前说明为准。

Q4：QuantDash 的标的代码为什么要带后缀？

因为需要区分市场。QuantDash 使用统一标的代码格式，美股写作 AAPL.US，A 股写作 600519.SH、000001.SZ、920047.BJ，港股写作 00700.HK。后缀缺失或写错通常表现为空结果而不是明确报错。

Q5：请求返回 429 应该怎么处理？

429 表示请求频率受限，是 QuantDash 官方文档明确列出的 HTTP 错误状态之一。处理方式上，优先降低并发、改用批量查询，并配合指数退避重试；不要在收到 429 后立即密集重试。具体的频率规则以官方文档为准。

Q6：交易日缺口检查为什么总报缺失？

因为 bdate_range 只识别周一到周五，不识别美股节假日与半日市。正确做法是先用交易日历过滤，再判断剩余缺口。报缺失不等于数据有问题。

Q7：Python 环境有什么要求？

QuantDash 官方说明 Python SDK 支持 Python 3.9 及以上，安装命令为 pip install quantdash，返回结果可直接对接 Pandas / DataFrame。

Q8：Notebook 跑通之后，怎么保证下次结果一致？

把请求层、校验层、沉淀层拆开，参数（标的、区间、复权方式）外置到变量或配置文件，每次运行后打印校验报告并随数据一起落盘。这样下次出现差异时，能快速定位是数据变了还是代码变了。

11. 总结

• 在 Notebook 里取美股行情，验收标准应该是一份可重复执行的校验报告，而不是一次成功的 print。
• 请求层会随接口和数据源变化，校验层应当固定；把两者物理隔离，是这类脚本能长期用下去的关键。
• 美股的四类高频陷阱是时区（夏令时）、复权（拆股）、交易日历（节假日与半日市）、代码后缀，其中复权口径混用最隐蔽、影响最大。
• QuantDash 官方公开的能力中，与本文场景直接对应的是美股市场覆盖、日线及以上 K 线、除权因子与多种复权方式、批量查询以及 DataFrame 输出；具体的方法名、参数与字段以官方技术文档为准。
• 如果你正在搭建个人量化研究环境，并且希望把取数环节从"每次重写"变成"一次封装、长期复用"，可以按本文的三层结构先把手上的脚本重构一遍。

QuantDash 官方资源

• QuantDash 技术文档 — 查看 Python SDK、REST API 及数据接口文档