USData.get_snapshots 美股即時快照

所屬章節：Data 表格查詢 以 2026-09-10 實際執行結果為準

Overview

取一批美股股票的即時報價快照。這是拉取式的一次性查詢。

api.USData.get_snapshots(symbols)

參數	型態	說明
symbols	list[str]	美股代號清單（如 ['AAPL', 'MSFT']）

回傳 dict[str, Symbol]，key 是股票代號。

只有美股 api.USData 有這個方法。台股 api.Data 不含 get_snapshots。 台股要盤中資料請用 api.Data.get(...) 的分K／逐筆查詢，見 intraday.md。

Manual Sample Input/Output

Example 1：取兩檔

input

s = api.USData.get_snapshots(['AAPL', 'MSFT'])
print(type(s).__name__, len(s), list(s))
s['AAPL']

output

dict 2 ['AAPL', 'MSFT']

Symbol(timestamp='20260910160000000', open=316.67, high=326.74, low=316.51,
       close=326.57, volume=70011913, previousClose=315.34,
       netChange=11.23, percentChange=3.56)

---

Example 2：Symbol 欄位

欄位	型態	說明
timestamp	str	報價時間，格式 yyyyMMddHHmmssSSS（毫秒）
open / high / low / close	float	當日開 / 高 / 低 / 最新（收）價
volume	int	當日累計成交量
previousClose	float	昨收價
netChange	float	漲跌（相對昨收）
percentChange	float	漲跌幅（%），已算好

Symbol 是 dataclass，可用 dataclasses.asdict() 轉 dict：

from dataclasses import asdict
asdict(s['AAPL'])

{'timestamp': '20260910160000000', 'open': 316.67, 'high': 326.74,
 'low': 316.51, 'close': 326.57, 'volume': 70011913,
 'previousClose': 315.34, 'netChange': 11.23, 'percentChange': 3.56}

---

Example 3：漲跌幅直接讀

台股的 Stock 沒有漲跌幅要自己算；美股的 Symbol 已經帶好 netChange 與 percentChange，直接讀即可：

d = s['AAPL']
print(f"{d.netChange:+.2f} ({d.percentChange:+.2f}%)")

+11.23 (+3.56%)

---

注意

• 盤後執行拿到的是最後一筆收盤快照，timestamp 停在收盤時間（如上例 160000000 = 16:00 收盤）。
• 美股 Symbol 與台股 Stock 欄位不同：美股沒有五檔（買賣價量）、沒有漲停跌停， 但多了現成的 netChange / percentChange。