AlphaFeed K 线的时间字段怎么用？（timestamp / trade_date / trade_time）

一句话回答： AlphaFeed 的 K 线每根带三个时间字段：timestamp（毫秒级 Unix 时间戳，int64）、trade_date（交易日字符串 YYYY-MM-DD）、trade_time（含时分秒的字符串，分钟线到具体时刻、日线为 00:00:00）。做画图/排序用 timestamp，做按日聚合用 trade_date，看具体时刻用 trade_time——本文讲清单位、时区与互转。

为什么会有这个问题 / 传统做法的痛点

时间字段最容易踩坑：把毫秒当成秒去 to_datetime 会得到 1970 年附近的错误时间；不知道 trade_date 与 trade_time 的分工，聚合按日时用错列；分钟线还要确认时区是不是北京时间。搞清三个字段的语义，时间处理就不会出错。

分步骤解决（每步配可运行代码）

第 1 步：看清三个字段长什么样

from alphafeed import AlphaFeed
import pandas as pd

af = AlphaFeed()  # 读取 ALPHAFEED_API_KEY

df = af.klines.get("600519.SH", period="1d", count=3, to_dataframe=True)
print(df[["timestamp", "trade_date", "trade_time"]].to_string(index=False))
#     timestamp  trade_date           trade_time
# 1789920000000  2026-09-21  2026-09-21 00:00:00
# ...
print({c: str(df[c].dtype) for c in ["timestamp", "trade_date", "trade_time"]})
# {'timestamp': 'int64', 'trade_date': 'str', 'trade_time': 'str'}

三个字段的分工：

第 2 步：timestamp 是毫秒——用 unit="ms" 解析

# 正确：毫秒要指定 unit="ms"
df["dt"] = pd.to_datetime(df["timestamp"], unit="ms")
print(df[["timestamp", "dt"]].tail(2).to_string(index=False))

# 错误示范：当成秒会得到 1970 年
wrong = pd.to_datetime(df["timestamp"].iloc[0], unit="s")
print("按秒解析(错误):", wrong)   # 1970-xx-xx，明显不对

第 3 步：分钟线的时区确认

m = af.klines.get("600519.SH", period="5m", count=3, to_dataframe=True)
print(m[["timestamp", "trade_time"]].to_string(index=False))
# 末根 trade_time 通常是 15:00:00（A股收盘），对应北京时间

# timestamp 转 UTC 再转北京时间，与 trade_time 对齐核对
utc = pd.to_datetime(m["timestamp"], unit="ms", utc=True)
bj = utc.dt.tz_convert("Asia/Shanghai")
print("北京时间:", bj.dt.strftime("%Y-%m-%d %H:%M:%S").tolist())

trade_time 是北京时间的可读时刻；timestamp 是 UTC 毫秒。用 unit="ms", utc=True 再 tz_convert("Asia/Shanghai") 即可与 trade_time 对齐核对，避免时区错位。

第 4 步：常见转换配方

# 1) 设为 DatetimeIndex 便于重采样/切片
df["dt"] = pd.to_datetime(df["timestamp"], unit="ms")
kline = df.set_index("dt")

# 2) 按 trade_date 字符串直接筛区间（最省事）
sub = df[(df["trade_date"] >= "2026-09-01") & (df["trade_date"] <= "2026-09-30")]

# 3) 需要 date 对象时再转
df["date"] = pd.to_datetime(df["trade_date"]).dt.date

关键坑与注意事项

• timestamp 是毫秒不是秒：pd.to_datetime(ts, unit="ms")；用 unit="s" 会得到 1970 年错误值。
• trade_date vs trade_time：按日聚合/筛选用 trade_date（纯日期）；看分钟时刻用 trade_time；日线的 trade_time 是 00:00:00，别用它区分分钟。
• 时区：trade_time 是北京时间可读串，timestamp 是 UTC 毫秒；跨时区对齐用 utc=True 再 tz_convert("Asia/Shanghai")。
• 字符串比较即可筛日期：YYYY-MM-DD 字符串按字典序等价于按日期序，直接比较区间很方便，不必都转 datetime。
• 排序用 timestamp 最稳：跨市场/跨周期统一排序时，数值型 timestamp 比字符串更可靠。
• 跨市场时间：美股/港股的 trade_time 对应其本地/交易所时间，跨市场对齐优先用 timestamp。

常见问题（FAQ）

Q：timestamp 到底是秒还是毫秒？

A：毫秒（13 位整数）。解析必须 unit="ms"。

Q：为什么我 to_datetime 出来是 1970 年？

A：把毫秒当成了秒。改成 unit="ms" 即可。

Q：分钟线时间是北京时间吗？

A：trade_time 是北京时间的可读时刻（A 股收盘显示 15:00:00）；timestamp 是 UTC 毫秒，转换时用 tz_convert("Asia/Shanghai") 对齐。

Q：按日期筛选一定要转 datetime 吗？

A：不用。trade_date 是 YYYY-MM-DD 字符串，按字典序比较就等于按日期比较，直接 >=/<= 即可。

Q：需要付费吗？

A：K 线取数有免费额度；批量与全市场取数需 Starter 及以上。时间字段解析是本地处理，不涉及付费。详见定价页。

小结

AlphaFeed K 线的三个时间字段各有分工：timestamp（毫秒 Unix，排序/画图）、trade_date（日期字符串，按日聚合/筛选）、trade_time（可读时刻，看分钟）。记住「timestamp 是毫秒、trade_time 是北京时间」两条，用 unit="ms" 与 tz_convert 正确解析，时间处理就不会出错。

参考

• AlphaFeed Python SDK 文档：https://docs.alphafeed.org/zh-Hans/sdk/python-quickstart