美股工具： SEC 官方財報數據庫與 secfsdstools 簡介

如果說各大財經 API 都是經過包裝的數據，那麼 SEC 官方提供的資料，就是最新鮮、最原始的「產地直送」。

在先前的文章中，我們介紹了許多方便的 API（如 FMP, yfinance, SimFin）。但如果你是一位想要徹底掌握數據源、不希望受制於第三方 API 限制或收費的量化開發者，直接去美國證券交易委員會 (SEC) 抓官方資料絕對是你的終極目標。

這篇文章將為你介紹 SEC 官方的 Financial Statement Data Sets，以及如何利用強大的 Python 工具 secfsdstools，將這些生硬的原始檔轉化為我們熟悉的 Pandas DataFrame。

為什麼要用 SEC 官方數據？

SEC 為了提高市場透明度，每季都會在官方網站釋出所謂的 Financial Statement Data Sets。這些資料集涵蓋了所有在美國上市的公司（使用 XBRL 標籤）提交的 10-Q (季報) 與 10-K (年報) 數據。

• 絕對免費與權威：這是最源頭的數據，沒有任何第三方的過濾或修改。
• 無頻率限制：你可以一次把過去十幾年的資料包全部下載下來存在硬碟。
• 最細緻的科目：商業 API 往往會把財報科目合併或簡化，而在 SEC 數據集裡，你可以看到公司財報上最原始、最細微的會計科目。

原始數據的痛點：極度硬核的資料結構

雖然寶藏就在那裡，但 SEC 提供的下載檔案是一堆以季度區分的 ZIP 壓縮檔。解壓縮後，你會看到幾百萬行的 .txt 檔案（主要是 sub.txt, num.txt, pre.txt）。

• sub.txt (Submission)：記載公司基本資料與提交報告的代號 (adsh)。
• num.txt (Number)：包含了所有的數字（資產多少、營收多少）。
• pre.txt (Presentation)：記載這些數字在財報上應該怎麼排序與呈現。

如果你想自己寫程式把這三張表 Join 起來，處理各種歷史版本的 XBRL 標籤變更，你大概會先崩潰。這就是為什麼我們需要 secfsdstools。

secfsdstools 簡介

secfsdstools 是一個專門用來處理 SEC Financial Statement Data Sets 的開源 Python 函式庫。它的核心設計理念就是幫你把上述那些髒活全部包辦：

1. 自動下載與更新：自動去 SEC 網站把 ZIP 檔載回來，並存入本地 SQLite 資料庫。
2. 自動關聯重組：自動將 sub、num、pre 表格關聯，並處理好索引。
3. 直出 DataFrame：提供簡潔的指令，讓你可以用股票代號 (Ticker) 一鍵抓出整理好的報表 DataFrame。

實戰演練：建立你的本地 SEC 數據庫

讓我們一步步在本地端建立這個強大的數據庫，並抓出蘋果公司 (AAPL) 的財報資料。

1. 安裝與初始化

首先，在終端機安裝套件：

pip install secfsdstools

2. 下載與建置本地數據庫

接下來，我們需要讓套件去下載 SEC 的歷史資料。建立一個 init_db.py 執行以下程式碼：

from secfsdstools.update import update

if __name__ == '__main__':
    print("開始初始化與下載 SEC 資料集，這可能需要幾十分鐘...")
    # 預設會在家目錄建立 .secfsdstools 設定檔與資料庫
    update()
    print("下載與解析完成！")

💡 數據儲存架構：你下載的數據到底存在哪裡？

剛打開建立好的 secfsdstools.db (SQLite 資料庫) 時會一頭霧水，因為裡面**「完全沒有財報數字」，只有公司基本資料與報告代號 (adsh)。這是因為套件採用了「圖書館系統（索引 + 本體分離）」**的雙層架構：

1. 索引層 (SQLite DB)：它就像是圖書館的「索書號系統」。只負責記錄「哪家公司在哪天發布了什麼報告代號」。
2. 數據層 (Parquet 格式)：真正的海量財報數字，被高度壓縮轉存到了 parquet 資料夾下。這就像是圖書館裡的「實體書本」，專為大數據的高速讀取而生。

當你後續用 Python 腳本查詢財報時，系統會先去 DB (櫃台) 查出報告代號，接著用閃電般的速度去 Parquet (書架) 抽出對應的財務數字。這就是它能在一秒內處理數千萬筆 SEC 數據的秘密！

3. 進階：透過 CIK 精準提取與三大表標準化 (以嬌生 JNJ 為例)

除了簡單的提取單一報表，secfsdstools 更強大的功能在於透過 CIK (中央索引鍵) 尋找最新的 10-K 年報，並利用 StandardStatementPresenter 將複雜的原始標籤標準化為易讀的格式。

以下這段程式碼展示了如何抓取嬌生 (Johnson & Johnson, CIK: 200406) 最新一期的現金流量表：

import pandas as pd
from secfsdstools.c_index.companyindexreading import CompanyIndexReader
from secfsdstools.e_collector.reportcollecting import SingleReportCollector
from secfsdstools.e_filter.rawfiltering import ReportPeriodAndPreviousPeriodRawFilter
from secfsdstools.e_presenter.presenting import StandardStatementPresenter

if __name__ == '__main__':
    # 1. 讀取嬌生 Index
    jnj_cik = 200406
    reader = CompanyIndexReader.get_company_index_reader(cik=jnj_cik)
    reports_df = reader.get_all_company_reports_df(forms=["10-K"])
    latest_adsh = reports_df.iloc[0].adsh  # 取得最新年報的報告代號
    
    print(f"找到 JNJ 最新 10-K 報表: {latest_adsh}")

    # 2. 萃取現金流量表並標準化
    cf_collector = SingleReportCollector.get_report_by_adsh(adsh=latest_adsh, stmt_filter=["CF"])
    cf_df = cf_collector.collect().filter(ReportPeriodAndPreviousPeriodRawFilter()).join().present(StandardStatementPresenter())

    # 3. 匯出 CSV 供後續 DCF 估值使用
    cf_df.to_csv("jnj_cash_flow.csv", index=False)
    print("成功匯出嬌生現金流量表！")

有了這份原汁原味的 CSV，我們就可以像專業分析師一樣，自己手動計算年複合成長率 (CAGR) 與 DCF 估值，再也不用盲目依賴第三方 API 的黑盒子數字了！

4. 實戰應用：從 SEC 原始數據計算 DCF

拿到上述 CSV 後，我們可以寫一段簡單的 Python 腳本來提取嬌生過去兩年的自由現金流 (FCF)，並進行 10 年期的 DCF 投射，藉此一窺那些昂貴的商業 API (如 FMP 算出的 $334.41) 背後的邏輯：

# 1. 提取歷史現金流並計算成長率
fcf_2024 = 19.842e9  # 2024 營運現金流 24.26B - 資本支出 4.42B
fcf_2023 = 18.248e9  # 2023 營運現金流 22.79B - 資本支出 4.54B
growth_rate = (fcf_2024 / fcf_2023) - 1  # 歷史 CAGR 約 8.7%

# 2. 設定 10 年期 DCF 模型參數 (模擬 FMP 環境)
wacc = 0.07          # 折現率 7% (因 JNJ 風險極低)
p_g = 0.025          # 永續成長率 2.5%
shares = 2.408e9     # 流通股數
net_debt = 30e9 - 24.105e9  # 淨負債 (總負債 - 帳上現金)

# 3. 進行 10 年期現金流投射
cf = fcf_2024
pv = 0
for i in range(1, 11):
    cf *= (1 + growth_rate)
    pv += cf / ((1 + wacc)**i)

# 4. 計算終值 (Terminal Value) 並折現
tv = (cf * (1 + p_g)) / (wacc - p_g)
pv += tv / ((1 + wacc)**10)

# 5. 計算每股合理價
dcf_price = (pv - net_debt) / shares
print(f"10 年期 DCF 估值: ${dcf_price:.2f}") # 結果約 $307.24

💡 分析洞察： 透過最源頭的 SEC 數據，我們算出 10 年期的 DCF 基準值大約是 **$307.24**。如果我們將折現率 WACC 微調至 `6.5$327 ~ $348** 之間。這完美破解了 FMP 雲端 API 算出 `$334.41` 的底層邏輯！這就是掌握原始數據、不盲信黑盒子的最強大威力。

總結：自己蓋水庫，還是開水龍頭？

到這邊，我們的「美股數據工具系列」介紹了三個不同層次的解決方案：

1. 商業 API (如 FMP)：就像「打開水龍頭」，只要付水費（月租），整理好的乾淨水（數據）就立刻流出來，最適合快速開發與即時看盤。
2. 開源套件 (如 yfinance)：像是「公有加水站」，免費好用，但如果一次提太多桶水可能會被限流，適合輕量級回測。
3. SEC + secfsdstools：就像「自己蓋水庫」。雖然前期建置管線（下載、設定）比較花時間，但一旦蓋好，水庫裡所有的原始數據都歸你完全掌控，要怎麼喝、怎麼過濾，全由你決定。

對於追求極致自由與深度的量化開發者或 AI 投資架構師而言，掌握 secfsdstools 絕對是你的必修課。