紀錄工作經驗、相關知識,解決技術相關問題。

財商

美股指數 API Python 串接教學:Alpha Vantage 與 yfinance 抓取歷史日線數據範本

美股指數 API Python 串接教學:Alpha Vantage 與 yfinance 抓取歷史日線數據範本 特色圖片

在進行量化交易、投資組合回測或財經資訊面板開發時,工程師經常需要穩定且高效率的管道來取得美股三大指數(S&P 500、Dow Jones、Nasdaq)的即時與歷史價格。

本篇將深入探討如何運用 美股指數 API Python 程式碼範本,分別透過 yfinance 與 Alpha Vantage 抓取 OHLCV 歷史資料,並解決速率限制(Rate Limit)與時區對齊等常見工程難題。

兩者的定位不同:yfinance 是社群維護的開源套件,與 Yahoo 並無隸屬關係;Alpha Vantage 則是提供官方 API 與金鑰的資料商。文中的「即時」依各來源的授權與延遲而定,請以下方規格對照為準。

一、 核心語法速查與規格對照

在開發財經數據自動化腳本時,選擇合適的資料來源至關重要。以下提供直接可用的 yfinance 基本抓取範本,並整理主流美股指數 API 的規格對照表:

import yfinance as yf
import pandas as pd

# 抓取 S&P 500 (^GSPC)、Dow Jones (^DJI) 與 Nasdaq (^IXIC) 近 1 年日線數據
tickers = ["^GSPC", "^DJI", "^IXIC"]
data = yf.download(tickers, period="1y", interval="1d", group_by="ticker")

# 檢視 S&P 500 的近期收盤價
print(data["^GSPC"]["Close"].tail())
API 來源授權與費用Rate Limit 限制指數資料與即時性
yfinance開源(Apache-2.0),與 Yahoo 無隸屬關係;README 註明僅供研究與教育用途,Yahoo finance API 僅限個人使用無官方公布的請求上限數字;請求過於頻繁時,套件原始碼定義了 YFRateLimitError(Too Many Requests)可直接用 ^GSPC、^DJI、^IXIC 代號取得指數 OHLCV
Alpha Vantage提供免費與付費方案免費金鑰每日 25 次請求;驗證過的開源或教育專案可申請不限次數指數資料(INDEX_DATA,含 DJI、SPX、COMP)屬 premium 端點;免費金鑰可查詢股票與 ETF(例如 SPY)

二、 關鍵機制與跨情境細部拆解

1. 使用 yfinance 抓取 OHLCV 歷史資料與時區對齊

yfinance 能夠快速取得全球主要市場的歷史行情,但在處理多檔指數時,回傳的 Pandas DataFrame 常有多重索引(MultiIndex)結構。此外,yf.download 的日線資料預設回傳不帶時區(tz-naive)的索引,盤中資料則會轉成交易所時區;與本地資料庫或其他來源合併前,需先確認索引是否帶有時區,否則可能產生時間位移。

三張排成一列的日線價格表格,由一把長尺從下方橫貫,示意多檔指數資料對齊同一條時間軸
圖說:多檔指數的日線資料對齊同一條時間軸(示意圖,Gemini 生成)

透過 Pandas 進行時區轉換與交易日對齊的寫法如下:

import yfinance as yf
import pandas as pd

# 抓取標普 500 指數歷史資料
sp500 = yf.download("^GSPC", start="2025-01-01", end="2026-01-01")

# 確保索引為 DatetimeIndex;若不帶時區,先標示為美東時間,再統一轉為 UTC
sp500.index = pd.to_datetime(sp500.index)
if sp500.index.tz is None:
    sp500.index = sp500.index.tz_localize("America/New_York")
    
# 轉換為 UTC 時區以利資料庫儲存
sp500_utc = sp500.tz_convert("UTC")
print(sp500_utc.head())

2. Alpha Vantage API Key 申請與 JSON 回傳解析

當需要有官方文件與金鑰管理的 API 時,Alpha Vantage 是常見的選擇。開發者需先至官網申請免費的 API Key,並透過 requests 套件發送 HTTP 請求。

補充說明:Alpha Vantage 官方文件將 INDEX_DATA(指數資料)標示為 premium 端點。下列範例使用免費金鑰可呼叫的 TIME_SERIES_DAILY,查詢的是追蹤標普 500 的 ETF(SPY),並不是指數本身;outputsize=compact 只回傳最新 100 筆資料,full 僅限 premium 金鑰。

一個貼著黃銅鑰匙的信封,由虛線連到放著一疊紙張的服務櫃台,示意帶 API Key 發出請求並取回資料
圖說:帶著金鑰發出請求,取回 JSON 資料(示意圖,Gemini 生成)
import requests
import pandas as pd

API_KEY = "YOUR_ALPHA_VANTAGE_API_KEY"
url = f"https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol=SPY&outputsize=compact&apikey={API_KEY}"

response = requests.get(url)
data = response.json()

# 解析 Time Series (Daily) 節點
time_series = data.get("Time Series (Daily)", {})
df = pd.DataFrame.from_dict(time_series, orient="index")

# 重新命名欄位並調整資料型態
df = df.rename(columns={
    "1. open": "Open",
    "2. high": "High",
    "3. low": "Low",
    "4. close": "Close",
    "5. volume": "Volume"
})
df = df.astype(float)
df.index = pd.to_datetime(df.index)
df = df.sort_index()

print(df.tail())

三、 常見問題與排錯(Q&A)

1. 當使用 yfinance 批次抓取多檔美股指數時,頻繁遭遇 HTTP 429 Too Many Requests 錯誤該如何緩解?

  • 問題原因:yfinance 透過 Yahoo 公開的 API 取得資料,Yahoo 沒有公布請求上限;短時間內大量請求時,Yahoo 可能回應 HTTP 429(Too Many Requests),套件原始碼中對應的例外為 YFRateLimitError。
  • 解法:在程式碼中導入指數退避(Exponential Backoff)與 time.sleep() 緩衝機制。yf.download 失敗時通常只記錄錯誤並回傳空的 DataFrame,不一定丟出例外,因此範例在「空結果」與「例外」兩種情況都等待後重試:
import time
import random
import yfinance as yf

def fetch_with_backoff(ticker, retries=3, backoff_in_seconds=2):
    for attempt in range(retries):
        try:
            data = yf.download(ticker, period="5d", progress=False)
            if not data.empty:
                return data
        except Exception:
            pass
        sleep_time = backoff_in_seconds * (2 ** attempt) + random.uniform(0, 1)
        time.sleep(sleep_time)
    raise RuntimeError(f"無法成功抓取 {ticker} 數據,已達最大重試次數")

sp500_data = fetch_with_backoff("^GSPC")

2. Alpha Vantage 免費版每日 25 次請求限制下,如何設計本地端 SQLite 快取機制以避免重複消耗額度?

  • 問題原因:免費金鑰每日僅有 25 次請求,若開發階段頻繁重啟腳本會迅速耗盡當日配額。
  • 解法:使用 Python 內建的 sqlite3 與 Pandas 建立本地快取層,該代號已有快取資料時直接讀取 SQLite 資料表;SQL 以參數綁定(?)傳入代號,避免字串拼接。下列範例只判斷「有無快取」,若要依日期更新,需另行比對最新一筆日期:
import sqlite3
import pandas as pd
import requests

def get_cached_alpha_vantage_data(symbol, api_key):
    conn = sqlite3.connect("market_cache.db")
    query = "SELECT * FROM daily_prices WHERE symbol = ?"
    
    try:
        df_cached = pd.read_sql(query, conn, params=(symbol,), index_col="date")
        if not df_cached.empty:
            print("從本地 SQLite 快取載入資料")
            conn.close()
            return df_cached
    except Exception:
        pass

    # 若無快取則發送 API 請求
    url = f"https://www.alphavantage.co/query?function=TIME_SERIES_DAILY&symbol={symbol}&apikey={api_key}"
    res = requests.get(url).json()
    time_series = res.get("Time Series (Daily)", {})
    df = pd.DataFrame.from_dict(time_series, orient="index").astype(float)
    df.index = pd.to_datetime(df.index)
    df.index.name = "date"
    df["symbol"] = symbol
    
    # 寫入 SQLite
    df.to_sql("daily_prices", conn, if_exists="append", index=True)
    conn.close()
    return df

3. 使用 Python 解析 Alpha Vantage 回傳的 JSON 結構時,遇到欄位名稱包含特殊字元或隨日期間隔變動,如何強健地轉換為 Pandas DataFrame?

  • 問題原因:Alpha Vantage 回傳的 JSON 鍵名帶有數字編號與空格(如 "1. open"),且當切換為周線或月線時,根節點名稱會從 "Time Series (Daily)" 變更為 "Weekly Time Series"。
  • 解法:編寫動態鍵值檢索邏輯,過濾並標準化欄位名稱:
def parse_alpha_vantage_json(json_data):
    time_series_key = next((k for k in json_data.keys() if "Time Series" in k), None)
    if not time_series_key:
        raise ValueError("JSON 回傳結構異常,找不到 Time Series 節點")
    
    raw_data = json_data[time_series_key]
    df = pd.DataFrame.from_dict(raw_data, orient="index")
    
    # 動態清理欄位名稱
    df.columns = [col.split(". ")[1].capitalize() for col in df.columns if ". " in col]
    df = df.astype(float)
    df.index = pd.to_datetime(df.index)
    return df.sort_index()

4. yfinance 抓取到的即時與歷史價格資料,其時區轉換與交易日對齊在 Pandas 中該如何處理?

  • 問題原因:不同市場與指數的休市時間不一致,直接進行數學運算或合併(Merge)時常會因 NaN 導致對齊失敗。
  • 解法:利用 Pandas 的 reindex() 建立統一的日期索引後對齊。下列範例以週一至週五(freq="B")建立索引,不會排除美股休市日;若需嚴格的交易日,需另行引入交易日曆:
import pandas as pd

def align_trading_days(df):
    # 建立完整的交易日索引範圍
    full_idx = pd.date_range(start=df.index.min(), end=df.index.max(), freq="B")
    df_aligned = df.reindex(full_idx)
    
    # 針對缺失值進行前向填充(Forward Fill);休市日的值會沿用前一個交易日
    df_aligned["Close"] = df_aligned["Close"].ffill()
    return df_aligned

5. 在財經數據自動化腳本中,如何確保 API 金鑰在程式碼庫與環境變數中的安全性?

  • 問題原因:直接將 API Key 硬編碼(Hardcode)在 .py 檔案中容易因版控推送到 GitHub 而導致金鑰外洩。
  • 解法:使用環境變數與 python-dotenv 進行配置管理。
import os
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY")

if not API_KEY:
    raise EnvironmentError("未偵測到 ALPHA_VANTAGE_API_KEY 環境變數")

6. 當 Yahoo Finance 與 Alpha Vantage 提供的美股指數 OHLCV 資料出現價差或缺失值時,工程上應採用何種內插法進行清洗?

  • 問題原因:來源供應商之間的資料源清洗邏輯不同,可能導致特定交易日的開高收低出現微幅價差或缺漏。
  • 解法:對於短暫的缺失值,可使用 Pandas 的線性內插法(Linear Interpolation)進行補齊:
import pandas as pd

def clean_missing_prices(df):
    # 檢查並補齊缺失的 Close 價格
    df["Close"] = df["Close"].interpolate(method="linear")
    return df

參考資料與延伸閱讀

發佈留言