USData 美股表格查詢

所屬章節：Data 表格查詢以 2026-08-21 實際執行結果為準（資料日 2026-08-20）本頁 25 張表全部實跑過，形狀與欄位是真實輸出

Overview

api.USData 是美股的表格式查詢：一次拿一張 pandas.DataFrame。與 api.USMSMP（矩陣式，日期 × 股票代號）分工如下：

	`api.USData`	`api.USMSMP`
形狀	一張表一個主題，欄位是欄名	日期 × 股票代號的矩陣
適合	看單一標的的完整財報、分K、明細	跨全市場算指標、選股
資料日	到前一交易日；盤中表另有即時值	到前一交易日

三個方法：

api.USData.get_table()              # 印出所有表名與必填參數（不回傳值）
api.USData.get(table, *args)        # 取一張表 -> DataFrame
api.USData.get_snapshots(symbols)   # 即時快照 -> dict[str, Symbol]

get(table: str, *args) -> pandas.DataFrame。沒有關鍵字參數，全部照位置傳，順序見 get_table() 印出的提示。

資料表清單

get_table() 只印出來、回傳 None（型態是 NoneType），所以不能拿回傳值去列舉表名——要程式化處理請照抄下面的清單。

不需要參數（多檔股票最新時間）

表名	形狀	欄位
`美股產業對照表`	(13187, 21)	`股票代號`、`股票名稱`、`粗產業名稱`、`細產業名稱`、`是否為ETF`、`股票名稱(中文)`、`粗產業名稱(中文)`、`細產業名稱(中文)`、`市值(美元)`、`流通股數`、`員工人數`、`股東人數`、`經營概述`、`產業地位` 及其英文／簡中版本
`EPS/本益比/殖利率-多檔股票最新時間`	(5796, 7)	`股票代號`、`股票名稱`、`昨日收盤價`、`本益比`、`殖利率`、`公告累計EPS(元)`、`近四季EPS(元)`
`ROE/ROA-多檔股票最新時間`	(5635, 5)	`股票代號`、`股票名稱`、`年季`、`ROE-稅後權益報酬率(%)`、`ROA-稅後資產報酬率(%)`
`日K價量資料(個股、ETF)-多檔股票最新時間`	(13167, 10)	`股票代號`、`股票名稱`、`日期`、`開盤價`、`最高價`、`最低價`、`收盤價`、`成交量`、`漲跌`、`漲跌幅(%)`
`取得美股盤後收盤價-多檔股票最新時間`	(13531, 8)	`股票代號`、`日期`、`開盤價`、`最高價`、`最低價`、`收盤價`、`成交量`、`更新時間`
`取得當前所有產業資金流`	(145, 6)	`日期`、`產業名稱`、`買入金額`、`賣出金額`、`資金淨流`、`percentChange`

美股產業對照表 有 4 個長文字欄（經營概述 / 產業地位 的中英簡三版），單筆可達數千字。只要分類的話取 ['股票代號','粗產業名稱','細產業名稱','是否為ETF','市值(美元)'] 就好。

需要 `symbol`（單檔股票多個區間）

表名	形狀（AAPL）	欄位
`日K價量資料(個股、ETF)-單檔股票多個區間`	(1000, 22)	日期、代號、名稱、OHLC、`成交量`、`漲跌`、`漲跌幅(%)`，外加 `5/10/20/60/125/250日均價` 與 `5/10/20/60/125/250日均量`
`週K價量資料(個股、ETF)-單檔股票多個區間`	(235, 13)	同上但均線只有 `5MA`、`20MA`、`60MA`
`月K價量資料(個股、ETF)-單檔股票多個區間`	(49, 13)	同週K
`個股營收資訊-單檔股票多個區間`	(110, 14)	`年季`、`單季/累計合併營收(千)`、季變動與年成長率、毛利／營益／稅前／稅後／總資產／淨值成長率
`個股資本支出-單檔股票多個區間`	(30, 4)	`年度`、`資本支出(千)`、`固定資產(千)`
`個股股利資訊(年)-單檔股票多個區間`	(30, 4)	`年度`、`股利合計(元)`、`殖利率`
`季稅後淨利/季稅後EPS-單檔股票多個區間`	(114, 6)	`年季`、`日期`、`公告日`、`稅後純益(千)`、`每股稅後盈餘(元)`
`季毛利率/季營益率/ROE-單檔股票多個區間`	(114, 7)	`年季`、`日期`、`公告日`、`毛利率(%)`、`營業利益率(%)`、`ROE–稅後權益報酬率(%)`
`個股季財報資訊-單檔股票多個區間`	(110, 81)	完整三表＋比率，見下方說明
`近四季財報加總-單檔股票多個區間`	(111, 24)	`近四季公告EPS(元)`、近四季營收／毛利／淨利／三大現金流、`最近一季之加權平均流通在外股數(千)` 等
`取得個股內外盤-單檔股票多個區間`	(589, 5)	`日期`、`股票代號`、`買量(股)`、`賣量(股)`、`資金淨流`
`分價量`	(1951, 5)	`股票代號`、`日期`、`類型`、`價格`、`成交量`
`取得最新一筆成交明細`	(1, 11)	`timestamp`、代號、OHLC、`成交量`（該筆）、`當日成交量`、`上個交易日的收盤價`、`漲跌`、`漲跌幅(%)`

需要多個參數

表名	參數	形狀
`取得指定日期前幾天的分價量歷史資料`	`symbol`、`endDate`（`yyyyMMdd`）、`days`	(62, 4)
`取得全天含盤前盤後歷史分k(最後交易日)`	`symbol`、`market`（`F`全天／`P`盤前／`M`盤中／`A`盤後）	(946, 8)
`取得歷史1/3/5/15/30/60分K`	`symbol`、`minutes`（1／3／5／15／30／60）	(999, 8)

三張分K表的欄位相同：股票代號、日期、hhmm、開盤價、最高價、最低價、收盤價、成交量。 日期與時間是分開兩欄（日期 是 date、hhmm 是 4 位字串），要合併得自己組。

需要 `List[symbol]`（批次盤中）

表名	形狀（傳 2-3 檔）	欄位
`批次取得個股盤中多筆分K`	(780, 8)	同分K表
`批次取得個股盤中最新行情`	(3, 10)	`timestamp`、代號、OHLC、`當日成交量`、`上個交易日的收盤價`、`漲跌`、`漲跌幅(%)`
`批次取得個股盤中內外盤`	(2, 5)	`日期`、`股票代號`、`買量(股)`、`賣量(股)`、`資金淨流`

Manual Sample Input/Output

Example 1：日K 價量（單股，含均價與均量）

input

df = api.USData.get('日K價量資料(個股、ETF)-單檔股票多個區間', 'AAPL')
print(df.shape)
df.head(2)

output

(1000, 22)

          日期  股票代號       股票名稱      開盤價      最高價      最低價      收盤價      成交量     漲跌  漲跌幅(%)    5日均價   10日均價        5日均量
0 2022-08-25  AAPL  APPLE INC 168.7800 170.1400 168.3500 170.0300 51218209 2.5000  1.4900 168.7760 171.0900 59715988.4000
1 2022-08-26  AAPL  APPLE INC 170.5700 171.0500 163.5600 163.6200 78961000 -6.4100 -3.7700 167.1960 170.2420 61438928.4000

固定給最近 1000 個交易日，由舊到新排序。均價／均量欄位已經算好，不需要自己 rolling。

成交量 的單位是股，不是張。 台股 api.Data 的成交量是張（1 張 = 1000 股），兩邊直接相比會差 1000 倍。

Example 2：分K（三種取法）

input

# 標準分K：symbol + 分鐘數
df = api.USData.get('取得歷史1/3/5/15/30/60分K', 'NVDA', 5)
df.head(2)

output

(999, 8)

  股票代號         日期  hhmm      開盤價      最高價      最低價      收盤價     成交量
0  NVDA 2026-08-04  1050 210.1300 211.0399 209.9900 210.9200 1593932
1  NVDA 2026-08-04  1055 210.9025 211.0200 209.3545 209.5950 1982633

input

# 含盤前盤後：最後一個交易日，market 決定盤別
df = api.USData.get('取得全天含盤前盤後歷史分k(最後交易日)', 'AAPL', 'F')
df.head(1)

output

(946, 8)

  股票代號         日期  hhmm      開盤價      最高價      最低價      收盤價    成交量
0  AAPL 2026-08-20  0400 316.0315 316.8300 315.5000 315.6000  14553

hhmm='0400' 是美東時間 4:00（盤前）。market 傳 'M' 只會拿到盤中那段，並且會印出一行交易時間提示（此為美股(紐約)交易時間: M(盤中):9:30 - 16:00）。

要組成 DateTime 索引——日期 欄本來就是 datetime64[ns]、hhmm 是 4 位字串：

df['DateTime'] = pd.to_datetime(
    df['日期'].astype(str) + df['hhmm'].astype(str).str.zfill(4),
    format='%Y-%m-%d%H%M')

Example 3：財報（三種粒度）

個股季財報資訊-單檔股票多個區間 是最完整的一張，81 欄，一次給三表加比率：

資產負債：資產(千)、流動資產(千)、現金及約當現金(千)、存貨(千)、負債(千)、股東權益(千) …
損益：營業收入(千)、營業成本(千)、營業毛利(千)、研究發展費用(千)、稅後純益(千)、EBIT(稅前息前淨利)(千) …
現金流：營業活動現金流量(千)、投資活動現金流量(千)、籌資活動現金流量(千)、自由現金流(千)、資本支出(千)
比率：毛利率(%)、營業利益率(%)、稅後權益報酬率(%)、負債比率(%)、流動比率(%)、存貨週轉率單季(次)、股價淨值比、企業價值對EBITDA比率 …
另有 財報發布日、股價、市值、股數(千)、本益比、每股股息

只要 EPS 或 ROE 的話用小張的更省：

eps = api.USData.get('季稅後淨利/季稅後EPS-單檔股票多個區間', 'AAPL')   # (114, 6)
roe = api.USData.get('季毛利率/季營益率/ROE-單檔股票多個區間', 'AAPL')  # (114, 7)
ttm = api.USData.get('近四季財報加總-單檔股票多個區間', 'AAPL')          # (111, 24)

三張都用 年季（例如 '2026-Q1'）當時間軸，並且有 公告日 可以避開前視偏誤。

Example 4：批次盤中行情

input

df = api.USData.get('批次取得個股盤中最新行情', ['AAPL', 'MSFT', 'NVDA'])
df

output

(3, 10)
columns: ['timestamp', '股票代號', '開盤價', '最高價', '最低價', '收盤價',
          '當日成交量', '上個交易日的收盤價', '漲跌', '漲跌幅(%)']

批次取得個股盤中內外盤 給買賣量與資金淨流：

          日期  股票代號    買量(股)    賣量(股)            資金淨流
0 2026-08-20  AAPL 10428586 13428416 -946373213.6530
1 2026-08-20  MSFT  6953991  4704988 1084683432.1550

批次表沒有明文的檔數上限，但傳越多回應越慢；要全市場請改用 api.USMSMP。

Example 5：產業資金流

input

df = api.USData.get('取得當前所有產業資金流')
df.head(2)

output

(145, 6)

          日期                       產業名稱           買入金額           賣出金額            資金淨流  percentChange
0 2026-08-20  Utilities - Regulated Water 157658842.6423 174145998.9061  -16487156.2638         0.1371
1 2026-08-20        Electronic Components 1938664200.2077 2064006536.7922 -125342336.5845        -1.3857

145 個產業，用的是 細產業名稱（英文），可以跟 美股產業對照表 的細產業名稱 欄對接——實測 145 個全部對得上（對照表共 146 個細產業，多的那個當日沒有資金流資料）：

flow = api.USData.get('取得當前所有產業資金流')
ind = api.USData.get('美股產業對照表')
m = flow.merge(ind[['股票代號', '細產業名稱', '市值(美元)']],
               left_on='產業名稱', right_on='細產業名稱')

Example 6：`get_snapshots` 即時快照

input

snaps = api.USData.get_snapshots(['AAPL', 'MSFT'])
s = snaps['AAPL']
{f: getattr(s, f) for f in ('close', 'open', 'high', 'low', 'volume',
                            'previousClose', 'netChange', 'percentChange', 'timestamp')}

output

{'close': 311.3, 'open': 317.455, 'high': 320.28, 'low': 310.65,
 'volume': 40959184, 'previousClose': 316.83,
 'netChange': -5.53, 'percentChange': -1.75,
 'timestamp': '20260820160000000'}

回傳 dict[str, Symbol]，key 是代號。Symbol 共 9 個欄位：

欄位	說明
`open` / `high` / `low` / `close`	當日 OHLC（`close` 是最新價）
`volume`	當日累計成交量（股）
`previousClose`	前一交易日收盤
`netChange` / `percentChange`	漲跌與漲跌幅（%），已經算好
`timestamp`	17 位字串 `yyyyMMddHHmmssSSS`，例如 `'20260820160000000'`

台股沒有快照方法：api.Data 不含 get_snapshots，只有美股 api.USData 有。美股 Symbol 有 9 欄且直接給了 netChange / percentChange。詳見 data-get-snapshots.md。

簽名也不同：美股是 get_snapshots(*args)，型別註記比台股鬆。傳 list 是可行的用法。

錯誤訊息

表名打錯是 KeyError，參數個數不對是 ValueError，而且會把正確用法印出來：

api.USData.get('不存在的表')
# KeyError: '不存在的表'

api.USData.get('日K價量資料(個股、ETF)-單檔股票多個區間')
# ValueError: 參數輸入錯誤，正確用法：
#   USData.get('日K價量資料(個股、ETF)-單檔股票多個區間', 'AAPL')

api.USData.get('日K價量資料(個股、ETF)-單檔股票多個區間', 'AAPL', 'extra')
# 同一個 ValueError —— 多傳也算錯

表名要完全一致，包含全形括號與斜線。常見打錯的是漏掉開頭的「取得」： '取得個股內外盤-單檔股票多個區間' 有「取得」，但 '個股營收資訊-單檔股票多個區間' 沒有。

注意

成交量單位是股，台股 api.Data 是張。跨市場比較前先換算。
日K 均線已內含在日K表（5~250日均價／5~250日均量），不必另取技術指標表。台股是分開兩張表。
年季 格式是 '2026-Q1' 字串，不是日期；要排序或對齊請先轉換。
財報表都有 公告日 / 財報發布日，做回測時用它而不是 年季 才不會前視。
盤中類表（分價量、取得最新一筆成交明細、批次*）的值會隨盤變動，非交易時段拿到的是最後一筆。

USData 美股表格查詢

Overview

資料表清單

不需要參數（多檔股票最新時間）

需要 symbol（單檔股票多個區間）

需要多個參數

需要 List[symbol]（批次盤中）

Manual Sample Input/Output

Example 1：日K 價量（單股，含均價與均量）

input

output

Example 2：分K（三種取法）

input

output

input

output

Example 3：財報（三種粒度）

Example 4：批次盤中行情

input

output

Example 5：產業資金流

input

output

Example 6：get_snapshots 即時快照

input

output

錯誤訊息

注意

需要 `symbol`（單檔股票多個區間）

需要 `List[symbol]`（批次盤中）

Example 6：`get_snapshots` 即時快照