開始使用 SnowyOwl

所屬章節：入門以 2026-08-21 實際執行結果為準（資料日 2026-08-20）

Overview

snowyowl 是資料 + 選股積木 + 回測的整合套件。兩行就能拿到可用的 api 物件：

import snowyowl as so
api = so.login('user@x.com', 'pwd')   # 或 so.login(type='google')

so.login(person_id, person_pwd, type='account')：帳密登入要帶帳號密碼；type='google'/'apple' 開瀏覽器登入。登入約 10-15 秒，含下載／更新本地 MSMP 快取。

先分流：你的問題屬於哪一類

三條路完全不同，走錯會繞遠路：

你要做的	走哪	起點
查一個事實——今天漲幅 5% 以上、台積電最近一個月、成交額前 10 名	`api.MSMP` 矩陣，通常一行	msmp.md、data-history.md
把多個條件 AND 起來篩股——突破 20 日高且外資買超且成交額佔比 >1%	積木 `api.Block`	block.md
驗證一組規則能不能賺錢	回測 `api.bt`	backtest.md

積木是「條件組合」不是「查數據」。 拿積木回答事實問題常常找不到剛好對的，或找到名稱像但語意不同的——例如 漲跌幅介於P1%到P2%之間 其實算的是近 20 日 漲跌幅，不是當日。見 block-caveats.md 第 12 節。

Manual Sample Input/Output

Example 1：登入

input

import snowyowl as so
api = so.login('user@x.com', 'pwd')
api

output

[系統訊息] MSMP 物件初始化完成。
[系統訊息] USMSMP 物件初始化完成。
[系統訊息] 已將資料存入本地暫存
[系統訊息] Block 積木物件初始化完成。
[系統訊息] API 加載完成，歡迎使用。

Api Instance is ready

Example 2：查一個事實（最短路徑）

input

k = api.MSMP.日_K              # index 是日期，columns 是股票代號
t = k.漲跌幅.iloc[-1].dropna()  # 最後一個交易日的漲跌幅
len(t[t >= 5]), str(k.Close.index[-1].date())

output

(89, '2026-08-20')

回答時要講資料日期。 api.MSMP 只到前一交易日——使用者說「今天」通常指的是最近一個交易日，用 k.Close.index[-1] 取出來明講。

Example 3：選一次股

input

block = api.Block.con_tw('今日收盤價<>開高低P%',
                         operator='>', ohlc_field='adj_High', percent=3)
result = api.Block.screener_tw([block])
result['date'], result['dataframe'].shape

output

(Timestamp('2026-08-20 00:00:00'), (2416, 8))

screener_tw 回傳 dict，四個 key：code / dataframe / date / sig。詳見 Block.screener 執行選股。

Example 4：取單一標的的歷史資料

input

api.Data.get('還原日K價量資料(個股、ETF、大盤)-單檔股票多個區間', '2330').tail(3)

output

DataFrame shape: (1000, 14)

            日期  股票代號 股票名稱  開盤價  最高價  最低價  收盤價        成交量  漲跌  漲跌幅(%)
997 2026-08-18  2330  台積電 2415 2415 2375 2380 19997.2130 -20 -0.8300
998 2026-08-19  2330  台積電 2340 2355 2335 2350 23618.6120 -30 -1.2600
999 2026-08-20  2330  台積電 2365 2375 2350 2375 16967.7370  25  1.0600

日頻一律 1000 筆（約 4.1 年），api.MSMP 與 api.Data 都一樣。要更長的歷史得降頻——週／月／季／年頻回溯 11~16 年。見 data-history.md。

命名空間

命名空間	用途	文件
`api.Block`	積木選股（台股 405 個、美股 260 個）	block.md 起 10 頁
`api.Data` / `api.USData`	表格式查詢（台股 80 張表、美股 25 張）	data.md、usdata.md
`api.MSMP` / `api.USMSMP`	矩陣式歷史資料（日期 × 股票代號）	msmp.md、msmp-tables.md
`api.bt`	回測	backtest.md 起 5 頁

snowyowl 沒有下單功能，api 上不存在 Order。詳見 api-structure.md。

文件怎麼查

想知道	看
撞到錯誤訊息	errors.md（含 13 項「不報錯但結果是錯的」）
有哪些積木、參數怎麼填	block-get-table.md、block-reference-tw.md
積木有哪些已知落差	block-caveats.md（12 節）
台股 80 張表按用途分組	data-get-table.md
某個頻率有多長歷史 / 期貨資料在哪	data-history.md
MSMP 每張表有哪些欄位	msmp-tables.md
寫策略、成交價規則、報表欄位	backtest-strategy.md、backtest-order.md、backtest-report.md

全部 34 篇的索引在 llms.txt，全文串接在 llms-full.txt。

三個最常踩的坑

1. 單位。 _千 結尾 ÷1e5 得億元、_百萬 結尾 ÷1e4 得億元。成交量：整股是張、零股是股、期貨是口。

2. 日頻只有 1000 筆。 「近五年」以上的問題要降到週／月／季頻。

3. SnowyOwl 沒有的資料：選擇權、匯率、央行利率、原物料、海外期貨。表裡出現的「匯率」是財報的「匯率變動對現金之影響」、「利率」是殖利率／毛利率這類財務比率——都不是行情。